@deeeed/metamask-harness 0.34.2 → 0.34.3
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.
- package/CHANGELOG.md +11 -0
- package/dist/adapters.js +5 -2
- package/dist/recipe-security.js +1 -0
- package/library/actions/core/perps/_controller.mjs +75 -23
- package/library/actions/core/perps/read_account.mjs +6 -12
- package/library/actions/core/perps/read_snapshot.mjs +66 -0
- package/library/actions/extension/performance/_navigation-memory.mjs +372 -0
- package/library/actions/extension/performance/compare_idle_navigation_memory.mjs +18 -0
- package/library/actions/extension/performance/measure_detached_dom.mjs +18 -0
- package/library/actions/extension/performance/measure_navigation_memory.mjs +18 -0
- package/library/actions/mobile/app/network-control.mjs +24 -12
- package/library/manifests/core.action-manifest.json +55 -0
- package/library/manifests/extension.action-manifest.json +100 -0
- package/library/recipes/core/perps/snapshot.recipe.json +25 -0
- package/library/recipes/extension/performance/navigation-memory.recipe.json +175 -0
- package/package.json +1 -1
- package/scripts/site-contrast.mjs +39 -3
- package/site/architecture.html +22 -16
- package/site/assets/progress.mjs +1 -1
- package/site/assets/style.css +113 -1
- package/site/cheatsheet.html +14 -12
- package/site/how-it-works.html +693 -0
- package/site/index.html +70 -640
- package/site/perps.html +7 -6
- package/site/recipes.html +23 -17
- package/site/reviewers.html +7 -6
- package/site/tutorials/index.html +7 -6
- package/site/tutorials/v1.html +12 -11
- package/site/tutorials/v2.html +7 -6
- package/site/tutorials/v3.html +15 -11
- package/site/tutorials/v4.html +6 -5
- package/site/tutorials/v5.html +6 -5
- package/site/tutorials/v6.html +6 -5
- package/site/tutorials/v7.html +6 -5
|
@@ -0,0 +1,693 @@
|
|
|
1
|
+
<!DOCTYPE html>
|
|
2
|
+
<html lang="en">
|
|
3
|
+
<head>
|
|
4
|
+
<meta charset="utf-8">
|
|
5
|
+
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
6
|
+
<title>How it works — proving a change with a recipe</title>
|
|
7
|
+
<meta name="description" content="How a recipe proves a change on a real MetaMask build, checks itself before handoff, and stays behind as a regression guard. The full walkthrough, step by step.">
|
|
8
|
+
<link rel="stylesheet" href="assets/style.css">
|
|
9
|
+
</head>
|
|
10
|
+
<body data-progress-page="start">
|
|
11
|
+
<a class="skip" href="#steps">Skip to the walkthrough</a>
|
|
12
|
+
|
|
13
|
+
<header class="topbar">
|
|
14
|
+
<div class="wrap topbar-inner">
|
|
15
|
+
<a class="brand" href="index.html">
|
|
16
|
+
<span class="brand-mark" aria-hidden="true"></span>
|
|
17
|
+
<span class="brand-name">recipes</span>
|
|
18
|
+
</a>
|
|
19
|
+
<nav class="nav" aria-label="Main">
|
|
20
|
+
<a class="nav-cta" href="index.html#prompt">Quick start</a>
|
|
21
|
+
<a href="how-it-works.html" aria-current="page">How it works</a>
|
|
22
|
+
<a href="recipes.html">Recipe anatomy</a>
|
|
23
|
+
<a href="perps.html">Perps</a>
|
|
24
|
+
<a href="cheatsheet.html">Cheatsheet</a>
|
|
25
|
+
<a href="architecture.html">Architecture</a>
|
|
26
|
+
<a href="tutorials/index.html">Tutorials</a>
|
|
27
|
+
<a href="reviewers.html">For Reviewers</a>
|
|
28
|
+
</nav>
|
|
29
|
+
</div>
|
|
30
|
+
</header>
|
|
31
|
+
|
|
32
|
+
<div class="progress-rail">
|
|
33
|
+
<div class="wrap progress-inner">
|
|
34
|
+
<div class="progress-track" role="progressbar" aria-label="Walkthrough progress" aria-valuemin="0" aria-valuemax="100" aria-valuenow="0">
|
|
35
|
+
<div class="progress-fill"></div>
|
|
36
|
+
</div>
|
|
37
|
+
<span class="progress-label">0/8 steps</span>
|
|
38
|
+
<button type="button" class="progress-reset">Reset</button>
|
|
39
|
+
</div>
|
|
40
|
+
</div>
|
|
41
|
+
|
|
42
|
+
<main>
|
|
43
|
+
<section class="wrap hero">
|
|
44
|
+
<span class="eyebrow">How it works</span>
|
|
45
|
+
<h1>How a recipe earns trust.</h1>
|
|
46
|
+
<p class="lede">
|
|
47
|
+
A recipe is a graph of typed actions run against a real MetaMask build — Extension, Mobile, or
|
|
48
|
+
Core. It runs while the change is being written, so the work is proven as it is made rather than
|
|
49
|
+
hoped about and checked at the end. <code>mm-harness</code> is the runner. Everything below, in
|
|
50
|
+
order.
|
|
51
|
+
</p>
|
|
52
|
+
<div class="hero-meta">
|
|
53
|
+
<span>requires mm-harness 0.34+</span>
|
|
54
|
+
<span>~20 minutes</span>
|
|
55
|
+
<span>progress saves in this browser</span>
|
|
56
|
+
</div>
|
|
57
|
+
<p style="margin-top:.9rem;opacity:.7;font-size:.9rem;max-width:60ch">
|
|
58
|
+
A proposal for how agents can code at MetaMask — offered for teams to try, not an official standard.
|
|
59
|
+
</p>
|
|
60
|
+
</section>
|
|
61
|
+
|
|
62
|
+
<section class="wrap">
|
|
63
|
+
<div class="note plain">
|
|
64
|
+
<span class="note-title">Rather hand it to your agent?</span>
|
|
65
|
+
<p style="margin-bottom:0">
|
|
66
|
+
The <a href="index.html">front page</a> carries one prompt that goes further than this page:
|
|
67
|
+
it sets up the harness and the skills, then drives a real ticket through one.
|
|
68
|
+
</p>
|
|
69
|
+
</div>
|
|
70
|
+
</section>
|
|
71
|
+
|
|
72
|
+
<section class="wrap">
|
|
73
|
+
<h2 id="why">Why a recipe</h2>
|
|
74
|
+
<p>
|
|
75
|
+
<strong>Proof, as the change is made.</strong> The agent drives a real build, asserts what should
|
|
76
|
+
be true, and leaves a trace: which actions ran, what they returned, how many times. On-device
|
|
77
|
+
evidence, produced while the work is happening.
|
|
78
|
+
</p>
|
|
79
|
+
<p>
|
|
80
|
+
<strong>Self-checked in the same context.</strong> Replaying a recipe needs no fresh session, no
|
|
81
|
+
human, and no wait for CI. The agent does it mid-task, in the context it made the change in — so a
|
|
82
|
+
broken step surfaces while it is still cheap to fix.
|
|
83
|
+
</p>
|
|
84
|
+
<p>
|
|
85
|
+
<strong>Prevents regressions.</strong> The recipe outlives the change it was written for. Every
|
|
86
|
+
later change has to pass it too, so the same bug cannot quietly come back: a one-time check becomes
|
|
87
|
+
a permanent guard.
|
|
88
|
+
</p>
|
|
89
|
+
<p>
|
|
90
|
+
<strong>Trust.</strong> Proven, self-checked, and still proving — so the change is trustworthy
|
|
91
|
+
while it is being built, not hoped about and verified afterwards. Everything downstream, review
|
|
92
|
+
included, inherits that.
|
|
93
|
+
</p>
|
|
94
|
+
</section>
|
|
95
|
+
|
|
96
|
+
<section class="wrap">
|
|
97
|
+
<h2 id="fit">How it fits your work</h2>
|
|
98
|
+
<p>
|
|
99
|
+
You use this through the skills. A <strong>skill</strong> is the interface — the packaged workflow
|
|
100
|
+
an agent follows to fix a bug, build a feature, or review a pull request. The skill calls
|
|
101
|
+
<code>mm-harness</code> underneath, and what the harness runs is a <strong>recipe</strong>: the
|
|
102
|
+
executable proof that drives a real build, asserts, and leaves the evidence.
|
|
103
|
+
</p>
|
|
104
|
+
<p>You do not add proof to your work. Working through a skill is what produces it.</p>
|
|
105
|
+
|
|
106
|
+
<p class="stack-caption">Top is how you interact; each layer calls the one below.</p>
|
|
107
|
+
<div class="stack">
|
|
108
|
+
<div class="layer layer-static">
|
|
109
|
+
<span class="layer-n">1</span>
|
|
110
|
+
<span class="layer-name">Skills</span>
|
|
111
|
+
<span class="layer-sub">how you use it — fix a bug, build a feature, review a PR</span>
|
|
112
|
+
</div>
|
|
113
|
+
<div class="arrow" aria-hidden="true">↓</div>
|
|
114
|
+
<div class="layer layer-static">
|
|
115
|
+
<span class="layer-n">2</span>
|
|
116
|
+
<span class="layer-name">mm-harness</span>
|
|
117
|
+
<span class="layer-sub">what the skill calls underneath</span>
|
|
118
|
+
</div>
|
|
119
|
+
<div class="arrow" aria-hidden="true">↓</div>
|
|
120
|
+
<div class="layer layer-static">
|
|
121
|
+
<span class="layer-n">3</span>
|
|
122
|
+
<span class="layer-name">Recipe</span>
|
|
123
|
+
<span class="layer-sub">what the harness runs — on-device proof, kept as a regression guard</span>
|
|
124
|
+
</div>
|
|
125
|
+
</div>
|
|
126
|
+
|
|
127
|
+
<p>
|
|
128
|
+
So what you are adopting is not a testing tool. It is a way of working where the proof comes out
|
|
129
|
+
of doing the work rather than out of a separate step afterwards.
|
|
130
|
+
</p>
|
|
131
|
+
<p>
|
|
132
|
+
Skills come from two sources: the public <code>MetaMask/skills</code> repo, and the internal
|
|
133
|
+
<code>Consensys/skills</code> overlay, which needs access to that org. Both are cloned locally and
|
|
134
|
+
installed per checkout with <code>yarn skills</code>. You can drive the harness directly — the
|
|
135
|
+
walkthrough below does, and uses no skill — but skills are the path day to day.
|
|
136
|
+
<a href="architecture.html#stack">The full stack is on Architecture.</a>
|
|
137
|
+
</p>
|
|
138
|
+
</section>
|
|
139
|
+
|
|
140
|
+
<section class="wrap">
|
|
141
|
+
<h2 id="model">Two words</h2>
|
|
142
|
+
<p>
|
|
143
|
+
An <strong>action</strong> is one typed operation: unlock the wallet, press a button, read the
|
|
144
|
+
account state. A <strong>recipe</strong> is a JSON graph of actions. The steps below follow
|
|
145
|
+
<strong>discover → drive → prove</strong>, which is also the order you will work in from here on.
|
|
146
|
+
<code>mm-harness</code> is the runner, and it implements a versioned recipe specification —
|
|
147
|
+
<a href="architecture.html#spec">see Architecture</a>.
|
|
148
|
+
</p>
|
|
149
|
+
|
|
150
|
+
<div class="doctrine">
|
|
151
|
+
<p>
|
|
152
|
+
<span class="k">You never guess capabilities — you discover them.</span>
|
|
153
|
+
<code>mm-harness actions</code> prints what this checkout can do, and that list is law. The tool
|
|
154
|
+
refuses an invented action rather than improvising one, which is why its output is worth
|
|
155
|
+
trusting.
|
|
156
|
+
</p>
|
|
157
|
+
</div>
|
|
158
|
+
</section>
|
|
159
|
+
|
|
160
|
+
<section class="wrap">
|
|
161
|
+
<h2 id="steps">The walkthrough, step by step</h2>
|
|
162
|
+
<p>Each piece on its own, from an empty terminal to an evidence bundle. Checkboxes persist in this browser, so you can close the tab and come back.</p>
|
|
163
|
+
|
|
164
|
+
<ol class="steps">
|
|
165
|
+
|
|
166
|
+
<li class="step" data-step="install">
|
|
167
|
+
<div class="step-head">
|
|
168
|
+
<input type="checkbox" class="step-check" id="c-install" aria-labelledby="t-install">
|
|
169
|
+
<h3 class="step-title" id="t-install">Get the CLI</h3>
|
|
170
|
+
</div>
|
|
171
|
+
<p class="step-why">Both paths end with <code>mm-harness</code> on your PATH.</p>
|
|
172
|
+
|
|
173
|
+
<div class="grid grid-2" style="margin:1.2rem 0">
|
|
174
|
+
<div class="path-card">
|
|
175
|
+
<div class="path-tag">Path A — from zero</div>
|
|
176
|
+
<h4 style="margin:0 0 .5rem">No checkout yet</h4>
|
|
177
|
+
<p style="font-size:.92rem;color:var(--text-dim)">
|
|
178
|
+
Install below, then <code>mm-harness setup-base</code> clones the MetaMask product repos
|
|
179
|
+
into one standard layout and runs each repo's own dependency install. Use
|
|
180
|
+
<code>--dry-run</code> first to see the layout it would create.
|
|
181
|
+
</p>
|
|
182
|
+
<p style="margin-bottom:0"><span class="badge live">available now</span></p>
|
|
183
|
+
</div>
|
|
184
|
+
<div class="path-card">
|
|
185
|
+
<div class="path-tag">Path B — you already have a checkout</div>
|
|
186
|
+
<h4 style="margin:0 0 .5rem">Install and cd in</h4>
|
|
187
|
+
<p style="font-size:.92rem;color:var(--text-dim)">
|
|
188
|
+
Install globally, then work from inside the checkout. The product, ports, and runtime paths
|
|
189
|
+
are detected from where you are standing; there is no config file to write.
|
|
190
|
+
</p>
|
|
191
|
+
<p style="margin-bottom:0"><span class="badge live">available now</span></p>
|
|
192
|
+
</div>
|
|
193
|
+
</div>
|
|
194
|
+
|
|
195
|
+
<div class="cmd"><pre><code><span class="p">$ </span>npm i -g @deeeed/metamask-harness@latest
|
|
196
|
+
<span class="p">$ </span>mm-harness --version</code></pre></div>
|
|
197
|
+
|
|
198
|
+
<div class="out-label">Expected</div>
|
|
199
|
+
<div class="out">0.34.x <span class="dim">— any 0.34 or newer</span></div>
|
|
200
|
+
|
|
201
|
+
<p class="step-why">Everything from here runs inside a product checkout:</p>
|
|
202
|
+
<div class="cmd"><pre><code><span class="p">$ </span>cd ~/dev/metamask/metamask-extension <span class="dim"># or metamask-mobile, or core</span></code></pre></div>
|
|
203
|
+
|
|
204
|
+
<details class="fail">
|
|
205
|
+
<summary>If it fails</summary>
|
|
206
|
+
<div class="fail-body">
|
|
207
|
+
<p>
|
|
208
|
+
<strong><code>mm-harness: command not found</code></strong> — your global npm bin is not on
|
|
209
|
+
PATH. <code>npm prefix -g</code> prints the global prefix; add its <code>bin</code>
|
|
210
|
+
directory to your shell profile.
|
|
211
|
+
</p>
|
|
212
|
+
<p>
|
|
213
|
+
<strong>Older than 0.34</strong> — a stale global install is the most common source of
|
|
214
|
+
"the docs don't match my terminal". Run <code>mm-harness update</code>, or
|
|
215
|
+
<code>update --check</code> to look without installing.
|
|
216
|
+
</p>
|
|
217
|
+
</div>
|
|
218
|
+
</details>
|
|
219
|
+
</li>
|
|
220
|
+
|
|
221
|
+
<li class="step" data-step="doctor">
|
|
222
|
+
<div class="step-head">
|
|
223
|
+
<input type="checkbox" class="step-check" id="c-doctor" aria-labelledby="t-doctor">
|
|
224
|
+
<h3 class="step-title" id="t-doctor">Run doctor — and learn to read the errors</h3>
|
|
225
|
+
</div>
|
|
226
|
+
<p class="step-why">
|
|
227
|
+
A read-only readiness check that launches nothing and names the exact command that fixes each
|
|
228
|
+
finding.
|
|
229
|
+
</p>
|
|
230
|
+
|
|
231
|
+
<div class="cmd"><pre><code><span class="p">$ </span>mm-harness doctor</code></pre></div>
|
|
232
|
+
|
|
233
|
+
<div class="out-label">Expected — a checkout that needs one repair</div>
|
|
234
|
+
<div class="out"><span class="ok">pass</span> extension bridge present manifest=…/extension.action-manifest.json
|
|
235
|
+
harness: @deeeed/metamask-harness@0.34.x
|
|
236
|
+
runtime: decision=install (deps-missing) deps=missing webpack=down
|
|
237
|
+
Dependencies are not installed (no yarn install-state markers).
|
|
238
|
+
runtime-context: temp/recipe/runtime/agentic-runtime.json (<span class="bad">absent</span> — run mm-harness doctor --fix)
|
|
239
|
+
capture: <span class="ok">pass</span> (screenshots: capture-helper → cdp; video: capture-helper)
|
|
240
|
+
<span class="hint">Next: mm-harness launch --adapter extension --target '…'</span></div>
|
|
241
|
+
|
|
242
|
+
<div class="note">
|
|
243
|
+
<span class="note-title">The habit the toolchain is built around</span>
|
|
244
|
+
<p>
|
|
245
|
+
Every failure names one next action. Above, the finding tells you to run
|
|
246
|
+
<code>doctor --fix</code> and the <code>Next:</code> line says where to go once it passes.
|
|
247
|
+
Read the message and do what it says — that is also what lets an agent recover on its own
|
|
248
|
+
instead of guessing.
|
|
249
|
+
</p>
|
|
250
|
+
</div>
|
|
251
|
+
|
|
252
|
+
<p class="step-why">Do what it said:</p>
|
|
253
|
+
<div class="cmd"><pre><code><span class="p">$ </span>mm-harness doctor --fix</code></pre></div>
|
|
254
|
+
|
|
255
|
+
<div class="out-label">Expected — the finding is gone</div>
|
|
256
|
+
<div class="out"><span class="ok">pass</span> extension bridge present ready=true <span class="ok">fixed=[runtime-context]</span> failed=[]</div>
|
|
257
|
+
|
|
258
|
+
<p class="step-why">
|
|
259
|
+
<code>--fix</code> repairs runtime state the harness owns. It will not launch the app, invent
|
|
260
|
+
credentials, or pick a wallet fixture; those are your decisions, so it stops and asks.
|
|
261
|
+
</p>
|
|
262
|
+
|
|
263
|
+
<details class="fail">
|
|
264
|
+
<summary>If it fails</summary>
|
|
265
|
+
<div class="fail-body">
|
|
266
|
+
<p>
|
|
267
|
+
<strong><code>deps=missing</code></strong> — run <code>yarn install</code> as usual for
|
|
268
|
+
that repo. The harness does not manage your product repo's dependencies.
|
|
269
|
+
</p>
|
|
270
|
+
<p>
|
|
271
|
+
<strong>A finding you do not understand</strong> — <code>mm-harness doctor --json</code>
|
|
272
|
+
carries the same findings with structured detail, and is the form to paste to an agent or a
|
|
273
|
+
bug report.
|
|
274
|
+
</p>
|
|
275
|
+
<p>
|
|
276
|
+
<strong>Still failing after <code>--fix</code></strong> — <code>fixed=[…] failed=[…]</code>
|
|
277
|
+
separates the two. Anything in <code>failed</code> needs a human decision; the finding says
|
|
278
|
+
which.
|
|
279
|
+
</p>
|
|
280
|
+
</div>
|
|
281
|
+
</details>
|
|
282
|
+
</li>
|
|
283
|
+
|
|
284
|
+
<li class="step" data-step="launch">
|
|
285
|
+
<div class="step-head">
|
|
286
|
+
<input type="checkbox" class="step-check" id="c-launch" aria-labelledby="t-launch">
|
|
287
|
+
<h3 class="step-title" id="t-launch">Launch the app under harness control</h3>
|
|
288
|
+
</div>
|
|
289
|
+
<p class="step-why">
|
|
290
|
+
Starts the app and its dev server, installing the runtime overlay first if missing. Platform is
|
|
291
|
+
auto-detected. On iOS, pin one simulator UUID through provisioning and launch so duplicate device
|
|
292
|
+
names cannot select different simulators.
|
|
293
|
+
</p>
|
|
294
|
+
|
|
295
|
+
<div class="cmd"><pre><code><span class="p">$ </span>mm-harness launch --verify <span class="dim"># extension — fullscreen by default</span>
|
|
296
|
+
<span class="p">$ </span>xcrun simctl list devices available <span class="dim"># choose one iPhone UUID</span>
|
|
297
|
+
<span class="p">$ </span>mm-harness provision runway ios --device '<UUID>' --force
|
|
298
|
+
<span class="p">$ </span>xcrun simctl get_app_container '<UUID>' io.metamask.MetaMask app
|
|
299
|
+
<span class="p">$ </span>mm-harness launch ios --device '<UUID>' --verify
|
|
300
|
+
<span class="p">$ </span>mm-harness launch android --verify</code></pre></div>
|
|
301
|
+
|
|
302
|
+
<p class="step-why">
|
|
303
|
+
Quick relaunch is the default and reuses a healthy runtime. <code>--build</code> is the escape
|
|
304
|
+
hatch that always clean-builds; reach for it only when native or bundler output changed.
|
|
305
|
+
</p>
|
|
306
|
+
|
|
307
|
+
<div class="out-label">Core is headless — and says so</div>
|
|
308
|
+
<div class="out"><span class="bad">✗</span> mm-harness launch: core is headless; there is nothing to launch.
|
|
309
|
+
<span class="hint">Next: mm-harness verify</span></div>
|
|
310
|
+
<p class="step-why">
|
|
311
|
+
In <code>core</code> there is no UI to launch, so you get the equivalent step instead of a
|
|
312
|
+
silent failure. Run <code>mm-harness verify</code> and continue.
|
|
313
|
+
</p>
|
|
314
|
+
|
|
315
|
+
<details class="fail">
|
|
316
|
+
<summary>If it fails</summary>
|
|
317
|
+
<div class="fail-body">
|
|
318
|
+
<p>
|
|
319
|
+
<strong>Mobile: more than one device</strong> — the harness lists what it found rather than
|
|
320
|
+
guessing. Re-run with <code>--device <udid|serial></code>. Prefer the iOS UUID over a name,
|
|
321
|
+
because Xcode can contain several simulators with the same display name.
|
|
322
|
+
</p>
|
|
323
|
+
<p>
|
|
324
|
+
<strong>iOS app missing after provisioning</strong> — repeat the provision command with
|
|
325
|
+
<code>--force</code> and the same UUID. Do not use <code>--preflight-mode</code>; it is an
|
|
326
|
+
internal adapter flag, not a public <code>mm-harness launch</code> option.
|
|
327
|
+
</p>
|
|
328
|
+
<p>
|
|
329
|
+
<strong>Stuck</strong> — <code>mm-harness logs</code> tails the dev server and app logs;
|
|
330
|
+
<code>mm-harness status</code> shows the adapter, devices, and next command.
|
|
331
|
+
</p>
|
|
332
|
+
<p>
|
|
333
|
+
<strong>Clean slate</strong> — <code>mm-harness stop</code> stops only what this checkout
|
|
334
|
+
owns, so parallel checkouts are untouched. Stopping nothing is success.
|
|
335
|
+
</p>
|
|
336
|
+
</div>
|
|
337
|
+
</details>
|
|
338
|
+
</li>
|
|
339
|
+
|
|
340
|
+
<li class="step" data-step="actions">
|
|
341
|
+
<div class="step-head">
|
|
342
|
+
<input type="checkbox" class="step-check" id="c-actions" aria-labelledby="t-actions">
|
|
343
|
+
<h3 class="step-title" id="t-actions">Discover what this checkout can do</h3>
|
|
344
|
+
</div>
|
|
345
|
+
<p class="step-why">
|
|
346
|
+
Prints every typed operation available here, with its fields. The set differs per product:
|
|
347
|
+
Mobile has UI actions, Core is headless and has none.
|
|
348
|
+
</p>
|
|
349
|
+
|
|
350
|
+
<div class="cmd"><pre><code><span class="p">$ </span>mm-harness actions --categories</code></pre></div>
|
|
351
|
+
|
|
352
|
+
<div class="out-label">Expected — a mobile checkout, with its own counts</div>
|
|
353
|
+
<div class="out">analytics (4)
|
|
354
|
+
assertion (4)
|
|
355
|
+
control (4)
|
|
356
|
+
deeplink (1)
|
|
357
|
+
evidence (2)
|
|
358
|
+
perps (11)
|
|
359
|
+
runtime (4)
|
|
360
|
+
ui (13)
|
|
361
|
+
utility (1)
|
|
362
|
+
wallet (6)</div>
|
|
363
|
+
|
|
364
|
+
<p class="step-why">
|
|
365
|
+
Categories and counts move with the release and the adapter. Read yours from the command; the
|
|
366
|
+
shape is the point, not the numbers.
|
|
367
|
+
</p>
|
|
368
|
+
|
|
369
|
+
<p class="step-why">Then look inside a category, search, or inspect one action's fields:</p>
|
|
370
|
+
<div class="cmd"><pre><code><span class="p">$ </span>mm-harness actions --category ui
|
|
371
|
+
<span class="p">$ </span>mm-harness actions positions
|
|
372
|
+
<span class="p">$ </span>mm-harness actions --action read_state</code></pre></div>
|
|
373
|
+
|
|
374
|
+
<div class="doctrine">
|
|
375
|
+
<p>
|
|
376
|
+
<span class="k">The discovered list is law.</span> It is the capability boundary, not a
|
|
377
|
+
subset of some larger API. Call something not on it and the harness refuses, pointing you back
|
|
378
|
+
at discovery:
|
|
379
|
+
</p>
|
|
380
|
+
</div>
|
|
381
|
+
|
|
382
|
+
<div class="out"><span class="bad">✗</span> call: unknown action "totally_made_up" for the extension adapter.
|
|
383
|
+
<span class="hint">Next: mm-harness actions --adapter extension --json</span></div>
|
|
384
|
+
|
|
385
|
+
<p class="step-why">
|
|
386
|
+
That refusal is why the evidence is worth reading: a tool that invents an action when asked for
|
|
387
|
+
something impossible would also produce a plausible-looking result, and you would have no way to
|
|
388
|
+
tell. Add <code>--json</code> when feeding this to an agent.
|
|
389
|
+
</p>
|
|
390
|
+
|
|
391
|
+
<details class="fail">
|
|
392
|
+
<summary>If it fails</summary>
|
|
393
|
+
<div class="fail-body">
|
|
394
|
+
<p>
|
|
395
|
+
<strong>Fewer actions than expected</strong> — you are seeing only the bundled set. Team
|
|
396
|
+
libraries add domain actions and must be declared: <a href="tutorials/v3.html">V3</a>.
|
|
397
|
+
</p>
|
|
398
|
+
<p>
|
|
399
|
+
<strong>Wrong product detected</strong> — pass <code>--adapter mobile|extension|core</code>
|
|
400
|
+
explicitly, and check you are inside the checkout you meant.
|
|
401
|
+
</p>
|
|
402
|
+
</div>
|
|
403
|
+
</details>
|
|
404
|
+
</li>
|
|
405
|
+
|
|
406
|
+
<li class="step" data-step="call-read">
|
|
407
|
+
<div class="step-head">
|
|
408
|
+
<input type="checkbox" class="step-check" id="c-call-read" aria-labelledby="t-call-read">
|
|
409
|
+
<h3 class="step-title" id="t-call-read">Drive it: read product state</h3>
|
|
410
|
+
</div>
|
|
411
|
+
<p class="step-why">
|
|
412
|
+
<code>call</code> runs one action as a one-node recipe through the real engine — same execution
|
|
413
|
+
path, trace, and evidence as a full run. Start with a read; reads cannot break anything.
|
|
414
|
+
</p>
|
|
415
|
+
|
|
416
|
+
<div class="cmd"><pre><code><span class="p">$ </span>mm-harness call read_state</code></pre></div>
|
|
417
|
+
|
|
418
|
+
<div class="note blue">
|
|
419
|
+
<span class="note-title">Core branch</span>
|
|
420
|
+
<p>
|
|
421
|
+
Core has no wallet UI. Exercise its live controller boundary instead:
|
|
422
|
+
<code>mm-harness call read_positions mode=all</code>.
|
|
423
|
+
</p>
|
|
424
|
+
</div>
|
|
425
|
+
|
|
426
|
+
<p class="step-why">
|
|
427
|
+
Short names resolve when unambiguous: <code>read_state</code> finds
|
|
428
|
+
<code>metamask.wallet.read_state</code>. An ambiguous one stops and lists the candidates.
|
|
429
|
+
</p>
|
|
430
|
+
|
|
431
|
+
<div class="out-label">Expected — shape of the result</div>
|
|
432
|
+
<div class="out">call read_state: <span class="ok">pass</span>
|
|
433
|
+
Result:
|
|
434
|
+
{
|
|
435
|
+
"action": "metamask.wallet.read_state",
|
|
436
|
+
"state": {
|
|
437
|
+
"selectedAccount": { "name": "Account 1", "address": "0x…" },
|
|
438
|
+
"completedOnboarding": true
|
|
439
|
+
},
|
|
440
|
+
"redacted": true
|
|
441
|
+
}</div>
|
|
442
|
+
|
|
443
|
+
<p class="step-why">
|
|
444
|
+
Note <code>"redacted": true</code> — wallet state passes through redaction before reaching an
|
|
445
|
+
artifact, because these bundles get attached to pull requests.
|
|
446
|
+
</p>
|
|
447
|
+
|
|
448
|
+
<details class="fail">
|
|
449
|
+
<summary>If it fails</summary>
|
|
450
|
+
<div class="fail-body">
|
|
451
|
+
<p>
|
|
452
|
+
<strong>Runtime health check failed / CDP not reachable</strong> — the app is not running.
|
|
453
|
+
Complete the launch step; <code>mm-harness status</code> confirms what is live.
|
|
454
|
+
</p>
|
|
455
|
+
<p>
|
|
456
|
+
<strong>Mobile: more than one device</strong> — <code>call</code> fails fast and lists
|
|
457
|
+
them. Re-run with <code>--device</code>.
|
|
458
|
+
</p>
|
|
459
|
+
<p>
|
|
460
|
+
<strong><code>unknown action</code></strong> — not in this adapter's set.
|
|
461
|
+
<code>mm-harness call --list</code> shows what <code>call</code> accepts here.
|
|
462
|
+
</p>
|
|
463
|
+
</div>
|
|
464
|
+
</details>
|
|
465
|
+
</li>
|
|
466
|
+
|
|
467
|
+
<li class="step" data-step="call-ui">
|
|
468
|
+
<div class="step-head">
|
|
469
|
+
<input type="checkbox" class="step-check" id="c-call-ui" aria-labelledby="t-call-ui">
|
|
470
|
+
<h3 class="step-title" id="t-call-ui">Drive it again: UI or headless Core</h3>
|
|
471
|
+
</div>
|
|
472
|
+
<p class="step-why">Keep the app visible for this one.</p>
|
|
473
|
+
|
|
474
|
+
<div class="cmd"><pre><code><span class="p">$ </span>mm-harness call navigate page=perps</code></pre></div>
|
|
475
|
+
|
|
476
|
+
<div class="note blue">
|
|
477
|
+
<span class="note-title">Core branch</span>
|
|
478
|
+
<p>
|
|
479
|
+
Prove a second headless action instead:
|
|
480
|
+
<code>mm-harness call command cmd="echo core-ready"</code>.
|
|
481
|
+
</p>
|
|
482
|
+
</div>
|
|
483
|
+
|
|
484
|
+
<p class="step-why">
|
|
485
|
+
Fields are passed as <code>key=value</code>, or <code>--arg k=v</code> for the same effect.
|
|
486
|
+
</p>
|
|
487
|
+
|
|
488
|
+
<div class="note blue">
|
|
489
|
+
<span class="note-title">Semantic intent, not coordinates</span>
|
|
490
|
+
<p>
|
|
491
|
+
You asked for a <em>page</em>, not a pixel or a route. The adapter owns the mapping and
|
|
492
|
+
verifies where it landed, so a drifted route fails loudly instead of quietly doing nothing —
|
|
493
|
+
which is why these actions survive redesigns.
|
|
494
|
+
<code>mm-harness actions --action navigate</code> lists accepted values.
|
|
495
|
+
</p>
|
|
496
|
+
</div>
|
|
497
|
+
|
|
498
|
+
<p class="step-why">Others worth trying, if your adapter lists them:</p>
|
|
499
|
+
<div class="cmd"><pre><code><span class="p">$ </span>mm-harness call press text="Account 1"
|
|
500
|
+
<span class="p">$ </span>mm-harness call screenshot path=proof.png</code></pre></div>
|
|
501
|
+
|
|
502
|
+
<details class="fail">
|
|
503
|
+
<summary>If it fails</summary>
|
|
504
|
+
<div class="fail-body">
|
|
505
|
+
<p>
|
|
506
|
+
<strong>Target not found</strong> — the element is not on screen. Actions do not hunt
|
|
507
|
+
blindly; use <code>wait_for</code> when something needs to mount first.
|
|
508
|
+
</p>
|
|
509
|
+
<p>
|
|
510
|
+
<strong>Core has no UI actions</strong> — correct, it is headless. Try
|
|
511
|
+
<code>mm-harness call command cmd="echo hello"</code> there instead.
|
|
512
|
+
</p>
|
|
513
|
+
</div>
|
|
514
|
+
</details>
|
|
515
|
+
</li>
|
|
516
|
+
|
|
517
|
+
<li class="step" data-step="run">
|
|
518
|
+
<div class="step-head">
|
|
519
|
+
<input type="checkbox" class="step-check" id="c-run" aria-labelledby="t-run">
|
|
520
|
+
<h3 class="step-title" id="t-run">Prove it: run your first recipe</h3>
|
|
521
|
+
</div>
|
|
522
|
+
<p class="step-why">
|
|
523
|
+
Everything so far was driving by hand. A recipe composes the same operations into a graph that
|
|
524
|
+
runs identically every time and records what happened. Start with what ships:
|
|
525
|
+
</p>
|
|
526
|
+
|
|
527
|
+
<div class="cmd"><pre><code><span class="p">$ </span>mm-harness run --list</code></pre></div>
|
|
528
|
+
|
|
529
|
+
<div class="out-label">Expected — an extension checkout</div>
|
|
530
|
+
<div class="out">runnable recipes (extension)
|
|
531
|
+
Inspect: mm-harness run <recipe> --describe
|
|
532
|
+
perps.clean-market-testnet [metamask] variant=all params=market — Converge one Perps testnet market…
|
|
533
|
+
perps.lifecycle [metamask] variant=all — Opens a small ETH testnet position, verifies it, closes it…
|
|
534
|
+
perps.smoke [metamask] variant=extension — Non-mutating Perps domain smoke…
|
|
535
|
+
runner.action-validation [metamask] variant=extension — Exercises every manifest-declared action…
|
|
536
|
+
runner.smoke [metamask] variant=extension — Proves the runner executes manifest-declared actions…
|
|
537
|
+
wallet.smoke [metamask] variant=extension — Fixture-backed proof that the wallet is reachable…</div>
|
|
538
|
+
<p class="step-why">
|
|
539
|
+
The bundled set grows between releases; yours is whatever this command prints, not what is
|
|
540
|
+
printed here.
|
|
541
|
+
</p>
|
|
542
|
+
|
|
543
|
+
<p class="step-why">
|
|
544
|
+
Read one first. <code>--describe</code> shows its parameters and every action it composes:
|
|
545
|
+
</p>
|
|
546
|
+
<div class="cmd"><pre><code><span class="p">$ </span>mm-harness run wallet.smoke --describe
|
|
547
|
+
<span class="p">$ </span>mm-harness run wallet.smoke --plan</code></pre></div>
|
|
548
|
+
|
|
549
|
+
<p class="step-why">
|
|
550
|
+
<code>--plan</code> validates and prints the execution plan while touching nothing, exiting 5 if
|
|
551
|
+
the recipe is invalid. Cheap check before the expensive one.
|
|
552
|
+
</p>
|
|
553
|
+
|
|
554
|
+
<p class="step-why">Now for real, with the evidence somewhere you chose:</p>
|
|
555
|
+
<div class="cmd"><pre><code><span class="p">$ </span>mm-harness run wallet.smoke --artifacts-dir ./first-recipe-artifacts</code></pre></div>
|
|
556
|
+
|
|
557
|
+
<div class="out-label">Expected</div>
|
|
558
|
+
<div class="out"><span class="ok">PASS</span> recipe run [extension]
|
|
559
|
+
summary:
|
|
560
|
+
<span class="ok">PASS</span> status (app.status, 9ms): platform=extension
|
|
561
|
+
<span class="ok">PASS</span> fixture (metamask.wallet.fixture_status, 17ms): path=temp/recipe/runtime/wallet-fixture.json
|
|
562
|
+
<span class="ok">PASS</span> unlock (metamask.wallet.ensure_unlocked, 100ms): proof=extension-unlocked-state
|
|
563
|
+
<span class="ok">PASS</span> state (metamask.wallet.read_state, 94ms): proof=extension-wallet-state
|
|
564
|
+
<span class="ok">PASS</span> screenshot (ui.screenshot, 6.0s): path=screenshots/wallet-smoke.png
|
|
565
|
+
<span class="ok">PASS</span> done (end, 0ms)
|
|
566
|
+
artifacts (6):
|
|
567
|
+
Human run report: ./first-recipe-artifacts/report.md
|
|
568
|
+
Run summary: ./first-recipe-artifacts/summary.json
|
|
569
|
+
Execution trace: ./first-recipe-artifacts/trace.json
|
|
570
|
+
Executed recipe: ./first-recipe-artifacts/recipe.json
|
|
571
|
+
<span class="dim">…</span></div>
|
|
572
|
+
|
|
573
|
+
<div class="note">
|
|
574
|
+
<span class="note-title">Wallet fixtures</span>
|
|
575
|
+
<p>
|
|
576
|
+
Recipes needing a signed-in wallet read one canonical fixture per checkout; the password comes
|
|
577
|
+
<em>from</em> the fixture and is never typed. On a missing fixture,
|
|
578
|
+
<code>mm-harness fixtures</code> shows its status and the safe next command.
|
|
579
|
+
<code>fixtures init --dev</code> creates a disposable public test wallet that must never hold
|
|
580
|
+
real funds.
|
|
581
|
+
</p>
|
|
582
|
+
</div>
|
|
583
|
+
|
|
584
|
+
<details class="fail">
|
|
585
|
+
<summary>If it fails</summary>
|
|
586
|
+
<div class="fail-body">
|
|
587
|
+
<p>
|
|
588
|
+
<strong>Exit 5</strong> — validation or trust failure. The recipe is the problem, not your
|
|
589
|
+
environment; nothing executed. The message names the invalid part.
|
|
590
|
+
</p>
|
|
591
|
+
<p>
|
|
592
|
+
<strong>Exit 1</strong> — it ran and an action failed. A real result, not a tooling
|
|
593
|
+
problem: find the first node in <code>trace.json</code> with <code>"ok": false</code>.
|
|
594
|
+
</p>
|
|
595
|
+
<p>
|
|
596
|
+
<strong>Exit 3</strong> — infrastructure, not your recipe: the app or dev server fell over.
|
|
597
|
+
Try <code>mm-harness doctor</code> then <code>mm-harness logs</code>.
|
|
598
|
+
</p>
|
|
599
|
+
<p>
|
|
600
|
+
<strong>Lost track</strong> — <code>mm-harness last</code> prints the last significant
|
|
601
|
+
command with its verdict and evidence paths.
|
|
602
|
+
</p>
|
|
603
|
+
</div>
|
|
604
|
+
</details>
|
|
605
|
+
</li>
|
|
606
|
+
|
|
607
|
+
<li class="step" data-step="evidence">
|
|
608
|
+
<div class="step-head">
|
|
609
|
+
<input type="checkbox" class="step-check" id="c-evidence" aria-labelledby="t-evidence">
|
|
610
|
+
<h3 class="step-title" id="t-evidence">Open the evidence bundle</h3>
|
|
611
|
+
</div>
|
|
612
|
+
<p class="step-why">The run left a directory behind. This is the part that beats clicking through by hand.</p>
|
|
613
|
+
|
|
614
|
+
<div class="cmd"><pre><code><span class="p">$ </span>ls first-recipe-artifacts
|
|
615
|
+
<span class="p">$ </span>cat first-recipe-artifacts/summary.json
|
|
616
|
+
<span class="p">$ </span>open first-recipe-artifacts/screenshots</code></pre></div>
|
|
617
|
+
|
|
618
|
+
<div class="table-scroll">
|
|
619
|
+
<table>
|
|
620
|
+
<thead><tr><th>File</th><th>What it answers</th></tr></thead>
|
|
621
|
+
<tbody>
|
|
622
|
+
<tr><td><code>summary.json</code></td><td>Did it pass? How many nodes, how long, which libraries were in play. The verdict.</td></tr>
|
|
623
|
+
<tr><td><code>trace.json</code></td><td>What happened at every step: per-node verdict, timing, inputs, outputs. Counts come from here.</td></tr>
|
|
624
|
+
<tr><td><code>recipe.json</code></td><td>The graph that actually executed, including each node's stated intent.</td></tr>
|
|
625
|
+
<tr><td><code>report.md</code></td><td>The same story in one readable page — the thing to skim first.</td></tr>
|
|
626
|
+
<tr><td><code>screenshots/</code></td><td>Visual evidence captured during the run.</td></tr>
|
|
627
|
+
<tr><td><code>diagnostics.json</code></td><td>Warnings and errors the app emitted, kept deliberately separate from the verdict.</td></tr>
|
|
628
|
+
</tbody>
|
|
629
|
+
</table>
|
|
630
|
+
</div>
|
|
631
|
+
|
|
632
|
+
<p class="step-why">
|
|
633
|
+
Read them in that order: <code>report.md</code>, then <code>summary.json</code> for the verdict,
|
|
634
|
+
then <code>trace.json</code> when you want to know why. Cite numbers from
|
|
635
|
+
<code>trace.json</code>, never from prose written around it.
|
|
636
|
+
</p>
|
|
637
|
+
|
|
638
|
+
<div class="btn-row" style="margin-top:1.2rem">
|
|
639
|
+
<a class="btn btn-primary" href="reviewers.html">Read a bundle line by line →</a>
|
|
640
|
+
</div>
|
|
641
|
+
|
|
642
|
+
<details class="fail">
|
|
643
|
+
<summary>If it fails</summary>
|
|
644
|
+
<div class="fail-body">
|
|
645
|
+
<p>
|
|
646
|
+
<strong>Cannot find the directory</strong> — without <code>--artifacts-dir</code> it goes
|
|
647
|
+
to a checkout-local run directory. <code>mm-harness last</code> prints the path.
|
|
648
|
+
</p>
|
|
649
|
+
<p>
|
|
650
|
+
<strong>No screenshots</strong> — capture differs per platform;
|
|
651
|
+
<code>mm-harness doctor</code> reports it on a <code>capture:</code> line. A degraded
|
|
652
|
+
fallback still succeeds and records that it degraded in the artifact metadata.
|
|
653
|
+
</p>
|
|
654
|
+
</div>
|
|
655
|
+
</details>
|
|
656
|
+
</li>
|
|
657
|
+
|
|
658
|
+
</ol>
|
|
659
|
+
</section>
|
|
660
|
+
|
|
661
|
+
<section class="wrap">
|
|
662
|
+
<hr class="sep">
|
|
663
|
+
<h2>Next</h2>
|
|
664
|
+
<div class="grid grid-3">
|
|
665
|
+
<div class="card">
|
|
666
|
+
<h3>What a recipe is</h3>
|
|
667
|
+
<p>The graph, the intents, the assertions, and the test of whether yours is worth keeping.</p>
|
|
668
|
+
<p><a href="recipes.html">Recipes →</a></p>
|
|
669
|
+
</div>
|
|
670
|
+
<div class="card">
|
|
671
|
+
<h3>Your team's library</h3>
|
|
672
|
+
<p>Install the skills, declare your library, prove discovery sees it.</p>
|
|
673
|
+
<p><a href="tutorials/v3.html">Tutorial V3 →</a></p>
|
|
674
|
+
</div>
|
|
675
|
+
<div class="card">
|
|
676
|
+
<h3>Reviewing someone's proof</h3>
|
|
677
|
+
<p>A real bundle annotated, including a degraded capture that stayed honest about it.</p>
|
|
678
|
+
<p><a href="reviewers.html">For reviewers →</a></p>
|
|
679
|
+
</div>
|
|
680
|
+
</div>
|
|
681
|
+
</section>
|
|
682
|
+
</main>
|
|
683
|
+
|
|
684
|
+
<footer class="footer">
|
|
685
|
+
<div class="wrap">
|
|
686
|
+
<p>Internal getting-started guide for proving MetaMask changes with recipes. Not official MetaMask product documentation.</p>
|
|
687
|
+
<p>Commands here are checked against the CLI's own <code>--help</code>. If one disagrees with your terminal, your terminal is right: run <code>mm-harness update</code>, then trust <code>--help</code>.</p>
|
|
688
|
+
</div>
|
|
689
|
+
</footer>
|
|
690
|
+
|
|
691
|
+
<script type="module" src="assets/progress.mjs"></script>
|
|
692
|
+
</body>
|
|
693
|
+
</html>
|