@muggleai/works 5.18.0-staging.121 → 5.18.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.
- package/README.md +303 -508
- package/dist/release-manifest.json +3 -3
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,71 +1,68 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Muggle Works
|
|
2
2
|
|
|
3
|
-
**
|
|
3
|
+
**An open-source harness that drives your AI coding agent through the whole delivery cycle — design, build, test, acceptance — and closes the loop on GitHub and GitLab.**
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Coding agents are good at producing a diff. They are bad at knowing whether the diff works, whether it broke the login flow, and what still has to happen before a human can merge it. Muggle Works is the harness around the agent that answers those questions: it freezes requirements, delegates the design and build, runs the unit suite, drives a **real browser** through the affected user flows, opens the pull request with screenshots attached, and then keeps watching that PR — picking up review comments, red CI, and a stale base branch until the change is genuinely mergeable.
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
[
|
|
9
|
-
[
|
|
10
|
-
[
|
|
7
|
+
[](https://www.npmjs.com/package/@muggleai/works)
|
|
8
|
+
[](https://www.npmjs.com/package/@muggleai/works)
|
|
9
|
+
[](https://nodejs.org)
|
|
10
|
+
[](#mcp-tool-reference)
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
Works in Claude Code, Cursor, Codex, Windsurf, and any MCP client. Powered by [Muggle Test](https://www.muggletest.com).
|
|
13
13
|
|
|
14
14
|
---
|
|
15
15
|
|
|
16
|
-
##
|
|
16
|
+
## Highlights
|
|
17
17
|
|
|
18
|
-
|
|
18
|
+
- **One request, one pull request.** `/mdo "add a logout button"` runs requirements → design → build → impact analysis → unit tests → browser acceptance → PR. You answer one questionnaire up front, then walk away.
|
|
19
|
+
- **A real browser under a real identity.** Not a headless stub. Every managed login profile owns a live inbox, so magic links, emailed OTPs, email 2FA, verification mail, and password resets are all testable — no mail catcher, no test-only backdoor, no `SKIP_AUTH` flag.
|
|
20
|
+
- **GitHub and GitLab as peers.** Pull requests and merge requests, review threads and discussions, Actions and pipelines, signed commits on both. Self-hosted GitLab included — the provider is detected from the remote, not hardcoded.
|
|
21
|
+
- **The loop keeps running after you close the laptop.** A watcher polls the PR and re-enters the cycle when a reviewer comments, CI goes red, or the branch falls behind its base. Feedback becomes commits without you relaying it.
|
|
22
|
+
- **A gate, not a vibe.** No PR is opened until requirements are written, the build typechecks and lints, new logic carries unit tests, the suite passes, and a browser verdict is recorded — or a waiver reason is written down. Silence is not a waiver.
|
|
23
|
+
- **Plain English in, replayable scripts out.** Describe a flow in a sentence; get a script that persists across sessions and re-runs as a regression test after every change.
|
|
24
|
+
- **100+ MCP tools** if you'd rather assemble your own pipeline than use the packaged one.
|
|
19
25
|
|
|
20
|
-
|
|
26
|
+
### Built for two kinds of people
|
|
21
27
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
-
|
|
28
|
+
**If you write code for a living,** this is the discipline you'd apply yourself if you had the patience to apply it every time: frozen requirements, a Definition of Done that blocks the PR, evidence attached to the review, and a follow-up loop that doesn't forget.
|
|
29
|
+
|
|
30
|
+
**If you vibe-code,** this is the part you can't easily judge by reading the diff. You don't have to know Playwright, or what a fixture is, or why the checkout page broke on mobile. Describe the feature; the harness builds it, clicks through it like a user, shows you the screenshots, and tells you what failed in English.
|
|
31
|
+
|
|
32
|
+
---
|
|
33
|
+
|
|
34
|
+
## The cycle
|
|
35
|
+
|
|
36
|
+
| # | Stage | What it does | Evidence it leaves |
|
|
37
|
+
| :- | :---- | :----------- | :----------------- |
|
|
38
|
+
| 1 | Pre-flight | Detects repo, branch, dev server, project, credentials; asks everything it can't detect in **one** turn | `state.md` |
|
|
39
|
+
| 2 | Requirements | Freezes goal and acceptance criteria before a line is written | `requirements.md` |
|
|
40
|
+
| 3 | Build | Delegates real design surface to a design → plan → subagent build, then commits (signed) | Conventional commits |
|
|
41
|
+
| 4 | Impact analysis | Maps the diff to the user flows it can break | Affected-flow list |
|
|
42
|
+
| 5 | Unit tests | Runs the suite authored in stage 3 | Exit code |
|
|
43
|
+
| 6 | Acceptance | Drives a real browser through the affected flows | Verdict + `runId` + per-step screenshots |
|
|
44
|
+
| 7 | Pull request | Opens the PR/MR with the evidence block in the body | PR URL |
|
|
45
|
+
| 7.5 | Repair | Investigates and fixes acceptance failures, up to 3 iterations | Repair log |
|
|
46
|
+
| 8 | Watcher | Polls reviews, CI, and base-branch drift; re-enters the cycle on each | `followup.log` |
|
|
47
|
+
|
|
48
|
+
Stage 7 refuses to run until the Definition of Done holds. Stage 8 is dispatched only once stage 7.5 clears — a cycle with unrepaired failures never reaches a watcher.
|
|
25
49
|
|
|
26
50
|
---
|
|
27
51
|
|
|
28
|
-
## Quick
|
|
52
|
+
## Quick start
|
|
29
53
|
|
|
30
|
-
### 1. Install
|
|
54
|
+
### 1. Install
|
|
31
55
|
|
|
32
|
-
**Claude Code
|
|
56
|
+
**Claude Code** — full plugin: skills, MCP tools, and the browser runner.
|
|
33
57
|
|
|
34
58
|
```
|
|
35
59
|
/plugin marketplace add https://github.com/multiplex-ai/muggle-ai-works
|
|
36
60
|
/plugin install muggleai@muggle-works
|
|
37
61
|
```
|
|
38
62
|
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
- `/muggle:muggle` — command router and menu
|
|
42
|
-
- `/muggle:muggle-do` — autonomous dev pipeline (requirements to PR)
|
|
43
|
-
- `/muggle:muggle-test` — change-driven E2E acceptance testing (local or remote, with PR posting)
|
|
44
|
-
- `/muggle:muggle-test-feature-local` — local quick E2E acceptance testing
|
|
45
|
-
- `/muggle:muggle-test-prepare` — verify and start the dev servers a test run needs
|
|
46
|
-
- `/muggle:muggle-test-import` — import existing Playwright/Cypress specs, PRDs, or feature files
|
|
47
|
-
- `/muggle:muggle-test-regenerate-missing` — bulk-regenerate test scripts for every test case that has no active script
|
|
48
|
-
- `/muggle:muggle-browser-task` — perform a real action on a website from plain English
|
|
49
|
-
- `/muggle:muggle-pr-visual-walkthrough` — post screenshots and a pass/fail summary to a PR
|
|
50
|
-
- `/muggle:muggle-pr-followup` — watch a PR's review thread and address incoming feedback
|
|
51
|
-
- `/muggle:muggle-feedback` — flag a generated action script or step as wrong
|
|
52
|
-
- `/muggle:muggle-preferences` — view, set, or reset Muggle Test preferences
|
|
53
|
-
- `/muggle:muggle-status` — health check for muggle-works plugins (Electron app, MCP server, and auth)
|
|
54
|
-
- `/muggle:muggle-repair` — diagnose and fix broken installation
|
|
55
|
-
- `/muggle:muggle-upgrade` — update to the latest version
|
|
56
|
-
- short aliases for every command above — `/m`, `/mdo`, `/mtest`, `/mtestlocal`, `/mtestprep`, `/mimport`, `/mregen`, `/mbt`, `/mpr`, `/mprfollowup`, `/mfeedback`, `/mprefs`, `/mstatus`, `/mrepair`, `/mupgrade`
|
|
57
|
-
- MCP server with 70+ tools (auto-started)
|
|
58
|
-
- Electron browser test runner provisioning (via session hook)
|
|
59
|
-
|
|
60
|
-
**Cursor, Codex, Windsurf, and other MCP clients (MCP tools only)**
|
|
63
|
+
**Cursor** — `npm install -g @muggleai/works`. The postinstall writes `~/.cursor/mcp.json` and syncs the `muggle-*` skills into `~/.cursor/skills/`. Restart Cursor.
|
|
61
64
|
|
|
62
|
-
|
|
63
|
-
npm install -g @muggleai/works
|
|
64
|
-
```
|
|
65
|
-
|
|
66
|
-
For Cursor, that's it — the install automatically configures `~/.cursor/mcp.json` and syncs `muggle-*` skills to `~/.cursor/skills/`. Just restart Cursor.
|
|
67
|
-
|
|
68
|
-
For other MCP clients, add this to your client's config:
|
|
65
|
+
**Codex, Windsurf, any other MCP client** — install the package as above, then register the server:
|
|
69
66
|
|
|
70
67
|
```json
|
|
71
68
|
{
|
|
@@ -81,347 +78,92 @@ For other MCP clients, add this to your client's config:
|
|
|
81
78
|
}
|
|
82
79
|
```
|
|
83
80
|
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
### 2. Verify
|
|
87
|
-
|
|
88
|
-
**Claude Code**
|
|
81
|
+
### 2. Set up
|
|
89
82
|
|
|
83
|
+
```bash
|
|
84
|
+
muggle init
|
|
90
85
|
```
|
|
91
|
-
/muggle:muggle-status
|
|
92
|
-
```
|
|
93
|
-
|
|
94
|
-
This checks Electron browser test runner, MCP server health, and authentication. If anything is broken, run `/muggle:muggle-repair`.
|
|
95
|
-
|
|
96
|
-
**Cursor/Codex/Windsurf/other MCP clients**
|
|
97
|
-
|
|
98
|
-
Run any `muggle-*` MCP tool from your client after adding the MCP server config above. Authentication starts automatically on first protected tool call.
|
|
99
|
-
|
|
100
|
-
### 3. Start building features
|
|
101
86
|
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
Describe what you want to build:
|
|
87
|
+
Explains how the harness works, saves your preferences, and offers to install the pull-request walkthrough check. Then confirm the install is healthy:
|
|
105
88
|
|
|
106
89
|
```
|
|
107
|
-
/
|
|
90
|
+
/mstatus # Claude Code
|
|
91
|
+
muggle doctor # anywhere else
|
|
108
92
|
```
|
|
109
93
|
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
**Cursor/Codex/Windsurf/other MCP clients**
|
|
113
|
-
|
|
114
|
-
Use the direct MCP workflow section below to call `muggle-*` tools from your client.
|
|
115
|
-
|
|
116
|
-
### 4. Test a feature locally
|
|
117
|
-
|
|
118
|
-
**Claude Code**
|
|
94
|
+
Broken? `/mrepair`, or `muggle setup --force`.
|
|
119
95
|
|
|
120
|
-
|
|
96
|
+
### 3. Build something
|
|
121
97
|
|
|
122
98
|
```
|
|
123
|
-
/
|
|
99
|
+
/mdo "Add a logout button to the header"
|
|
124
100
|
```
|
|
125
101
|
|
|
126
|
-
Describe what to test in plain English. The AI finds or creates test cases, launches a real browser, and reports results with screenshots.
|
|
127
|
-
|
|
128
|
-
**Cursor/Codex/Windsurf/other MCP clients**
|
|
129
|
-
|
|
130
|
-
Call local execution MCP tools directly (for example `muggle-local-execute-test-script-replay` or related `muggle-local-*` commands exposed by your client).
|
|
131
|
-
|
|
132
|
-
---
|
|
133
|
-
|
|
134
|
-
## Architecture
|
|
135
|
-
|
|
136
|
-
muggle-ai-works separates test management from test execution. All entity management (projects, use cases, test cases) lives in the cloud via `muggle-remote-*` tools. Local execution (`muggle-local-*`) is stateless — it receives what it needs and runs the test.
|
|
137
|
-
|
|
138
|
-
### Entity model
|
|
139
|
-
|
|
140
102
|
```
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
103
|
+
PRE-FLIGHT → repo: frontend · branch: users/me/logout-button · target: localhost:3000
|
|
104
|
+
REQUIREMENTS → Goal: logout button in header. AC: visible, ends session, redirects to /login.
|
|
105
|
+
BUILD → src/components/Header.tsx, src/hooks/useLogout.ts (+ unit tests)
|
|
106
|
+
IMPACT → affects "User Login" and "Session" flows
|
|
107
|
+
UNIT TESTS → 12/12 pass
|
|
108
|
+
ACCEPTANCE → 3/3 test cases pass · runId a1b2c3 · 14 screenshots
|
|
109
|
+
PULL REQUEST → #42 opened, walkthrough posted
|
|
110
|
+
WATCHER → armed on #42
|
|
146
111
|
```
|
|
147
112
|
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
```
|
|
151
|
-
Your AI assistant describes what to test
|
|
152
|
-
│
|
|
153
|
-
v
|
|
154
|
-
muggle-remote-* tools create test cases in cloud
|
|
155
|
-
│
|
|
156
|
-
v
|
|
157
|
-
muggle-local-execute-test-generation launches the browser test runner
|
|
158
|
-
│
|
|
159
|
-
v
|
|
160
|
-
AI agent drives the browser step-by-step (click, type, navigate, assert)
|
|
161
|
-
│
|
|
162
|
-
v
|
|
163
|
-
Screenshots captured per step → action-script.json recorded
|
|
164
|
-
│
|
|
165
|
-
v
|
|
166
|
-
Results: pass/fail with evidence at ~/.muggle-ai/sessions/{runId}/
|
|
167
|
-
│
|
|
168
|
-
v
|
|
169
|
-
studio publishes the run to the cloud during execution → run result carries viewUrl to open dashboard
|
|
170
|
-
```
|
|
113
|
+
Authentication starts on the first protected call: a browser opens with a verification code, you sign in, and the call continues. Credentials persist in `~/.muggle-ai/`.
|
|
171
114
|
|
|
172
115
|
---
|
|
173
116
|
|
|
174
|
-
##
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
### 2. `/muggle:muggle-do` — Autonomous dev pipeline
|
|
196
|
-
|
|
197
|
-
Full development cycle: requirements to PR in one command. The AI codes the feature, writes unit tests, runs E2E acceptance tests against your running app, and opens a PR.
|
|
198
|
-
|
|
199
|
-
```
|
|
200
|
-
> /muggle:muggle-do "Add a logout button to the header"
|
|
201
|
-
|
|
202
|
-
REQUIREMENTS → Goal: Add logout button. Criteria: visible, functional, redirects.
|
|
203
|
-
IMPACT → frontend repo, src/components/Header.tsx
|
|
204
|
-
VALIDATE → Branch: feat/add-logout, 1 commit
|
|
205
|
-
CODING → (writes/fixes code)
|
|
206
|
-
UNIT_TESTS → 12/12 pass
|
|
207
|
-
E2E acceptance → 3/3 test cases pass
|
|
208
|
-
OPEN_PRS → PR #42 opened
|
|
209
|
-
DONE → 1 iteration, all green
|
|
210
|
-
```
|
|
211
|
-
|
|
212
|
-
- Session-based with crash recovery (`~/.muggle-ai/muggle-do/sessions/`)
|
|
213
|
-
- Auto-triage: analyzes failures and loops back to fix (max 3 iterations)
|
|
214
|
-
- Multi-repo support via `muggle-repos.json`
|
|
215
|
-
- PRs include E2E acceptance results and screenshots in the description
|
|
216
|
-
|
|
217
|
-
### 3. Direct MCP tool calls — Build your own E2E acceptance workflow
|
|
218
|
-
|
|
219
|
-
Use any of the 70+ MCP tools directly from your AI assistant. This is the lowest-level option and the most flexible for building custom E2E acceptance workflows.
|
|
220
|
-
|
|
221
|
-
```
|
|
222
|
-
"Create a project called My App with URL https://myapp.com"
|
|
223
|
-
"Generate test cases for the checkout flow"
|
|
224
|
-
"Replay all test scripts against localhost:3000"
|
|
225
|
-
"Show me the latest E2E acceptance results"
|
|
226
|
-
```
|
|
117
|
+
## Commands
|
|
118
|
+
|
|
119
|
+
Every skill has a short alias. Both spellings work in Claude Code.
|
|
120
|
+
|
|
121
|
+
| Command | Alias | What it does |
|
|
122
|
+
| :------ | :---- | :----------- |
|
|
123
|
+
| `/muggle:muggle` | `/m` | Command router and menu |
|
|
124
|
+
| `/muggle:muggle-do` | `/mdo` | The full cycle: request → pull request |
|
|
125
|
+
| `/muggle:muggle-test` | `/mtest` | Change-driven acceptance testing on your diff, PR, or branch |
|
|
126
|
+
| `/muggle:muggle-test-feature-local` | `/mtestlocal` | Test one named flow against localhost |
|
|
127
|
+
| `/muggle:muggle-test-prepare` | `/mtestprep` | Verify and start the dev servers a run needs |
|
|
128
|
+
| `/muggle:muggle-test-import` | `/mimport` | Import Playwright, Cypress, Gherkin, or PRDs |
|
|
129
|
+
| `/muggle:muggle-test-regenerate-missing` | `/mregen` | Bulk-regenerate scripts for cases that have none |
|
|
130
|
+
| `/muggle:muggle-browser-task` | `/mbt` | Perform a real action on a website from plain English |
|
|
131
|
+
| `/muggle:muggle-pr-visual-walkthrough` | `/mpr` | Post screenshots and a pass/fail summary to a PR |
|
|
132
|
+
| `/muggle:muggle-pr-followup` | `/mprfollowup` | Watch a PR's reviews, CI, and base drift |
|
|
133
|
+
| `/muggle:muggle-feedback` | `/mfeedback` | Flag a generated script or step as wrong |
|
|
134
|
+
| `/muggle:muggle-preferences` | `/mprefs` | View, set, or reset preferences |
|
|
135
|
+
| `/muggle:muggle-status` | `/mstatus` | Health check: runner, MCP server, auth |
|
|
136
|
+
| `/muggle:muggle-repair` | `/mrepair` | Diagnose and fix a broken install |
|
|
137
|
+
| `/muggle:muggle-upgrade` | `/mupgrade` | Update to the latest version |
|
|
227
138
|
|
|
228
139
|
---
|
|
229
140
|
|
|
230
|
-
##
|
|
231
|
-
|
|
232
|
-
muggle-ai-works provides 70+ MCP tools organized into 8 categories: authentication, project management, use cases, test cases, test scripts, local execution, reports, and administration. These tools power all AI testing automation workflows — from one-off browser checks to full E2E acceptance automation pipelines.
|
|
233
|
-
|
|
234
|
-
Authentication (muggle-remote-auth-*)
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
| Tool | Purpose |
|
|
238
|
-
| --------------------------- | ---------------------------- |
|
|
239
|
-
| `muggle-remote-auth-status` | Check authentication status |
|
|
240
|
-
| `muggle-remote-auth-login` | Start device-code login flow |
|
|
241
|
-
| `muggle-remote-auth-poll` | Poll for login completion |
|
|
242
|
-
| `muggle-remote-auth-logout` | Clear credentials |
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
Project Management (muggle-remote-project-*)
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
| Tool | Purpose |
|
|
249
|
-
| ------------------------------ | ------------------- |
|
|
250
|
-
| `muggle-remote-project-create` | Create E2E acceptance test project |
|
|
251
|
-
| `muggle-remote-project-list` | List all projects |
|
|
252
|
-
| `muggle-remote-project-get` | Get project details |
|
|
253
|
-
| `muggle-remote-project-update` | Update project |
|
|
254
|
-
| `muggle-remote-project-delete` | Delete project |
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
Use Cases (muggle-remote-use-case-*)
|
|
141
|
+
## GitHub and GitLab
|
|
258
142
|
|
|
143
|
+
The harness resolves one provider token — `github` or `gitlab` — from the URL you passed or the `origin` remote, then picks the matching recipe set. GitHub goes through `gh`, GitLab through `glab`. Self-hosted GitLab resolves by matching the remote host against `glab`'s configured host, so `git.acme.com` works without configuration.
|
|
259
144
|
|
|
260
|
-
|
|
|
261
|
-
|
|
|
262
|
-
|
|
|
263
|
-
|
|
|
264
|
-
|
|
|
265
|
-
|
|
|
266
|
-
|
|
|
267
|
-
|
|
|
268
|
-
| `muggle-remote-use-case-delete` | Delete use case (cascades to its test cases + scripts) |
|
|
145
|
+
| Capability | GitHub | GitLab |
|
|
146
|
+
| :--------- | :----- | :----- |
|
|
147
|
+
| Open and update the change | Pull request | Merge request |
|
|
148
|
+
| Read review feedback | Review threads + line comments | Discussions + notes |
|
|
149
|
+
| Reply per comment, resolve threads | Yes | Yes |
|
|
150
|
+
| Read CI status and re-enter on red | Actions | Pipelines |
|
|
151
|
+
| Rebase onto a drifted base | Yes | Yes |
|
|
152
|
+
| Signed commits | Yes | Yes |
|
|
269
153
|
|
|
154
|
+
Nested GitLab namespaces of any depth are handled — the project path is everything before the `/-/` segment, never assumed to be two levels.
|
|
270
155
|
|
|
271
|
-
|
|
156
|
+
### The pull-request walkthrough check
|
|
272
157
|
|
|
158
|
+
When a PR is opened from a session running this plugin, Muggle reserves a comment for the acceptance walkthrough and holds the turn open until it's settled — by the walkthrough, or by a stated reason acceptance testing doesn't apply.
|
|
273
159
|
|
|
274
|
-
|
|
275
|
-
| ---------------------------------------------- | -------------------------------------------------------- |
|
|
276
|
-
| `muggle-remote-test-case-list` | List all test cases |
|
|
277
|
-
| `muggle-remote-test-case-list-by-use-case` | List by use case |
|
|
278
|
-
| `muggle-remote-test-case-get` | Get test case details |
|
|
279
|
-
| `muggle-remote-test-case-create` | Create test case |
|
|
280
|
-
| `muggle-remote-test-case-generate-from-prompt` | Generate from prompt |
|
|
281
|
-
| `muggle-remote-test-case-bulk-preview-submit` | Async batch-preview via OpenAI Batch API (~50% cheaper) |
|
|
282
|
-
| `muggle-remote-test-case-delete` | Delete test case |
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
Bulk Preview Jobs (muggle-remote-bulk-preview-job-*)
|
|
286
|
-
|
|
287
|
-
Manage async jobs started by the `*-bulk-preview-submit` tools above. Submit returns a
|
|
288
|
-
`jobId` immediately; poll `-get` until a terminal status, then persist the results via
|
|
289
|
-
`muggle-remote-use-case-create` / `muggle-remote-test-case-create`.
|
|
290
|
-
|
|
291
|
-
| Tool | Purpose |
|
|
292
|
-
| --------------------------------------- | --------------------------------------- |
|
|
293
|
-
| `muggle-remote-bulk-preview-job-get` | Poll a bulk-preview job for status/results |
|
|
294
|
-
| `muggle-remote-bulk-preview-job-list` | List bulk-preview jobs for a project |
|
|
295
|
-
| `muggle-remote-bulk-preview-job-cancel` | Cooperatively cancel an in-flight job |
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
Test Scripts and Workflows (muggle-remote-workflow-*)
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
| Tool | Purpose |
|
|
302
|
-
| ------------------------------------------------------ | ----------------------- |
|
|
303
|
-
| `muggle-remote-test-script-list` | List test scripts |
|
|
304
|
-
| `muggle-remote-test-script-get` | Get script details |
|
|
305
|
-
| `muggle-remote-test-script-delete` | Delete test script |
|
|
306
|
-
| `muggle-remote-action-script-delete` | Delete action script (permanent) |
|
|
307
|
-
| `muggle-remote-workflow-start-website-scan` | Scan site for use cases |
|
|
308
|
-
| `muggle-remote-workflow-start-test-case-detection` | Generate test cases |
|
|
309
|
-
| `muggle-remote-workflow-start-test-script-generation` | Generate scripts |
|
|
310
|
-
| `muggle-remote-workflow-start-test-script-replay` | Replay single script |
|
|
311
|
-
| `muggle-remote-workflow-start-test-script-replay-bulk` | Batch replay |
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
Local Execution (muggle-local-*)
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
| Tool | Purpose |
|
|
318
|
-
| -------------------------------------- | ---------------------------------- |
|
|
319
|
-
| `muggle-local-check-status` | Check local browser test runner status |
|
|
320
|
-
| `muggle-local-execute-test-generation` | Generate test script locally |
|
|
321
|
-
| `muggle-local-execute-replay` | Replay existing script locally |
|
|
322
|
-
| `muggle-local-cancel-execution` | Cancel active execution |
|
|
323
|
-
| `muggle-local-run-result-list` | List run results |
|
|
324
|
-
| `muggle-local-run-result-get` | Get detailed results + screenshots + studio-published cloud refs (`viewUrl`, `cloudTestScriptId`, `cloudActionScriptId`) |
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
Reports and Analytics (muggle-remote-report-*)
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
| Tool | Purpose |
|
|
331
|
-
| ------------------------------------------------ | ----------------------------------------- |
|
|
332
|
-
| `muggle-remote-report-stats-summary-get` | Report statistics |
|
|
333
|
-
| `muggle-remote-report-cost-query` | Query cost/usage |
|
|
334
|
-
| `muggle-remote-report-final-generate` | Generate final report (PDF/HTML/Markdown) |
|
|
335
|
-
| `muggle-remote-project-test-results-summary-get` | Test results summary |
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
Administration (PRD, secrets, billing, scheduling)
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
| Category | Tools |
|
|
342
|
-
| ------------------ | -------------------------------------------------------------------- |
|
|
343
|
-
| PRD processing | `muggle-remote-prd-`* — upload and process product requirements docs |
|
|
344
|
-
| Secrets management | `muggle-remote-secret-`* — store credentials for test environments |
|
|
345
|
-
| Wallet and billing | `muggle-remote-wallet-`* — manage credits and payment methods |
|
|
346
|
-
| Scheduling | `muggle-remote-recommend-*` — get CI/CD and schedule recommendations |
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
---
|
|
350
|
-
|
|
351
|
-
## Works with muggle-ai-teams
|
|
352
|
-
|
|
353
|
-
[muggle-ai-teams](https://github.com/multiplex-ai/muggle-ai-teams) is the companion package for agent orchestration, workflow steps, and delivery. When both packages are installed, muggle-ai-teams automatically integrates E2E acceptance testing into the development workflow at each stage.
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
| Workflow Step | What Happens |
|
|
357
|
-
| ------------- | ------------------------------------------------------- |
|
|
358
|
-
| **Plan** | E2E acceptance test instructions written per implementation slice |
|
|
359
|
-
| **Build** | Per-slice E2E acceptance tests via muggle-ai-works before each commit |
|
|
360
|
-
| **Verify** | Full regression sweep replaying all project scripts |
|
|
361
|
-
| **Ship** | E2E results published to cloud, linked in PR description |
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
Frontend slices get browser E2E tests. Backend-only slices are verified by unit tests (browser E2E skipped with documented reasoning).
|
|
365
|
-
|
|
366
|
-
Install both: `npm install @muggleai/works @muggleai/teams`
|
|
367
|
-
|
|
368
|
-
**Muggle AI open-source ecosystem:**
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
| Package | Purpose | Install |
|
|
372
|
-
| ---------------------------------------------------------------------- | ----------------------------------------------- | --------------------------------------- |
|
|
373
|
-
| **muggle-ai-works** (this repo) | E2E acceptance testing MCP server + autonomous dev pipeline | `/plugin install muggleai@muggle-works` |
|
|
374
|
-
| **[muggle-ai-teams](https://github.com/multiplex-ai/muggle-ai-teams)** | Agent orchestration, workflow, skills, rules | `npm install @muggleai/teams` |
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
Want the full platform experience? [MuggleTest](https://www.muggletest.com) gives you everything out of the box — no setup, no configuration.
|
|
378
|
-
|
|
379
|
-
---
|
|
380
|
-
|
|
381
|
-
## CLI Reference
|
|
382
|
-
|
|
383
|
-
```bash
|
|
384
|
-
# Server (main command — starts MCP server for AI clients)
|
|
385
|
-
muggle serve # Start with all tools (default)
|
|
386
|
-
muggle serve --e2e # Cloud E2E tools only (muggle-remote-*)
|
|
387
|
-
muggle serve --local # Local E2E tools only (muggle-local-*)
|
|
388
|
-
|
|
389
|
-
# Setup and Diagnostics
|
|
390
|
-
muggle init # First-run walkthrough: preferences, then offers the CI check
|
|
391
|
-
muggle init --json # Emit the walkthrough for another front-end to render
|
|
392
|
-
muggle setup # Download/update browser test runner
|
|
393
|
-
muggle setup --force # Force re-download
|
|
394
|
-
muggle doctor # Diagnose installation issues
|
|
395
|
-
|
|
396
|
-
# Authentication
|
|
397
|
-
muggle login # Manually trigger login
|
|
398
|
-
muggle logout # Clear credentials
|
|
399
|
-
muggle status # Show auth status
|
|
400
|
-
|
|
401
|
-
# Pull request checks
|
|
402
|
-
muggle ci-install # Add the walkthrough check to this repo's GitHub Actions
|
|
403
|
-
muggle ci-install --force # Replace an existing workflow file
|
|
404
|
-
|
|
405
|
-
# Info
|
|
406
|
-
muggle --version # Show version
|
|
407
|
-
muggle --help # Show help
|
|
408
|
-
```
|
|
409
|
-
|
|
410
|
-
---
|
|
411
|
-
|
|
412
|
-
## Pull request walkthrough check
|
|
413
|
-
|
|
414
|
-
When you open a pull request from a Claude session running this plugin, Muggle reserves a comment on it for the E2E visual walkthrough and holds the turn open until that comment is settled — by the walkthrough itself, or by a stated reason E2E does not apply.
|
|
415
|
-
|
|
416
|
-
A pull request opened any other way — the GitHub web UI, a teammate without the plugin — never passes through that session, so the check also runs in GitHub Actions.
|
|
417
|
-
|
|
418
|
-
`muggle init` asks whether you want it and installs it for you. To add it to another repository later:
|
|
160
|
+
A PR opened any other way — the web UI, a teammate without the plugin — never passes through that session, so the same check also runs in GitHub Actions. `muggle init` offers to install it; to add it to another repository later:
|
|
419
161
|
|
|
420
162
|
```bash
|
|
421
163
|
muggle ci-install
|
|
422
164
|
```
|
|
423
165
|
|
|
424
|
-
That
|
|
166
|
+
That writes `.github/workflows/muggle-walkthrough.yml`. To add it by hand instead:
|
|
425
167
|
|
|
426
168
|
<!-- muggle:ci-workflow-snippet -->
|
|
427
169
|
```yaml
|
|
@@ -462,226 +204,279 @@ Three things worth knowing:
|
|
|
462
204
|
|
|
463
205
|
---
|
|
464
206
|
|
|
465
|
-
##
|
|
466
|
-
|
|
467
|
-
Authentication happens automatically when you first use a tool that requires it: a browser window opens with a verification code, you log in with your Muggle AI account, and the tool call continues. Credentials persist across sessions in `~/.muggle-ai/`.
|
|
468
|
-
|
|
469
|
-
MCP client configuration examples
|
|
207
|
+
## Architecture
|
|
470
208
|
|
|
471
|
-
|
|
209
|
+
Test management lives in the cloud; execution is local and stateless. `muggle-remote-*` tools own projects, use cases, test cases, and scripts. `muggle-local-*` tools receive what they need and run the browser — so a local run never waits on cloud replay capacity.
|
|
472
210
|
|
|
473
|
-
|
|
211
|
+
### Entity model
|
|
474
212
|
|
|
475
|
-
```
|
|
476
|
-
|
|
477
|
-
"
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
"env": {
|
|
482
|
-
"MUGGLE_MCP_PROMPT_SERVICE_TARGET": "production"
|
|
483
|
-
}
|
|
484
|
-
}
|
|
485
|
-
}
|
|
486
|
-
}
|
|
213
|
+
```
|
|
214
|
+
Project ("My App")
|
|
215
|
+
└── Use Case ("User Login Flow")
|
|
216
|
+
└── Test Case ("Login with valid credentials")
|
|
217
|
+
└── Test Script (recorded browser steps)
|
|
218
|
+
└── Run Result (pass/fail + screenshots)
|
|
487
219
|
```
|
|
488
220
|
|
|
489
|
-
|
|
221
|
+
### Execution flow
|
|
490
222
|
|
|
491
|
-
```
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
223
|
+
```
|
|
224
|
+
Your agent describes what to test
|
|
225
|
+
│
|
|
226
|
+
▼
|
|
227
|
+
muggle-remote-* create or find the test cases
|
|
228
|
+
│
|
|
229
|
+
▼
|
|
230
|
+
muggle-local-execute-test-generation launches the browser runner
|
|
231
|
+
│
|
|
232
|
+
▼
|
|
233
|
+
An agent drives the browser step by step (click, type, navigate, assert)
|
|
234
|
+
│
|
|
235
|
+
▼
|
|
236
|
+
Per-step screenshots → action-script.json recorded
|
|
237
|
+
│
|
|
238
|
+
▼
|
|
239
|
+
Results at ~/.muggle-ai/sessions/{runId}/ — published during the run,
|
|
240
|
+
so the result carries a viewUrl straight to the dashboard
|
|
496
241
|
```
|
|
497
242
|
|
|
498
|
-
Data directory
|
|
243
|
+
### Data directory
|
|
499
244
|
|
|
500
245
|
```
|
|
501
246
|
~/.muggle-ai/
|
|
502
247
|
├── oauth-session.json # OAuth tokens (short-lived, auto-refresh)
|
|
503
|
-
├── api-key.json # Long-lived
|
|
248
|
+
├── api-key.json # Long-lived key for service calls
|
|
504
249
|
├── projects/ # Local project cache
|
|
505
|
-
├── sessions/ #
|
|
250
|
+
├── sessions/ # Run sessions
|
|
506
251
|
│ └── {runId}/
|
|
507
252
|
│ ├── action-script.json # Recorded browser steps
|
|
508
253
|
│ ├── results.md # Step-by-step report
|
|
509
254
|
│ └── screenshots/ # Per-step images
|
|
510
|
-
|
|
511
|
-
|
|
255
|
+
├── muggle-do/sessions/ # Cycle state, iterations, PR watchers
|
|
256
|
+
└── electron-app/{version}/
|
|
512
257
|
```
|
|
513
258
|
|
|
514
259
|
---
|
|
515
260
|
|
|
516
|
-
##
|
|
261
|
+
## MCP tool reference
|
|
262
|
+
|
|
263
|
+
106 tools across authentication, projects, use cases, test cases, scripts, workflows, local execution, reporting, secrets, billing, and administration. Call them directly from any MCP client to build your own pipeline.
|
|
264
|
+
|
|
265
|
+
**Authentication** — `muggle-remote-auth-status`, `-login`, `-poll`, `-logout`, plus `-api-key-create`, `-list`, `-get`, `-revoke`.
|
|
266
|
+
|
|
267
|
+
**Projects** — `muggle-remote-project-create`, `-list`, `-get`, `-update`, `-delete`, plus per-project rollups: `-test-results-summary-get`, `-test-runs-summary-get`, `-test-scripts-summary-get`.
|
|
268
|
+
|
|
269
|
+
| Use cases | Purpose |
|
|
270
|
+
| :-------- | :------ |
|
|
271
|
+
| `muggle-remote-use-case-list` / `-get` | Read use cases |
|
|
272
|
+
| `muggle-remote-use-case-create` | Persist a fully-specified use case (no LLM) |
|
|
273
|
+
| `muggle-remote-use-case-create-from-prompts` | Create from natural language |
|
|
274
|
+
| `muggle-remote-use-case-prompt-preview` | Preview before creating |
|
|
275
|
+
| `muggle-remote-use-case-update-from-prompt` | Regenerate from a new prompt |
|
|
276
|
+
| `muggle-remote-use-case-candidates-approve` | Approve discovered candidates |
|
|
277
|
+
| `muggle-remote-use-case-bulk-preview-submit` | Async batch preview (~50% cheaper) |
|
|
278
|
+
| `muggle-remote-use-case-delete` | Delete (cascades to test cases + scripts) |
|
|
279
|
+
|
|
280
|
+
| Test cases | Purpose |
|
|
281
|
+
| :--------- | :------ |
|
|
282
|
+
| `muggle-remote-test-case-list` / `-list-by-use-case` / `-get` | Read test cases |
|
|
283
|
+
| `muggle-remote-test-case-create` / `-update` / `-delete` | Manage test cases |
|
|
284
|
+
| `muggle-remote-test-case-generate-from-prompt` | Generate from a prompt |
|
|
285
|
+
| `muggle-remote-test-case-ancestors-get` | Walk prerequisite chains |
|
|
286
|
+
| `muggle-remote-test-case-bulk-preview-submit` | Async batch preview (~50% cheaper) |
|
|
287
|
+
| `muggle-remote-test-plan-graph-rebuild` | Rebuild the prerequisite graph |
|
|
288
|
+
|
|
289
|
+
Bulk-preview submissions return a `jobId` immediately. Poll `muggle-remote-bulk-preview-job-get` until terminal, then persist with the matching `-create` tool. `-list` and `-cancel` round out the set.
|
|
290
|
+
|
|
291
|
+
| Scripts and workflows | Purpose |
|
|
292
|
+
| :-------------------- | :------ |
|
|
293
|
+
| `muggle-remote-test-script-list` / `-get` / `-delete` | Manage test scripts |
|
|
294
|
+
| `muggle-remote-action-script-get` / `-delete` | Manage recorded action scripts |
|
|
295
|
+
| `muggle-remote-workflow-start-website-scan` | Scan a site for use cases |
|
|
296
|
+
| `muggle-remote-workflow-start-test-case-detection` | Generate test cases |
|
|
297
|
+
| `muggle-remote-workflow-start-test-script-generation` | Generate a script |
|
|
298
|
+
| `muggle-remote-workflow-start-test-script-generation-bulk` | Generate in bulk |
|
|
299
|
+
| `muggle-remote-workflow-start-test-script-replay` | Replay one script |
|
|
300
|
+
| `muggle-remote-workflow-start-test-script-replay-bulk` | Batch replay |
|
|
301
|
+
| `muggle-remote-workflow-cancel-run` / `-cancel-runtime` | Cancel in flight |
|
|
302
|
+
| `muggle-remote-wf-get-*` | Poll the latest run of each workflow type |
|
|
303
|
+
|
|
304
|
+
| Local execution | Purpose |
|
|
305
|
+
| :-------------- | :------ |
|
|
306
|
+
| `muggle-local-check-status` | Browser runner status |
|
|
307
|
+
| `muggle-local-execute-test-generation` | Generate a script by driving the browser |
|
|
308
|
+
| `muggle-local-execute-replay` | Replay an existing script |
|
|
309
|
+
| `muggle-local-cancel-execution` | Cancel the active run |
|
|
310
|
+
| `muggle-local-run-result-list` / `-get` | Results, screenshots, and cloud refs (`viewUrl`) |
|
|
311
|
+
| `muggle-local-test-script-list` / `-get` | Read locally cached scripts |
|
|
312
|
+
| `muggle-local-last-host-*` / `-last-project-*` | Remember the host and project between runs |
|
|
313
|
+
| `muggle-local-preferences-set` | Set harness preferences |
|
|
314
|
+
| `muggle-remote-local-run-upload` | Publish a local run to the cloud |
|
|
315
|
+
|
|
316
|
+
**Reporting** — `muggle-remote-report-stats-summary-get`, `-cost-query`, `-final-generate` (PDF/HTML/Markdown), `-preferences-upsert`.
|
|
317
|
+
|
|
318
|
+
**Administration** — `muggle-remote-prd-file-*` (upload and process requirements docs), `muggle-remote-secret-*` (credentials for test environments), `muggle-remote-wallet-*` (credits, payment methods, auto-topup), `muggle-remote-recommend-cicd-setup` / `-recommend-schedule`, `muggle-remote-user-feedback-*`.
|
|
517
319
|
|
|
518
|
-
|
|
320
|
+
---
|
|
519
321
|
|
|
520
|
-
|
|
322
|
+
## CLI reference
|
|
521
323
|
|
|
324
|
+
```bash
|
|
325
|
+
# Server
|
|
326
|
+
muggle serve # Start the MCP server with all tools
|
|
327
|
+
muggle serve --e2e # Cloud tools only (muggle-remote-*)
|
|
328
|
+
muggle serve --local # Local tools only (muggle-local-*)
|
|
329
|
+
|
|
330
|
+
# Setup and diagnostics
|
|
331
|
+
muggle init # Guided setup; saves preferences, offers the CI check
|
|
332
|
+
muggle setup [--force] # Download or update the browser runner
|
|
333
|
+
muggle upgrade [--check] # Install the latest runner version
|
|
334
|
+
muggle versions # List installed runner versions
|
|
335
|
+
muggle cleanup [--dry-run] # Remove old versions and obsolete skills
|
|
336
|
+
muggle doctor # Diagnose installation problems
|
|
522
337
|
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
338
|
+
# Authentication
|
|
339
|
+
muggle login [--key-expiry 90d]
|
|
340
|
+
muggle logout
|
|
341
|
+
muggle status
|
|
342
|
+
|
|
343
|
+
# Pull requests
|
|
344
|
+
muggle ci-install [--force] # Add the walkthrough check to GitHub Actions
|
|
345
|
+
muggle pr-walkthrough-check # Verify a PR's walkthrough comment is settled
|
|
346
|
+
muggle build-pr-section # Render a PR evidence block from a report on stdin
|
|
528
347
|
|
|
348
|
+
muggle --version
|
|
349
|
+
muggle --help
|
|
350
|
+
```
|
|
529
351
|
|
|
530
352
|
---
|
|
531
353
|
|
|
532
|
-
|
|
354
|
+
## Configuration
|
|
533
355
|
|
|
534
|
-
|
|
356
|
+
**Environment targeting.** Set `MUGGLE_MCP_PROMPT_SERVICE_TARGET` (`production` or `dev`) in the MCP server's `env` block. Mismatching it against the account you log in with is the usual cause of `unauthorized_client`.
|
|
535
357
|
|
|
536
|
-
**
|
|
358
|
+
**Multi-repo cycles.** Drop a `muggle-repos.json` in your working directory so a single request can span services:
|
|
537
359
|
|
|
538
|
-
|
|
360
|
+
```json
|
|
361
|
+
[
|
|
362
|
+
{ "name": "frontend", "path": "/absolute/path/to/frontend", "testCommand": "pnpm test" },
|
|
363
|
+
{ "name": "backend", "path": "/absolute/path/to/backend", "testCommand": "pnpm test" }
|
|
364
|
+
]
|
|
365
|
+
```
|
|
539
366
|
|
|
540
|
-
|
|
367
|
+
**Preferences.** `/mprefs` (or `muggle init`) controls the gates — whether to use a worktree, rebase onto the base branch, run acceptance tests every cycle, open the PR automatically, and arm the watcher. Each gate takes `always`, `ask`, or `never`.
|
|
541
368
|
|
|
542
|
-
|
|
543
|
-
muggle setup --force # Re-download
|
|
544
|
-
muggle doctor # Diagnose
|
|
545
|
-
```
|
|
369
|
+
When installed as a Claude Code plugin, MCP configuration ships with the plugin (`plugin/.mcp.json`) — there is nothing to copy by hand.
|
|
546
370
|
|
|
547
|
-
|
|
371
|
+
---
|
|
548
372
|
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
373
|
+
## Client support
|
|
374
|
+
|
|
375
|
+
| Client | MCP tools | Slash commands |
|
|
376
|
+
| :----- | :-------- | :------------- |
|
|
377
|
+
| **Claude Code** | Yes | Yes — full plugin |
|
|
378
|
+
| **Cursor** | Yes, auto-configured | Skills synced to `~/.cursor/skills/` |
|
|
379
|
+
| **Codex, Windsurf, others** | Yes, via MCP config | No |
|
|
380
|
+
|
|
381
|
+
Slash commands are plugin-managed; update them with `/plugin update muggleai@muggle-works`.
|
|
554
382
|
|
|
555
383
|
---
|
|
556
384
|
|
|
557
|
-
##
|
|
385
|
+
## Troubleshooting
|
|
558
386
|
|
|
559
|
-
|
|
387
|
+
**`unauthorized_client` during login** — the MCP server is pointed at one environment and you're authenticating against another. Fix `MUGGLE_MCP_PROMPT_SERVICE_TARGET` and restart the client.
|
|
560
388
|
|
|
561
|
-
|
|
389
|
+
**Browser runner not found**
|
|
562
390
|
|
|
563
|
-
```
|
|
564
|
-
muggle
|
|
565
|
-
|
|
566
|
-
│ ├── .claude-plugin/ # Plugin manifest (plugin.json)
|
|
567
|
-
│ ├── skills/ # Skill definitions
|
|
568
|
-
│ │ ├── muggle/ # /muggle:muggle — command router and menu
|
|
569
|
-
│ │ ├── muggle-do/ # /muggle:muggle-do — autonomous dev pipeline
|
|
570
|
-
│ │ ├── muggle-test-feature-local/ # /muggle:muggle-test-feature-local
|
|
571
|
-
│ │ ├── muggle-test-regenerate-missing/# /muggle:muggle-test-regenerate-missing
|
|
572
|
-
│ │ ├── muggle-status/ # /muggle:muggle-status
|
|
573
|
-
│ │ ├── muggle-repair/ # /muggle:muggle-repair
|
|
574
|
-
│ │ └── muggle-upgrade/ # /muggle:muggle-upgrade
|
|
575
|
-
│ ├── hooks/ # Session hooks (hooks.json)
|
|
576
|
-
│ ├── config/ # Data the hooks read (preference defaults, onboarding limits)
|
|
577
|
-
│ ├── scripts/ # Hook scripts (ensure-electron-app.sh)
|
|
578
|
-
│ ├── .mcp.json # MCP server config
|
|
579
|
-
│ └── README.md # Plugin install and usage docs
|
|
580
|
-
│
|
|
581
|
-
├── src/ # Application source
|
|
582
|
-
│ ├── cli/ # CLI commands (serve, setup, doctor, login, etc.)
|
|
583
|
-
│ └── server/ # MCP server (tool registration, stdio transport)
|
|
584
|
-
│
|
|
585
|
-
├── packages/ # Workspace packages
|
|
586
|
-
│ ├── mcps/ # Core MCP runtime — tool registries, schemas, services
|
|
587
|
-
│ ├── commands/ # CLI command contracts and registration
|
|
588
|
-
│ └── workflows/ # Workflow contracts and tests
|
|
589
|
-
│
|
|
590
|
-
├── scripts/ # Build and release
|
|
591
|
-
│ ├── build-plugin.mjs # Assembles dist/plugin/ from plugin/ source
|
|
592
|
-
│ ├── verify-plugin-marketplace.mjs # Validates plugin/marketplace consistency
|
|
593
|
-
│ ├── verify-compatibility-contracts.mjs # Validates long-term surface contracts
|
|
594
|
-
│ ├── verify-upgrade-experience.mjs # Validates in-place upgrade behavior
|
|
595
|
-
│ └── postinstall.mjs # npm postinstall (Electron app download, Cursor MCP config, skills sync)
|
|
596
|
-
│
|
|
597
|
-
├── config/compatibility/ # Contract baselines (CLI/MCP/plugin/skills)
|
|
598
|
-
├── bin/ # CLI entrypoint (muggle.js → dist/cli.js)
|
|
599
|
-
├── dist/ # Build output (gitignored)
|
|
600
|
-
├── .claude-plugin/ # Marketplace catalog (marketplace.json)
|
|
601
|
-
└── docs/ # Internal design docs and plans
|
|
391
|
+
```bash
|
|
392
|
+
muggle setup --force
|
|
393
|
+
muggle doctor
|
|
602
394
|
```
|
|
603
395
|
|
|
604
|
-
|
|
396
|
+
**Authentication keeps expiring**
|
|
605
397
|
|
|
606
398
|
```bash
|
|
607
|
-
|
|
608
|
-
|
|
609
|
-
|
|
610
|
-
pnpm run verify:plugin # Validate plugin/marketplace metadata consistency
|
|
611
|
-
pnpm run verify:contracts # Validate compatibility contracts (CLI/MCP/plugin/skills)
|
|
612
|
-
pnpm run verify:electron-release-checksums # Ensure checksums.txt exists for bundled electron release
|
|
613
|
-
pnpm run verify:upgrade-experience # Validate existing-user cleanup + re-download flow
|
|
614
|
-
pnpm run dev # Dev mode (watch)
|
|
615
|
-
pnpm test # Run tests
|
|
616
|
-
pnpm run lint # Lint (auto-fix)
|
|
617
|
-
pnpm run lint:check # Lint (check only)
|
|
618
|
-
pnpm run typecheck # TypeScript type check
|
|
399
|
+
muggle logout
|
|
400
|
+
rm ~/.muggle-ai/oauth-session.json ~/.muggle-ai/api-key.json
|
|
401
|
+
muggle login
|
|
619
402
|
```
|
|
620
403
|
|
|
621
|
-
|
|
404
|
+
---
|
|
622
405
|
|
|
406
|
+
## The ecosystem
|
|
623
407
|
|
|
624
|
-
|
|
|
625
|
-
|
|
|
626
|
-
|
|
|
627
|
-
|
|
|
628
|
-
| `publish-works-to-npm.yml` | Tag `v*` or manual | Verify (including release checksums), audit, smoke-install, publish to npm |
|
|
408
|
+
| Package | Purpose | Install |
|
|
409
|
+
| :------ | :------ | :------ |
|
|
410
|
+
| **Muggle Works** (this repo) | Delivery-cycle harness, MCP server, acceptance testing | `/plugin install muggleai@muggle-works` |
|
|
411
|
+
| **[muggle-ai-teams](https://github.com/multiplex-ai/muggle-ai-teams)** | Agent orchestration, workflow steps, rules | `npm install @muggleai/teams` |
|
|
629
412
|
|
|
630
|
-
|
|
413
|
+
With both installed, muggle-ai-teams folds acceptance testing into each workflow step: test instructions written per slice at **Plan**, per-slice browser tests at **Build**, a full regression sweep at **Verify**, and results published and linked in the PR at **Ship**. Frontend slices get browser tests; backend-only slices are covered by unit tests, with the skip reasoned in writing.
|
|
631
414
|
|
|
632
|
-
|
|
415
|
+
Want it hosted, with nothing to configure? [Muggle Test](https://www.muggletest.com).
|
|
633
416
|
|
|
634
|
-
|
|
635
|
-
- `vX.Y.Z` tags in `muggle-ai-works` are for npm publishing of `@muggleai/works` (`publish-works-to-npm.yml`).
|
|
636
|
-
- `muggle-ai-teaching-service` builds Electron artifacts and publishes them into this public repo using `electron-app-vX.Y.Z`, so binaries are publicly downloadable.
|
|
637
|
-
- The two version tracks are intentionally separate: runtime Electron artifact versions and npm package versions can move independently.
|
|
417
|
+
---
|
|
638
418
|
|
|
419
|
+
## Contributing
|
|
639
420
|
|
|
640
|
-
|
|
421
|
+
```bash
|
|
422
|
+
pnpm install # This repo is pnpm-only
|
|
423
|
+
pnpm run build # tsup + plugin artifact
|
|
424
|
+
pnpm test # Test suite
|
|
425
|
+
pnpm run lint # Lint (auto-fix)
|
|
426
|
+
pnpm run typecheck # Type check
|
|
427
|
+
pnpm run dev # Watch mode
|
|
428
|
+
```
|
|
641
429
|
|
|
430
|
+
Verification gates, all run in CI:
|
|
642
431
|
|
|
643
|
-
|
|
432
|
+
```bash
|
|
433
|
+
pnpm run verify:plugin # Plugin and marketplace metadata agree
|
|
434
|
+
pnpm run verify:contracts # CLI/MCP/plugin/skill surface contracts hold
|
|
435
|
+
pnpm run verify:skill-deps # Skill dependencies stay one-way
|
|
436
|
+
pnpm run verify:signatures # Shipped artifacts are signed
|
|
437
|
+
pnpm run verify:upgrade-experience # Existing-user upgrade still works
|
|
438
|
+
pnpm run verify:electron-release-checksums
|
|
439
|
+
```
|
|
644
440
|
|
|
645
|
-
|
|
441
|
+
### Repository layout
|
|
646
442
|
|
|
647
|
-
|
|
648
|
-
-
|
|
649
|
-
|
|
650
|
-
|
|
651
|
-
|
|
443
|
+
```
|
|
444
|
+
muggle-ai-works/
|
|
445
|
+
├── plugin/ # Claude Code plugin — source of truth
|
|
446
|
+
│ ├── skills/ # Skill definitions (muggle-do, muggle-test, _shared/vcs, …)
|
|
447
|
+
│ ├── hooks/ # Session hooks
|
|
448
|
+
│ └── .mcp.json # MCP server config
|
|
449
|
+
├── src/
|
|
450
|
+
│ ├── cli/ # CLI entrypoint
|
|
451
|
+
│ └── server/ # MCP server — tool registration, stdio transport
|
|
452
|
+
├── packages/
|
|
453
|
+
│ ├── mcps/ # Tool registries, schemas, services
|
|
454
|
+
│ ├── commands/ # CLI command contracts
|
|
455
|
+
│ └── workflows/ # Workflow contracts
|
|
456
|
+
├── scripts/ # Build, verification, postinstall
|
|
457
|
+
├── config/compatibility/ # Surface contract baselines
|
|
458
|
+
├── internal/ # Maintainer-only skills (not published)
|
|
459
|
+
└── .claude-plugin/ # Marketplace catalog
|
|
460
|
+
```
|
|
652
461
|
|
|
653
|
-
|
|
462
|
+
### Releases
|
|
654
463
|
|
|
655
|
-
|
|
|
656
|
-
|
|
|
657
|
-
|
|
|
658
|
-
|
|
|
659
|
-
|
|
|
660
|
-
| Skill descriptions | `plugin/skills/*/SKILL.md` |
|
|
661
|
-
| Tool descriptions (local) | `packages/mcps/src/mcp/tools/local/tool-registry.ts` |
|
|
662
|
-
| Tool descriptions (cloud) | `packages/mcps/src/mcp/tools/e2e/tool-registry.ts` |
|
|
663
|
-
| Plugin metadata | `plugin/.claude-plugin/plugin.json` |
|
|
464
|
+
| Workflow | Trigger | What it does |
|
|
465
|
+
| :------- | :------ | :----------- |
|
|
466
|
+
| `ci.yml` | Push/PR to `master` | Lint, test, build, contract verification across platforms |
|
|
467
|
+
| `verify-end-user-upgrade.yml` | Weekly + manual | Existing-user upgrade validation |
|
|
468
|
+
| `publish-works-to-npm.yml` | Tag `v*` or manual | Verify, audit, smoke-install, publish |
|
|
664
469
|
|
|
665
|
-
|
|
470
|
+
Two independent tag tracks: `vX.Y.Z` publishes `@muggleai/works` to npm; `electron-app-vX.Y.Z` publishes browser-runner binaries consumed by `muggle setup` and `muggle upgrade`.
|
|
666
471
|
|
|
667
|
-
|
|
668
|
-
# Requires Python 3.10+ and skill-creator plugin
|
|
669
|
-
cd ~/.claude/plugins/cache/claude-plugins-official/skill-creator/unknown/skills/skill-creator
|
|
670
|
-
|
|
671
|
-
python3 -m scripts.run_eval \
|
|
672
|
-
--eval-set /path/to/eval_set.json \
|
|
673
|
-
--skill-path /path/to/plugin/skills/test-feature-local \
|
|
674
|
-
--model claude-opus-4-6 \
|
|
675
|
-
--runs-per-query 3 \
|
|
676
|
-
--verbose
|
|
677
|
-
```
|
|
472
|
+
Maintainers cut releases with the repo-local `/mrelease` skill rather than tagging by hand — CI can otherwise publish a version that disagrees with the checked-in manifests.
|
|
678
473
|
|
|
679
|
-
|
|
474
|
+
Agents pick tools by reading descriptions, so that text is tuned deliberately rather than written once. `internal/skills/optimize-descriptions/SKILL.md` documents the five layers of agent-facing text, where each lives, and how to build and run trigger eval sets against them. It is maintainer-only and ships in neither the npm package nor the plugin.
|
|
680
475
|
|
|
681
476
|
---
|
|
682
477
|
|
|
683
478
|
## License
|
|
684
479
|
|
|
685
|
-
|
|
480
|
+
MIT. Use it, fork it, make it yours.
|
|
686
481
|
|
|
687
|
-
If
|
|
482
|
+
If it saves you a bad merge, a star helps others find it.
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"release": "5.18.0",
|
|
3
|
-
"buildId": "run-
|
|
4
|
-
"commitSha": "
|
|
5
|
-
"buildTime": "2026-09-
|
|
3
|
+
"buildId": "run-122-1",
|
|
4
|
+
"commitSha": "1170bfa0f0a22368c3ee36f85b65d708f0c99f83",
|
|
5
|
+
"buildTime": "2026-09-19T08:03:02Z",
|
|
6
6
|
"serviceName": "muggle-ai-works-mcp"
|
|
7
7
|
}
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@muggleai/works",
|
|
3
3
|
"mcpName": "io.github.multiplex-ai/muggle",
|
|
4
|
-
"version": "5.18.0
|
|
4
|
+
"version": "5.18.0",
|
|
5
5
|
"description": "Ship quality products with AI-powered E2E acceptance testing that validates your web app like a real user — from Claude Code and Cursor to PR.",
|
|
6
6
|
"type": "module",
|
|
7
7
|
"main": "dist/index.js",
|
|
@@ -54,7 +54,7 @@
|
|
|
54
54
|
"muggleConfig": {
|
|
55
55
|
"electronAppVersion": "1.10.6",
|
|
56
56
|
"downloadBaseUrl": "https://github.com/multiplex-ai/muggle-ai-works/releases/download",
|
|
57
|
-
"runtimeTargetDefault": "
|
|
57
|
+
"runtimeTargetDefault": "production",
|
|
58
58
|
"checksumsByStream": {
|
|
59
59
|
"production": {
|
|
60
60
|
"win32-x64": "c20acdc2fd7a05039c62f9e5b079e3068d1b3a23a1b3b37b75e2a650b5401de6",
|