@muggleai/works 2.0.2 → 3.1.0

package/dist/{chunk-O6JAG3WQ.js → chunk-YPRFUVHP.js}

@@ -5090,7 +5090,7 @@ var testScriptGetTool = {
 };
 var executeTestGenerationTool = {
   name: "muggle-local-execute-test-generation",
-  description: "Execute test script generation for a test case. First call qa_test_case_get to get test case details, then pass them here along with the localhost URL. Requires explicit approval before launching electron-app in explore mode. By default runs headless; set showUi: true to display the electron-app UI.",
+  description: "Execute test script generation for a test case. First call qa_test_case_get to get test case details, then pass them here along with the localhost URL. Requires explicit approval before launching electron-app in explore mode. By default runs headless unless user explicitly asks for UI.",
   inputSchema: ExecuteTestGenerationInputSchema,
   execute: async (ctx) => {
     const logger14 = createChildLogger2(ctx.correlationId);

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { runCli } from './chunk-O6JAG3WQ.js';
+import { runCli } from './chunk-YPRFUVHP.js';
 
 // src/cli/main.ts
 runCli().catch((error) => {

package/dist/index.js

@@ -1 +1 @@
-export { src_exports2 as commands, createChildLogger, createUnifiedMcpServer, getConfig, getLocalQaTools, getLogger, getQaTools, local_exports as localQa, mcp_exports as mcp, qa_exports as qa, server_exports as server, src_exports as shared } from './chunk-O6JAG3WQ.js';
+export { src_exports2 as commands, createChildLogger, createUnifiedMcpServer, getConfig, getLocalQaTools, getLogger, getQaTools, local_exports as localQa, mcp_exports as mcp, qa_exports as qa, server_exports as server, src_exports as shared } from './chunk-YPRFUVHP.js';

package/dist/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "muggle",
+  "description": "Ship quality products with AI-powered QA that validates your app's user experience — from Claude Code and Cursor to PR.",
+  "version": "3.0.0",
+  "author": {
+    "name": "Muggle AI",
+    "email": "support@muggle-ai.com"
+  },
+  "homepage": "https://www.muggletest.com",
+  "repository": "https://github.com/multiplex-ai/muggle-ai-works",
+  "license": "MIT",
+  "keywords": [
+    "qa",
+    "testing",
+    "mcp",
+    "browser-automation",
+    "ai-coding",
+    "muggle-ai"
+  ]
+}

package/dist/plugin/.cursor-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "muggle",
+  "displayName": "Muggle AI",
+  "description": "Ship quality products with AI-powered QA that validates your app's user experience — from Claude Code and Cursor to PR.",
+  "version": "3.0.0",
+  "author": {
+    "name": "Muggle AI",
+    "email": "support@muggle-ai.com"
+  },
+  "homepage": "https://www.muggletest.com",
+  "repository": "https://github.com/multiplex-ai/muggle-ai-works",
+  "license": "MIT",
+  "keywords": [
+    "qa",
+    "testing",
+    "mcp",
+    "browser-automation",
+    "ai-coding",
+    "muggle-ai"
+  ]
+}

package/dist/plugin/.mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "muggle": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@muggleai/works",
+        "serve"
+      ]
+    }
+  }
+}

package/dist/plugin/README.md

