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/architecture.html ADDED Viewed

@@ -0,0 +1,415 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Architecture — how the pieces fit</title>
+<meta name="description" content="Skills, mm-harness, team recipe libraries, product repos: what lives where, the three workflows, and the mistakes newcomers make.">
+<link rel="stylesheet" href="assets/style.css">
+</head>
+<body data-progress-page="architecture">
+<a class="skip" href="#stack">Skip to the stack map</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">Recipes</a>
+      <a href="cheatsheet.html">Cheatsheet</a>
+      <a href="architecture.html" aria-current="page">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 stack</span>
+  <h1>How the pieces fit together</h1>
+  <p class="lede">
+    Four moving parts, two of which people routinely confuse. What each layer is, where it lives, which
+    workflow you are in, and the mistakes that cost newcomers their first afternoon.
+  </p>
+</section>
+<section class="wrap">
+  <h2 id="model">The one-paragraph model</h2>
+  <div class="doctrine">
+    <p>
+      <span class="k">A recipe proves a task with actions.</span> Recipes are JSON graphs of typed
+      actions; <code>mm-harness</code> executes them against a real app and produces an evidence bundle
+      a reviewer can trust. <strong>Skills</strong> teach an agent a workflow — author a recipe, review
+      a PR, validate a release. <strong>Recipe libraries</strong> hold each team's recipes and domain
+      actions. Compose in that order, against the product repo under test.
+    </p>
+  </div>
+</section>
+<section class="wrap">
+  <h2 id="stack">The layers</h2>
+  <p>Click a layer to see what it is responsible for and when you touch it.</p>
+  <div class="stack">
+    <button type="button" class="layer" aria-expanded="false" aria-controls="l-skills">
+      <span class="layer-n">1</span>
+      <span class="layer-name">Skills</span>
+      <span class="layer-sub">the workflow an agent follows</span>
+    </button>
+    <div class="layer-detail" id="l-skills" hidden>
+      <p>
+        A packaged workflow — author a recipe from a criterion, review a pull request, validate a
+        release — turning "figure it out" into a procedure with gates you can steer.
+      </p>
+      <p>
+        Skills live in the internal <code>Consensys/skills</code> repo, installed per checkout with that
+        repo's tooling. <strong>You do not need skills to run a recipe</strong>, only to have an agent
+        follow a proven workflow instead of improvising one.
+        <a href="tutorials/v3.html">V3 walks the install.</a>
+      </p>
+    </div>
+    <div class="arrow" aria-hidden="true">↓</div>
+    <button type="button" class="layer" aria-expanded="false" aria-controls="l-harness">
+      <span class="layer-n">2</span>
+      <span class="layer-name">mm-harness</span>
+      <span class="layer-sub">execution and evidence</span>
+    </button>
+    <div class="layer-detail" id="l-harness" hidden>
+      <p>
+        The CLI: launches the app, exposes the action vocabulary, executes recipe graphs against a real
+        build, writes the evidence. The only layer everyone needs, and the only one installed globally:
+      </p>
+      <div class="cmd"><pre><code><span class="p">$ </span>npm i -g @deeeed/metamask-harness@latest</code></pre></div>
+      <p style="margin-bottom:0">
+        It owns MetaMask runtime control and the domain capabilities; the generic graph engine and the
+        evidence schemas underneath it are separate packages it depends on.
+      </p>
+    </div>
+    <div class="arrow" aria-hidden="true">↓</div>
+    <button type="button" class="layer" aria-expanded="false" aria-controls="l-libs">
+      <span class="layer-n">3</span>
+      <span class="layer-name">Team recipe libraries</span>
+      <span class="layer-sub">your team's recipes and domain actions</span>
+    </button>
+    <div class="layer-detail" id="l-libs" hidden>
+      <p>
+        A team-owned repo of reusable recipes plus the domain actions they need. The harness ships a
+        bundled library so a fresh install can prove something immediately; your team's library is where
+        the recipes that matter to your work live.
+      </p>
+      <p>Libraries must be declared, or the harness only sees the bundled set:</p>
+      <div class="cmd"><pre><code><span class="p">$ </span>export RECIPE_LIBRARY_PATH="perps=$HOME/dev/my-recipe-library"
+<span class="p">$ </span>mm-harness run &lt;recipe&gt; --library perps=$HOME/dev/my-recipe-library</code></pre></div>
+      <p style="margin-bottom:0">
+        Each library carries its own setup notes — read those before running anything domain-specific.
+      </p>
+    </div>
+    <div class="arrow" aria-hidden="true">↓</div>
+    <button type="button" class="layer" aria-expanded="false" aria-controls="l-product">
+      <span class="layer-n">4</span>
+      <span class="layer-name">Product repos</span>
+      <span class="layer-sub">the thing under test</span>
+    </button>
+    <div class="layer-detail" id="l-product" hidden>
+      <p>
+        <code>metamask-extension</code>, <code>metamask-mobile</code>, and <code>core</code>. Recipes
+        execute against a real build, never a mock. Run <code>mm-harness</code> from inside the checkout
+        and it detects the product, ports, and runtime paths.
+      </p>
+      <p style="margin-bottom:0">
+        They differ, and the harness says so rather than pretending otherwise: Core is headless with
+        nothing to launch and no UI actions; Mobile carries video capture; Extension is screenshots
+        only.
+      </p>
+    </div>
+  </div>
+</section>
+<section class="wrap">
+  <h2 id="loop">The improvement loop</h2>
+  <p>The stack is arranged so each run can leave the next one better informed.</p>
+  <div class="doctrine">
+    <p>
+      <span class="k">Learnings are written, not collected.</span> The checklist an agent follows carries
+      a step instructing it to write what it learned as human-readable markdown, bundled beside the
+      execution plan and the evidence. A run ends with prose — what was hard, what surprised it, what
+      the next run should know — sitting next to the proof. A deliverable, not telemetry: nobody mines
+      traces for insight; the agent is asked and answers.
+    </p>
+  </div>
+  <h3>The chain</h3>
+  <div class="stack">
+    <div class="layer layer-static">
+      <span class="layer-n">1</span>
+      <span class="layer-name">A checklist step asks for learnings</span>
+      <span class="layer-sub">part of the execution plan</span>
+    </div>
+    <div class="arrow" aria-hidden="true">↓</div>
+    <div class="layer layer-static">
+      <span class="layer-n">2</span>
+      <span class="layer-name">The run writes learnings.md beside its evidence</span>
+      <span class="layer-sub">prose, in the run artifacts</span>
+    </div>
+    <div class="arrow" aria-hidden="true">↓</div>
+    <div class="layer layer-static">
+      <span class="layer-n">3</span>
+      <span class="layer-name">Curation promotes the durable ones</span>
+      <span class="layer-sub">a human decides what generalises</span>
+    </div>
+    <div class="arrow" aria-hidden="true">↓</div>
+    <div class="layer layer-static">
+      <span class="layer-n">4</span>
+      <span class="layer-name">They become team knowledge</span>
+      <span class="layer-sub">in the library, beside the recipes</span>
+    </div>
+    <div class="arrow" aria-hidden="true">↓</div>
+    <div class="layer layer-static">
+      <span class="layer-n">5</span>
+      <span class="layer-name">The next run loads it before acting</span>
+      <span class="layer-sub">discovery, not recall</span>
+    </div>
+  </div>
+  <p>
+    Step 3 is a person on purpose: a run produces plenty of true-but-local detail, and promoting all of
+    it buries what matters — the same judgement as deciding what belongs in a code comment.
+  </p>
+  <div class="note blue">
+    <span class="note-title">Where learnings collect</span>
+    <p>
+      Scrubbed packages from approved runs land in
+      <code>MetaMask/experimental-distributed-learnings</code>, a private append-only inbox — the same
+      repository as <code>experimental-agentic-learnings</code>, which was its earlier name and still
+      redirects. Capture records the observation, review later decides whether it warrants a proposal,
+      and proposals go to whichever repo owns the affected layer. Sharing is opt-in: without a local
+      <code>learning.config.json</code> a run stages locally and publishes nothing. Packages are
+      date-partitioned and the indexes are scaffolded, but only one day of runs has landed so far —
+      collection is beginning, so treat it as the destination rather than a corpus to read today.
+    </p>
+  </div>
+  <h3>What works today</h3>
+  <div class="table-scroll">
+    <table>
+      <thead><tr><th>Mechanism</th><th>Its part in the loop</th></tr></thead>
+      <tbody>
+        <tr>
+          <td>The evidence bundle</td>
+          <td>Produces the raw material. <code>diagnostics.json</code> in particular is where side findings land — application warnings and errors captured during the run, kept out of the verdict precisely so they survive as observations rather than being flattened into pass or fail.</td>
+        </tr>
+        <tr>
+          <td>Team recipe libraries</td>
+          <td>The place shared understanding accumulates. A recipe that encodes "get to a clean market first" <em>is</em> a piece of team knowledge, already reusable by everyone who declares the library.</td>
+        </tr>
+        <tr>
+          <td><code>mm-harness recipe-quality</code></td>
+          <td>Turns a review's verdicts into a quality artifact, so an assessment of a proof is itself a durable record rather than a comment that scrolls away.</td>
+        </tr>
+        <tr>
+          <td><code>mm-harness execution-template</code></td>
+          <td>Discovers, validates, and materialises shared agent checklists — a curated procedure written once and picked up by everyone, which is the loop working at the level of process.</td>
+        </tr>
+        <tr>
+          <td>Skills</td>
+          <td>The same idea for workflows. A skill is a procedure someone got right, packaged so nobody has to rediscover it.</td>
+        </tr>
+      </tbody>
+    </table>
+  </div>
+  <h3>Where this is heading</h3>
+  <p>
+    The gap is the middle of the loop: recipes and actions have a home in a team library; the sharper
+    things a run teaches you do not yet. Worth capturing:
+  </p>
+  <ul>
+    <li><strong>Gotchas</strong> — the non-obvious precondition that cost someone an afternoon, written down once.</li>
+    <li><strong>Screen maps</strong> — how a surface is actually reached and identified in the current build, so the next author is not re-deriving it.</li>
+    <li><strong>Flakes</strong> — the step known to be intermittent, with what is known about when and why, so an author can distinguish a real failure from a familiar one.</li>
+  </ul>
+  <p>
+    The intended shape is the one proven everywhere else here: <strong>discovery rather than
+    recall</strong>. Just as you ask the checkout what actions exist, you would ask what is already
+    known about a surface before authoring against it — a <code>knowledge</code> surface alongside
+    <code>actions</code> and <code>run --list</code>, resolving the way libraries already do, layered
+    most-specific-wins: yours, your team's, the workflow's, then defaults shipping with the harness
+    release so tool facts cannot drift out of date in a document nobody re-reads.
+  </p>
+  <p>
+    Entries stay small and curated: a short index of what exists and when to load it, topic files under
+    a size cap, each entry carrying a stable id and the same symptom → cause → what to do shape the
+    error messages use. Promotion happens through an ordinary reviewed pull request, so a human is in
+    the loop by construction.
+  </p>
+  <div class="note">
+    <span class="note-title">Being straight about status</span>
+    <p style="margin-bottom:0">
+      <strong>Not shipping yet.</strong> There is no <code>knowledge</code> command today, which is why
+      you will not find one in a copyable block on this page. Meanwhile the useful part is unblocked:
+      keep what your runs teach you in the library repo beside the recipes. Tooling makes it
+      discoverable later; writing it down is what makes it exist.
+    </p>
+  </div>
+  <div class="doctrine">
+    <p>
+      <span class="k">The skills teach the workflow; the knowledge teaches the product.</span> Runs
+      produce learnings, curation promotes them, discovery serves them to every run after.
+    </p>
+  </div>
+</section>
+<section class="wrap">
+  <h2 id="libraries">Where everything lives</h2>
+  <div class="table-scroll">
+    <table>
+      <thead><tr><th>What</th><th>Is</th><th>You need it when</th></tr></thead>
+      <tbody>
+        <tr>
+          <td><code>@deeeed/metamask-harness</code><br><span style="color:var(--text-faint);font-size:.85rem">the <code>mm-harness</code> CLI, on npm</span></td>
+          <td>The execution engine and evidence producer: <code>doctor</code>, <code>launch</code>, <code>actions</code>, <code>call</code>, <code>run</code>, <code>last</code>.</td>
+          <td><strong>Always.</strong> Install and update with <code>npm i -g @deeeed/metamask-harness@latest</code>.</td>
+        </tr>
+        <tr>
+          <td><code>Consensys/skills</code><br><span style="color:var(--text-faint);font-size:.85rem">internal repo</span></td>
+          <td>Agentic skills — recipe authoring, PR QA review, release validation. Installed into a checkout via that repo's tooling.</td>
+          <td>When you want an agent to follow a proven workflow instead of improvising one.</td>
+        </tr>
+        <tr>
+          <td>Team recipe libraries<br><span style="color:var(--text-faint);font-size:.85rem">e.g. the perps and money-movement libraries</span></td>
+          <td>Team-owned recipes, domain actions, and domain knowledge. Declared with <code>RECIPE_LIBRARY_PATH</code> or <code>--library</code>.</td>
+          <td>When running or authoring anything domain-specific. <a href="tutorials/v3.html#steps">V3 walks the setup</a> with the perps library as the worked example.</td>
+        </tr>
+        <tr>
+          <td>Product repos<br><span style="color:var(--text-faint);font-size:.85rem">extension · mobile · core</span></td>
+          <td>The thing under test. The harness runs against a real checkout and a real build.</td>
+          <td><strong>Always</strong> — there is nothing to prove without one.</td>
+        </tr>
+      </tbody>
+    </table>
+  </div>
+</section>
+<section class="wrap">
+  <h2 id="workflows">The three workflows — pick one, do not blend them</h2>
+  <p>Most confusion here is someone doing two at once. They need different setup and fail differently.</p>
+  <div class="grid grid-3">
+    <div class="card">
+      <h3>1 · Run an existing recipe</h3>
+      <p style="color:var(--text-dim);font-size:.92rem">No skills needed. This is the majority of daily use.</p>
+      <div class="cmd"><pre><code><span class="p">$ </span>mm-harness update
+<span class="p">$ </span>cd &lt;product checkout&gt;
+<span class="p">$ </span>export RECIPE_LIBRARY_PATH=&lt;name=path&gt;
+<span class="p">$ </span>mm-harness doctor
+<span class="p">$ </span>mm-harness launch
+<span class="p">$ </span>mm-harness run &lt;recipe&gt; \
+    --artifacts-dir ./out</code></pre></div>
+      <p style="margin-bottom:0;font-size:.92rem">Evidence lands in the artifacts dir. That is the whole workflow.</p>
+    </div>
+    <div class="card">
+      <h3>2 · Author a recipe</h3>
+      <p style="color:var(--text-dim);font-size:.92rem">For a specific acceptance criterion. Skills earn their keep here.</p>
+      <p style="font-size:.92rem">
+        Install the recipe-authoring skill. It discovers the vocabulary with
+        <code>mm-harness actions</code> — <strong>the discovered list is law, action names are never
+        invented</strong> — composes the graph, validates it with <code>run --plan</code>, then runs it
+        for real.
+      </p>
+      <p style="margin-bottom:0;font-size:.92rem">
+        Expect one honest failure-and-fix loop. That is the error messages doing their job.
+      </p>
+    </div>
+    <div class="card">
+      <h3>3 · Review a PR / validate a release</h3>
+      <p style="color:var(--text-dim);font-size:.92rem">Requires the QA skills.</p>
+      <p style="font-size:.92rem">
+        Give the skill one PR URL. It extracts the acceptance criteria verbatim — missing ones become a
+        hygiene finding, never an invented criterion — waits for you to confirm or edit the table, runs
+        the proof on a real device, and produces a per-criterion verdict with evidence paths.
+      </p>
+      <p style="margin-bottom:0;font-size:.92rem">
+        A criterion the surface genuinely cannot prove is reported as needing a human, not quietly
+        passed.
+      </p>
+    </div>
+  </div>
+  <div class="note blue">
+    <span class="note-title">Why "do not blend them" is a real instruction</span>
+    <p>
+      Running a recipe needs no skills; reviewing a PR does. Install everything and ask an agent to
+      "just handle it" and you get an agent choosing between procedures with no basis to pick. Name the
+      workflow you are in.
+    </p>
+  </div>
+</section>
+<section class="wrap">
+  <h2 id="mistakes">The five mistakes every newcomer makes</h2>
+  <ol style="padding-left:1.2rem">
+    <li style="margin-bottom:1rem">
+      <strong>Asking the agent to figure it all out from one sentence.</strong> The skills <em>are</em>
+      the figured-out part. Name the workflow you want; do not make the agent guess which of the three
+      you are in.
+    </li>
+    <li style="margin-bottom:1rem">
+      <strong>A stale harness.</strong> This one costs the most afternoons. The CLI ships often and
+      recipes assume current behaviour. Run <code>mm-harness update</code> before you debug anything
+      that "used to work".
+    </li>
+    <li style="margin-bottom:1rem">
+      <strong>Not declaring the library.</strong> Without <code>RECIPE_LIBRARY_PATH</code> (or
+      <code>--library</code>) the harness only sees bundled recipes — so your team's recipe appears not
+      to exist, and the error is telling the literal truth.
+    </li>
+    <li style="margin-bottom:1rem">
+      <strong>Skipping <code>doctor</code>.</strong> It tells you exactly what is missing and the exact
+      command that fixes it. Every error in this stack carries a <code>Next:</code> action. Read them —
+      that is the whole design.
+    </li>
+    <li>
+      <strong>Blending the workflows.</strong> See above. Mixing "run a recipe" with "review a PR"
+      confuses the agent and produces work you then have to check by hand.
+    </li>
+  </ol>
+  <hr class="sep">
+  <div class="btn-row">
+    <a class="btn btn-primary" href="index.html#steps">Do the walkthrough →</a>
+    <a class="btn btn-ghost" href="reviewers.html">Read an evidence bundle</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+.</p>
+  </div>
+</footer>
+<script type="module" src="assets/progress.mjs"></script>
+</body>
+</html>