@@ -0,0 +1,53 @@
+# Muggle AI Plugin for Claude Code
+
+Ship quality products with AI-powered QA that validates your app's user experience -- from Claude Code and Cursor to PR.
+
+## Install
+
+```
+/plugin marketplace add https://github.com/multiplex-ai/muggle-ai-works
+/plugin install muggleai@muggle-works
+```
+
+## Skills
+
+| Skill | What it does |
+|:---|:---|
+| `/muggle:do` | Autonomous dev pipeline: requirements, code, unit tests, QA, PR. |
+| `/muggle:test-feature-local` | Test a feature on localhost with AI-driven browser automation. Offers publish to cloud after each run. |
+| `/muggle:status` | Health check for Electron QA engine, MCP server, and authentication. |
+| `/muggle:repair` | Diagnose and fix broken installation automatically. |
+| `/muggle:upgrade` | Update Electron QA engine and MCP server to latest version. |
+
+## MCP Tools
+
+The plugin ships an MCP server with 70+ tools for project management, test case generation, browser automation, and reporting. The server starts automatically when the plugin is enabled.
+
+## Hooks
+
+A `SessionStart` hook ensures the Electron QA engine is downloaded and up to date.
+
+## Requirements
+
+- Claude Code 1.0.33 or later
+- Node.js 22+
+
+## Upgrade
+
+```
+/plugin update muggleai@muggle-works
+```
+
+## Uninstall
+
+```
+/plugin uninstall muggleai@muggle-works
+```
+
+## Links
+
+- [MuggleTest](https://www.muggletest.com)
+- [GitHub](https://github.com/multiplex-ai/muggle-ai-works)
+## License
+
+MIT

package/dist/plugin/hooks/hooks.json

@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/ensure-electron-app.sh\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/dist/plugin/scripts/ensure-electron-app.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+# Ensure the Electron QA runtime is installed/up to date.
+# This is intentionally best-effort so plugin startup is resilient.
+if command -v muggle >/dev/null 2>&1; then
+  muggle setup >/dev/null 2>&1 || true
+  exit 0
+fi
+
+npx -y @muggleai/works setup >/dev/null 2>&1 || true

package/dist/plugin/skills/do/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: do
+description: Unified Muggle AI workflow entry point. Routes to autonomous dev cycle, status, repair, or upgrade.
+disable-model-invocation: true
+---
+
+# Muggle Do
+
+Muggle Do is the top-level command for the Muggle AI development workflow.
+
+It runs the autonomous dev cycle: requirements -> impact analysis -> validate code -> coding -> unit tests -> QA -> open PRs.
+
+For maintenance tasks, use the dedicated skills: `/muggle:status`, `/muggle:repair`, `/muggle:upgrade`.
+
+## Input routing
+
+Treat `$ARGUMENTS` as the user command:
+
+- Empty / `help` / `menu` / `?` -> show menu and session selector.
+- Anything else -> treat as a new task description and start/resume a dev-cycle session.
+
+## Session model
+
+Use `.muggle-do/sessions/<slug>/` with these files:
+
+- `state.md`
+- `requirements.md`
+- `iterations/<NNN>.md`
+- `result.md`
+
+On each stage transition, update `state.md` and append stage output to the active iteration file.
+
+## Dev cycle agents
+
+Use the supporting files in this directory as stage-specific instructions:
+
+- [requirements.md](requirements.md)
+- [impact-analysis.md](impact-analysis.md)
+- [validate-code.md](validate-code.md)
+- [unit-tests.md](unit-tests.md)
+- [qa.md](qa.md)
+- [open-prs.md](open-prs.md)
+
+## Guardrails
+
+- Do not skip unit tests before QA.
+- Do not skip QA due to missing scripts; generate when needed.
+- If the same stage fails 3 times in a row, escalate with details.
+- If total iterations reach 3 and QA still fails, continue to PR creation with `[QA FAILING]`.

package/dist/plugin/skills/do/impact-analysis.md

@@ -0,0 +1,34 @@
+# Impact Analysis Agent
+
+You are analyzing git repositories to determine which ones have actual code changes that need to go through the dev cycle pipeline.
+
+## Input
+
+You receive:
+- A list of repos with their local filesystem paths
+- The requirements goal and affected repos from the requirements stage
+
+## Your Job
+
+For each repo path provided:
+
+1. **Check the current branch:** Run `git branch --show-current` in the repo. If it returns empty (detached HEAD), report an error for that repo.
+2. **Detect the default branch:** Run `git symbolic-ref refs/remotes/origin/HEAD --short` to find the default branch (e.g., `origin/main`). Strip the `origin/` prefix. If this fails, check if `main` or `master` exist locally via `git rev-parse --verify`.
+3. **Verify it's a feature branch:** The current branch must NOT be the default branch. If it is, report an error.
+4. **List changed files:** Run `git diff --name-only <default-branch>...HEAD` to find files changed on this branch relative to the default branch. If no merge base exists, fall back to `git diff --name-only HEAD`.
+5. **Get the diff:** Run `git diff <default-branch>...HEAD` for the full diff.
+
+## Output
+
+Report per repo:
+
+**Repo: (name)**
+- Branch: (current branch name)
+- Default branch: (detected default branch)
+- Changed files: (list)
+- Diff summary: (brief description of what changed)
+- Status: OK | ERROR (with reason)
+
+**Summary:** (which repos have changes, which don't, any errors)
+
+If NO repos have any changes, clearly state: "No changes detected in any repo."

package/dist/plugin/skills/do/open-prs.md

@@ -0,0 +1,52 @@
+# PR Creation Agent
+
+You are creating pull requests for each repository that has changes after a successful dev cycle run.
+
+## Input
+
+You receive:
+- Per-repo: repo name, path, branch name
+- Requirements: goal, acceptance criteria
+- QA report: passed/failed test cases, each with testCaseId, testScriptId, runId, artifactsDir, and projectId
+
+## Your Job
+
+For each repo with changes:
+
+1. **Push the branch** to origin: `git push -u origin <branch-name>` in the repo directory.
+2. **Build the PR title:**
+   - If QA has failures: `[QA FAILING] <goal>`
+   - Otherwise: `<goal>`
+   - Keep under 70 characters
+3. **Build the PR body** with these sections:
+   - `## Goal` — the requirements goal
+   - `## Acceptance Criteria` — bulleted list (omit section if empty)
+   - `## Changes` — summary of what changed in this repo
+   - `## QA Results` — full test case breakdown (see format below)
+4. **Create the PR** using `gh pr create --title "..." --body "..." --head <branch>` in the repo directory.
+5. **Capture the PR URL** from the output.
+
+## QA Results Section Format
+
+```
+## QA Results
+
+**X passed / Y failed**
+
+| Test Case | Status | Details |
+|-----------|--------|---------|
+| [Name](https://www.muggle-ai.com/muggleTestV0/dashboard/projects/{projectId}/scripts?modal=details&testCaseId={testCaseId}) | ✅ PASSED | — |
+| [Name](https://www.muggle-ai.com/muggleTestV0/dashboard/projects/{projectId}/scripts?modal=details&testCaseId={testCaseId}) | ❌ FAILED | {error} — artifacts: `{artifactsDir}` |
+```
+
+Rules:
+- Link each test case name to its details page on www.muggle-ai.com using the URL pattern above (requires `testCaseId` and `projectId` from the QA report).
+- For failed tests, include the error message and the local `artifactsDir` path so the developer can inspect screenshots.
+- Screenshots are in `{artifactsDir}/screenshots/` and viewable locally.
+
+## Output
+
+**PRs Created:**
+- (repo name): (PR URL)
+
+**Errors:** (any repos where PR creation failed, with the error message)

package/dist/plugin/skills/do/qa.md

@@ -0,0 +1,89 @@
+# QA Agent
+
+You are running QA test cases against code changes using Muggle AI's local testing infrastructure.
+
+## Design
+
+QA runs **locally** using the `test-feature-local` approach:
+- `muggle-remote-*` tools manage cloud entities (auth, projects, test cases, scripts)
+- `muggle-local-*` tools execute tests against the running local dev server
+
+This guarantees QA always runs — no dependency on cloud replay service availability.
+
+## Input
+
+You receive:
+- The Muggle project ID
+- The list of changed repos, files, and a summary of changes
+- The requirements goal
+- `localUrl` per repo (from `muggle-repos.json`) — the locally running dev server URL
+
+## Your Job
+
+### Step 0: Resolve Local URL
+
+Read `localUrl` for each repo from the context. If it is not provided, ask the user:
+> "QA requires a running local server. What URL is the `<repo>` app running on? (e.g. `http://localhost:3000`)"
+
+**Do not skip QA.** Wait for the user to provide the URL before proceeding.
+
+### Step 1: Check Authentication
+
+Use `muggle-remote-auth-status` to verify valid credentials. If not authenticated, use `muggle-remote-auth-login` to start the device-code login flow and `muggle-remote-auth-poll` to wait for completion.
+
+### Step 2: Get Test Cases
+
+Use `muggle-remote-test-case-list` with the project ID to fetch all test cases.
+
+### Step 3: Filter Relevant Test Cases
+
+Based on the changed files and the requirements goal, determine which test cases are relevant:
+- Test cases whose use cases directly relate to the changed functionality
+- Test cases that cover areas potentially affected by the changes
+- When in doubt, include the test case (better to over-test than miss a regression)
+
+### Step 4: Execute Tests Locally
+
+For each relevant test case:
+
+1. Call `muggle-remote-test-script-list` filtered by `testCaseId` to check for an existing script.
+
+2. **If a script exists** (replay path):
+   - Call `muggle-remote-test-script-get` with the `testScriptId` to fetch the full script object.
+   - Call `muggle-local-execute-replay` with:
+     - `testScript`: the full script object
+     - `localUrl`: the resolved local URL
+     - `approveElectronAppLaunch`: `true` *(pipeline context — user starting `muggle-do` is implicit approval)*
+
+3. **If no script exists** (generation path):
+   - Call `muggle-remote-test-case-get` with the `testCaseId` to fetch the full test case object.
+   - Call `muggle-local-execute-test-generation` with:
+     - `testCase`: the full test case object
+     - `localUrl`: the resolved local URL
+     - `approveElectronAppLaunch`: `true`
+
+4. When execution completes, call `muggle-local-run-result-get` with the `runId` returned by the execute call.
+
+5. **Retain per test case:** `testCaseId`, `testScriptId` (if present), `runId`, `status` (passed/failed), `artifactsDir`.
+
+### Step 5: Collect Results
+
+For each test case:
+- Record pass or fail from the run result
+- If failed, capture the error message and `artifactsDir` for reproduction
+- Every test case must be executed — generate a new script if none exists (no skips)
+
+## Output
+
+**QA Report:**
+
+**Passed:** (count)
+- (test case name) [testCaseId: `<id>`, testScriptId: `<id>`, runId: `<id>`]: passed
+
+**Failed:** (count)
+- (test case name) [testCaseId: `<id>`, runId: `<id>`]: (error) — artifacts: `<artifactsDir>`
+
+**Metadata:**
+- projectId: `<projectId>`
+
+**Overall:** ALL PASSED | FAILURES DETECTED

package/dist/plugin/skills/do/requirements.md

@@ -0,0 +1,33 @@
+# Requirements Analysis Agent
+
+You are analyzing a user's task description to extract structured requirements for an autonomous development cycle.
+
+## Input
+
+You receive:
+- A user's task description (natural language)
+- A list of configured repository names
+
+## Your Job
+
+1. **Read the task description carefully.** Understand what the user wants to build, fix, or change.
+2. **Extract the goal** — one clear sentence describing the outcome.
+3. **Extract acceptance criteria** — specific, verifiable conditions that must be true when the task is done. Each criterion should be independently testable. If the user's description is vague, infer reasonable criteria but flag them as inferred.
+4. **Identify which repos are likely affected** — based on the task description and the repo names provided.
+
+## Output
+
+Report your findings as a structured summary:
+
+**Goal:** (one sentence)
+
+**Acceptance Criteria:**
+- (criterion 1)
+- (criterion 2)
+- ...
+
+**Affected Repos:** (comma-separated list)
+
+**Notes:** (any ambiguities, assumptions, or questions — optional)
+
+Do NOT ask the user questions. Make reasonable inferences and flag assumptions in Notes.

package/dist/plugin/skills/do/unit-tests.md

@@ -0,0 +1,31 @@
+# Unit Test Runner Agent
+
+You are running unit tests for each repository that has changes in the dev cycle pipeline.
+
+## Input
+
+You receive:
+- A list of repos with their paths and test commands (e.g., `pnpm test`)
+
+## Your Job
+
+For each repo:
+
+1. **Run the test command** using Bash in the repo's directory. Use the provided test command (default: `pnpm test`).
+2. **Capture the full output** — both stdout and stderr.
+3. **Determine pass/fail** — exit code 0 means pass, anything else means fail.
+4. **If tests fail**, extract the specific failing test names/descriptions from the output.
+
+## Output
+
+Per repo:
+
+**Repo: (name)**
+- Test command: (what was run)
+- Result: PASS | FAIL
+- Failed tests: (list, if any)
+- Output: (relevant portion of test output — full output if failed, summary if passed)
+
+**Overall:** ALL PASSED | FAILURES DETECTED
+
+If any repo fails, clearly state which repos failed and include enough output for the user to diagnose the issue.

package/dist/plugin/skills/do/validate-code.md

@@ -0,0 +1,30 @@
+# Code Validation Agent
+
+You are validating that each repository's git state is ready for the dev cycle pipeline.
+
+## Input
+
+You receive:
+- A list of repos with changes (from impact analysis), including their paths and branch names
+
+## Your Job
+
+For each repo:
+
+1. **Verify the branch is a feature branch** (not main/master/the default branch). This should already be validated by impact analysis, but double-check.
+2. **Check for uncommitted changes:** Run `git status --porcelain` in the repo. If there are uncommitted changes, warn the user — uncommitted changes won't be included in PRs.
+3. **Get the branch diff:** Run `git diff <default-branch>...HEAD --stat` for a summary of changes.
+4. **Verify commits exist on the branch:** Run `git log <default-branch>..HEAD --oneline` to confirm there are commits to push.
+
+## Output
+
+Per repo:
+
+**Repo: (name)**
+- Branch: (name)
+- Commits on branch: (count and one-line summaries)
+- Uncommitted changes: yes/no (with warning if yes)
+- Diff stat: (file change summary)
+- Status: READY | WARNING | ERROR
+
+**Overall:** READY to proceed / BLOCKED (with reasons)

package/dist/plugin/skills/repair/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: repair
+description: Diagnose and fix a broken Muggle AI installation — re-downloads Electron app and resets credentials if needed.
+---
+
+# Muggle AI Repair
+
+Automatically diagnose and fix broken components.
+
+## Steps
+
+1. Run the same checks as `/muggle:status` to identify what is broken.
+2. If everything passes, report: "Nothing to repair — installation looks healthy."
+3. For each failing component:
+   - **Electron app missing or corrupt** — run `muggle setup --force` to re-download.
+   - **Authentication expired or invalid** — run `muggle-remote-auth-login` to re-authenticate.
+   - **MCP server unresponsive** — report the error and suggest restarting the session.
+4. Run status checks again to confirm all components are healthy.
+5. Report what was repaired.
+
+## Output
+
+Show before/after status for each repaired component. If repair fails, report the error with enough context for the user to investigate.

package/dist/plugin/skills/status/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: status
+description: Check health of the Muggle AI installation — Electron QA engine, MCP server, and authentication.
+---
+
+# Muggle AI Status
+
+Run a full health check and report results.
+
+## Checks
+
+1. **Electron app** — read `~/.muggle-ai/electron-app/` to find the installed version directory. Read `.install-metadata.json` to get version and checksum. Verify the binary exists at the expected path. On macOS, check code signing with `spctl --assess --verbose`.
+
+2. **MCP server** — call `muggle-local-check-status` to verify the server is responsive. Report auth state (authenticated, email, token expiry).
+
+3. **Authentication** — call `muggle-remote-auth-status`. Report whether credentials are valid and when they expire.
+
+## Output
+
+```
+Muggle AI — Status
+
+Electron app   [pass/fail]  version, binary status
+MCP server     [pass/fail]  responsive, auth state
+Authentication [pass/fail]  user, expiry
+
+[All systems operational / Issues found — run /muggle:repair to fix.]
+```
+
+Use pass/fail indicators for each check. If any check fails, tell the user to run `/muggle:repair`.

package/dist/plugin/skills/test-feature-local/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: test-feature-local
+description: Test a feature's user experience on localhost. Execute locally with muggle-local tools, and present the results on muggle-ai.com.
+---
+
+# Test Feature Local
+
+Run end-to-end feature testing from UI against a local URL:
+
+- Cloud management: `muggle-remote-*`
+- Local execution and artifacts: `muggle-local-*`
+
+## Workflow
+
+1. **Auth**
+   - `muggle-remote-auth-status`
+   - If needed: `muggle-remote-auth-login` + `muggle-remote-auth-poll`
+
+2. **Select or create the project -> use case -> test case to use**
+   - Explictly ask user to select each target to proceed.
+   - `muggle-remote-project-list`
+   - `muggle-remote-use-case-list`
+   - `muggle-remote-test-case-list-by-use-case`
+
+3. **Resolve local URL**
+   - Use the URL provided by the user.
+   - If missing, ask explicitly (do not guess).
+   - Inform user the local URL does not affect the project's remote test.
+
+4. **Check script availability**
+   - `muggle-remote-test-script-list` filtered by testCaseId
+   - If script exists, recommend replay unless user-flow changes suggest regeneration.
+
+5. **Execute**
+   - Replay path:
+     - `muggle-remote-test-script-get`
+     - `muggle-local-execute-replay`
+   - Generation path:
+     - `muggle-remote-test-case-get`
+     - `muggle-local-execute-test-generation`
+
+6. **Approval requirement**
+   - Before execution, get explicit user approval for launching Electron app.
+   - Only then set `approveElectronAppLaunch: true`.
+
+7. **Publish local generation result to MuggleTest cloud records**
+   - Use `muggle-local-publish-test-script` after successful generation so user can see the full job details.
+   - Return the remote URL for user to view the result and script details.
+
+8. **Report results**
+   - `muggle-local-run-result-get` with returned runId.
+   - Report:
+     - status
+     - duration
+     - pass/fail summary
+     - steps summary
+     - artifacts path
+     - script detail view URL
+
+## Tool map
+
+### Auth
+- `muggle-remote-auth-status`
+- `muggle-remote-auth-login`
+- `muggle-remote-auth-poll`
+- `muggle-remote-auth-logout`
+
+### Cloud entities
+- `muggle-remote-project-list`
+- `muggle-remote-project-create`
+- `muggle-remote-use-case-list`
+- `muggle-remote-use-case-create-from-prompts`
+- `muggle-remote-test-case-list-by-use-case`
+- `muggle-remote-test-case-get`
+- `muggle-remote-test-case-generate-from-prompt`
+- `muggle-remote-test-script-list`
+- `muggle-remote-test-script-get`
+
+### Local execution
+- `muggle-local-execute-test-generation`
+- `muggle-local-execute-replay`
+- `muggle-local-run-result-list`
+- `muggle-local-run-result-get`
+- `muggle-local-publish-test-script`
+
+## Guardrails
+
+- Do not silently skip auth.
+- Do not silently skip test execution when no script exists; generate one.
+- Do not launch Electron without explicit approval.
+- Do not hide failing run details; include error and artifacts path.

package/dist/plugin/skills/upgrade/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: upgrade
+description: Update Muggle AI to the latest version — Electron QA engine and MCP server.
+---
+
+# Muggle AI Upgrade
+
+Update all Muggle AI components to the latest published version.
+
+## Steps
+
+1. Run `/muggle:status` checks to capture current versions.
+2. Run `muggle setup --force` to download the latest Electron QA engine.
+3. Report the upgrade results:
+   - Previous version vs new version for each component.
+   - Whether the upgrade succeeded or failed.
+4. Run `/muggle:status` again to confirm everything is healthy after upgrade.
+
+## Output
+
+Show a before/after version comparison. If the upgrade fails at any step, report the error and suggest running `/muggle:repair`.