@muggleai/works 2.0.0 → 3.0.0

package/README.md

@@ -1,279 +1,334 @@
-# @muggleai/works
+# muggle-ai-works
 
-Unified MCP server for Muggle AI - combines Cloud QA and Local Testing tools into a single package.
+**Test your web app with AI — no test code required.**
 
-## Installation
+One install gives your AI coding assistant the power to QA your app like a real user would: clicking through flows, catching broken experiences, and reporting results with screenshots and evidence.
 
-```bash
-npm install -g @muggleai/works
-```
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![npm](https://img.shields.io/npm/v/@muggleai/works)]()
+[![MCP Tools](https://img.shields.io/badge/MCP_tools-70+-green)]()
+[![Node](https://img.shields.io/badge/node-22+-orange)]()
 
-Or install directly from GitHub:
+Powered by [MuggleTest](https://www.muggletest.com) — the [AI-powered QA testing platform](https://www.muggletest.com).
 
-```bash
-npm install -g github:multiplex-ai/muggle-ai-works
-```
+---
 
-This is the canonical one-liner install path.
+## What do you get?
 
-It automatically:
-1. Installs the package
-2. Downloads the Electron app binary (via postinstall)
-3. Registers/updates `~/.cursor/mcp.json` with a `muggle` server entry
-4. Sets up CLI commands
+muggle-ai-works gives your AI coding assistant three things it doesn't have out of the box: the ability to test your app in a real browser, a fully autonomous dev pipeline from requirements to PR, and 70+ MCP tools for building custom QA workflows.
+
+- **Test features on localhost** — describe what to test in plain English; the AI drives a real browser, clicks through your flows, and reports results with screenshots. No test code to write, no Playwright setup.
+- **Autonomous dev pipeline** — run `/muggle:muggle-do` with a requirement in English; the AI codes the feature, writes unit tests, runs QA against your app, and opens a PR — all in one command.
+- **70+ MCP tools** — build custom QA workflows using tools for project management, use case discovery, test case generation, browser automation, and reporting. Works with Claude Code, Cursor, and any MCP-compatible client.
+
+---
 
 ## Quick Start
 
-### 1. Validate your install
+### 1. Install
 
 ```bash
-muggle --version
-muggle doctor
+/plugin marketplace add <marketplace-url-or-path>
+/plugin install muggle@<marketplace-name>
 ```
 
-### 2. Add to your MCP client (if needed)
+<details>
+<summary>What gets configured automatically</summary>
 
-**Cursor (`~/.cursor/mcp.json`):**
+1. Namespaced skills (`/muggle:muggle-do`, `/muggle:test-feature-local`, `/muggle:publish-test-to-cloud`)
+2. Plugin-managed MCP server configuration
+3. Plugin hooks for Electron QA engine provisioning
 
-```json
-{
-  "mcpServers": {
-    "muggle": {
-      "command": "muggle",
-      "args": ["serve"]
-    }
-  }
-}
-```
+</details>
 
-### 2. Start using MCP tools
+### 2. Verify
 
-Ask your AI assistant to test your application! Authentication happens automatically when needed.
+```bash
+muggle --version
+muggle doctor
+```
 
-## CLI Commands
+### 3. Start testing
 
-```bash
-# Server (main command - starts MCP server for AI clients)
-muggle serve              # Start server with all tools (default)
-muggle serve --qa         # Cloud QA tools only
-muggle serve --local      # Local testing tools only
+In Claude Code or Cursor, describe what to test:
 
-# Setup & Diagnostics
-muggle setup              # Download/update Electron app
-muggle setup --force      # Force re-download
-muggle doctor             # Diagnose installation issues
+> "Test my login flow on localhost:3000"
 
-# Authentication (optional - auth happens automatically)
-muggle login              # Manually trigger login
-muggle logout             # Clear credentials
-muggle status             # Show auth status
+Your AI assistant authenticates, finds or creates test cases, launches the browser, records and replays tests, and shows results with screenshots.
 
-# Info
-muggle --version          # Show version
-muggle --help             # Show help
-```
+---
 
-## Authentication
+## How does it work?
 
-Authentication happens automatically when you first use a tool that requires it:
+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.
 
-1. A browser window opens with a verification code
-2. You log in with your Muggle AI account
-3. The tool call continues with your credentials
+### Entity model
 
-Your credentials are stored in `~/.muggle-ai/credentials.json` and persist across sessions.
+```
+Project (e.g., "My App")
+  └── Use Case (e.g., "User Login Flow")
+       └── Test Case (e.g., "Login with valid credentials")
+            └── Test Script (recorded browser automation steps)
+                 └── Run Result (pass/fail + screenshots)
+```
 
-### Handling Expired Tokens
+<details>
+<summary>Test execution flow</summary>
 
-Tokens expire after a period of time. When this happens:
+```
+Your AI assistant describes what to test
+         │
+         v
+muggle-remote-* tools create test cases in cloud
+         │
+         v
+muggle-local-execute-test-generation launches the QA engine
+         │
+         v
+AI agent drives the browser step-by-step (click, type, navigate, assert)
+         │
+         v
+Screenshots captured per step → action-script.json recorded
+         │
+         v
+Results: pass/fail with evidence at ~/.muggle-ai/sessions/{runId}/
+         │
+         v
+muggle-local-publish-test-script uploads to cloud
+```
 
-1. **Check status**: Run `muggle status` or call `muggle-remote-auth-status` to see expiration
-2. **Re-authenticate**: Run `muggle login` or call `muggle-remote-auth-login` to get fresh tokens
-3. **If login fails with "unauthorized_client"**: Check your runtime target configuration (see Troubleshooting)
+</details>
 
-The MCP server will attempt to auto-refresh tokens when possible, but manual re-authentication may be required if the refresh token has also expired.
+---
 
-## Muggle Do (`/muggle-do`)
+## Three Ways to Use It
 
-An autonomous development pipeline that takes your code changes through requirements analysis, testing, QA, and PR creation — all inside Claude Code.
+### 1. `/muggle:test-feature-local` — Test a feature on localhost
 
-### How it works
+Describe what to test in English. The AI finds the right project and test cases, launches a real browser, and reports results with screenshots.
 
 ```
-You write code on a feature branch
-         |
-         v
-/muggle-do "what I built"
-         |
-    Stage 1: Requirements    → extracts goal + acceptance criteria
-    Stage 2: Impact Analysis → detects which repos have git changes
-    Stage 3: Validate        → checks feature branch, commits exist
-    Stage 4: Unit Tests      → runs test commands, fails fast
-    Stage 5: QA              → runs Muggle AI test cases
-    Stage 6: Open PRs        → pushes branch, creates PR with QA results
-         |
-         v
-    PR ready for review
+> /muggle:test-feature-local
+
+"Test my login changes on localhost:3999"
+
+1. Auth check ✓
+2. Found project: "My App"
+3. Found use case: "User Login"
+4. Found 2 test cases — recommend replay (minor changes detected)
+5. Launching QA engine... (approve? y)
+6. Results: 2/2 PASS
+   Screenshots: ~/.muggle-ai/sessions/abc123/screenshots/
+7. Publish to cloud? (y)
 ```
 
-### Step by step
+### 2. `/muggle:muggle-do` — Autonomous dev pipeline
 
-**1. Make your changes on a feature branch:**
+Full development cycle: requirements to PR in one command. The AI codes the feature, writes unit tests, runs QA against your running app, and opens a PR.
 
-```bash
-cd /path/to/your/repo
-git checkout -b feat/add-login
-# ... write your code ...
-git add -A && git commit -m "feat: add login page"
+```
+> /muggle:muggle-do "Add a logout button to the header"
+
+REQUIREMENTS  → Goal: Add logout button. Criteria: visible, functional, redirects.
+IMPACT        → frontend repo, src/components/Header.tsx
+VALIDATE      → Branch: feat/add-logout, 1 commit
+CODING        → (writes/fixes code)
+UNIT_TESTS    → 12/12 pass
+QA            → 3/3 test cases pass
+OPEN_PRS      → PR #42 opened
+DONE          → 1 iteration, all green
 ```
 
-**2. Configure your repos** — create `muggle-repos.json` in the muggle-ai-works root:
+- Session-based with crash recovery (`.muggle-do/sessions/`)
+- Auto-triage: analyzes failures and loops back to fix (max 3 iterations)
+- Multi-repo support via `muggle-repos.json`
+- PRs include QA results and screenshots in the description
 
-```json
-[
-  { "name": "frontend", "path": "/absolute/path/to/frontend", "testCommand": "pnpm test" }
-]
-```
+### 3. Direct MCP tool calls — Build your own QA workflow
 
-**3. Open Claude Code and run the dev cycle:**
+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 QA workflows.
 
 ```
-/muggle-do "Add a login page with email/password authentication"
+"Create a project called My App with URL https://myapp.com"
+"Generate test cases for the checkout flow"
+"Replay all test scripts against localhost:3000"
+"Show me the latest QA results"
 ```
 
-Claude will detect your changes, run tests, trigger QA, and open a PR.
+---
 
-### What if something fails?
+## What MCP tools are included?
 
-| Failure | What happens |
-|---|---|
-| No changes detected | Stops — make changes first, re-run |
-| On main/master | Stops — create a feature branch first |
-| Unit tests fail | Shows output, stops — fix and re-run |
-| QA fails | Shows failing tests — fix and re-run |
+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 QA automation pipelines.
+
+<details>
+<summary>Authentication (muggle-remote-auth-*)</summary>
+
+| Tool | Purpose |
+|------|---------|
+| `muggle-remote-auth-status` | Check authentication status |
+| `muggle-remote-auth-login` | Start device-code login flow |
+| `muggle-remote-auth-poll` | Poll for login completion |
+| `muggle-remote-auth-logout` | Clear credentials |
 
-### Repo config
+</details>
 
-| Field | Required | Default | Description |
-|---|---|---|---|
-| `name` | yes | — | Short identifier for the repo |
-| `path` | yes | — | Absolute path on your machine |
-| `testCommand` | no | `pnpm test` | Command to run unit tests |
+<details>
+<summary>Project Management (muggle-remote-project-*)</summary>
 
----
+| Tool | Purpose |
+|------|---------|
+| `muggle-remote-project-create` | Create QA project |
+| `muggle-remote-project-list` | List all projects |
+| `muggle-remote-project-get` | Get project details |
+| `muggle-remote-project-update` | Update project |
+| `muggle-remote-project-delete` | Delete project |
 
-## Available Tools
+</details>
 
-### Cloud QA Tools (muggle-remote-*)
+<details>
+<summary>Use Cases (muggle-remote-use-case-*)</summary>
 
-Tools that work with the Muggle AI cloud backend:
+| Tool | Purpose |
+|------|---------|
+| `muggle-remote-use-case-list` | List use cases |
+| `muggle-remote-use-case-create-from-prompts` | Create from natural language |
+| `muggle-remote-use-case-prompt-preview` | Preview before creating |
+| `muggle-remote-use-case-update-from-prompt` | Regenerate from new prompt |
 
-- `muggle-remote-project-create` - Create QA project
-- `muggle-remote-project-list` - List projects
-- `muggle-remote-use-case-create-from-prompts` - Create use cases
-- `muggle-remote-test-case-generate-from-prompt` - Generate test cases
-- `muggle-remote-workflow-start-*` - Start various workflows
-- And more...
+</details>
 
-### Local QA Tools (muggle-local-*)
+<details>
+<summary>Test Cases (muggle-remote-test-case-*)</summary>
 
-Tools that work with local testing:
+| Tool | Purpose |
+|------|---------|
+| `muggle-remote-test-case-list` | List all test cases |
+| `muggle-remote-test-case-list-by-use-case` | List by use case |
+| `muggle-remote-test-case-get` | Get test case details |
+| `muggle-remote-test-case-create` | Create test case |
+| `muggle-remote-test-case-generate-from-prompt` | Generate from prompt |
 
-- `muggle-local-check-status` - Check local status
-- `muggle-local-list-sessions` - List sessions
-- `muggle-local-execute-test-generation` - Generate test script
-- `muggle-local-execute-replay` - Replay test script
-- `muggle-local-run-result-list` - List run results
-- `muggle-local-publish-test-script` - Publish to cloud
-- And more...
+</details>
 
-## Data Directory
+<details>
+<summary>Test Scripts and Workflows (muggle-remote-workflow-*)</summary>
 
-All Muggle AI data is stored in `~/.muggle-ai/`:
+| Tool | Purpose |
+|------|---------|
+| `muggle-remote-test-script-list` | List test scripts |
+| `muggle-remote-test-script-get` | Get script details |
+| `muggle-remote-workflow-start-website-scan` | Scan site for use cases |
+| `muggle-remote-workflow-start-test-case-detection` | Generate test cases |
+| `muggle-remote-workflow-start-test-script-generation` | Generate scripts |
+| `muggle-remote-workflow-start-test-script-replay` | Replay single script |
+| `muggle-remote-workflow-start-test-script-replay-bulk` | Batch replay |
 
-```
-~/.muggle-ai/
-├── credentials.json      # Auth credentials (auto-generated)
-├── projects/             # Local test projects
-├── sessions/             # Test execution sessions
-└── electron-app/         # Downloaded Electron app
-    └── 1.0.0/
-        └── MuggleAI.exe
-```
+</details>
 
-## Requirements
+<details>
+<summary>Local Execution (muggle-local-*)</summary>
 
-- Node.js 22 or higher
-- For local testing: Electron app (downloaded automatically)
+| Tool | Purpose |
+|------|---------|
+| `muggle-local-check-status` | Check local QA engine status |
+| `muggle-local-execute-test-generation` | Generate test script locally |
+| `muggle-local-execute-replay` | Replay existing script locally |
+| `muggle-local-cancel-execution` | Cancel active execution |
+| `muggle-local-run-result-list` | List run results |
+| `muggle-local-run-result-get` | Get detailed results + screenshots |
+| `muggle-local-publish-test-script` | Publish script to cloud |
 
-## Development
+</details>
 
-### Building
+<details>
+<summary>Reports and Analytics (muggle-remote-report-*)</summary>
 
-```bash
-npm install
-npm run build
-```
+| Tool | Purpose |
+|------|---------|
+| `muggle-remote-report-stats-summary-get` | Report statistics |
+| `muggle-remote-report-cost-query` | Query cost/usage |
+| `muggle-remote-report-final-generate` | Generate final report (PDF/HTML/Markdown) |
+| `muggle-remote-project-test-results-summary-get` | Test results summary |
 
-### Testing
+</details>
 
-```bash
-npm test              # Run tests once
-npm run test:watch    # Watch mode
-```
+<details>
+<summary>Administration (PRD, secrets, billing, scheduling)</summary>
 
-### Linting
+| Category | Tools |
+|----------|-------|
+| PRD processing | `muggle-remote-prd-*` — upload and process product requirements docs |
+| Secrets management | `muggle-remote-secret-*` — store credentials for test environments |
+| Wallet and billing | `muggle-remote-wallet-*` — manage credits and payment methods |
+| Scheduling | `muggle-remote-recommend-*` — get CI/CD and schedule recommendations |
+
+</details>
 
-```bash
-npm run lint          # Auto-fix issues
-npm run lint:check    # Check only
-```
+---
 
-## CI/CD Workflows
+## Works with muggle-ai-teams
 
-| Workflow | Trigger | Description |
-| :------- | :------ | :---------- |
-| `ci.yml` | Push/PR to `master` | Lint, test, build on multiple platforms/versions |
-| `publish-works.yml` | Tag `v*` or manual dispatch | Verify, package-audit, smoke-install, publish to npm |
+[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 QA into the development workflow at each stage.
 
-### Publishing a new version
+| Workflow Step | What Happens |
+|--------------|-------------|
+| **Plan** | QA test instructions written per implementation slice |
+| **Build** | Per-slice QA via muggle-ai-works before each commit |
+| **Verify** | Full regression sweep replaying all project scripts |
+| **Ship** | QA results published to cloud, linked in PR description |
 
-1. Update version in `package.json`
-2. Commit and push
-3. Create a git tag: `git tag v1.0.1 && git push --tags`
-4. The `publish-works.yml` workflow publishes to npm automatically
+Frontend slices get browser QA. Backend-only slices are verified by unit tests (browser QA skipped with documented reasoning).
 
-## Troubleshooting
+Install both: `npm install @muggleai/works @muggleai/teams`
 
-### Expired Token Errors
+**Muggle AI open-source ecosystem:**
 
-If you see authentication errors like "Not authenticated" or token expiration messages:
+| Package | Purpose | Install |
+|---------|---------|---------|
+| **muggle-ai-works** (this repo) | QA testing MCP server + autonomous dev pipeline | `/plugin install muggle@<marketplace>` |
+| **[muggle-ai-teams](https://github.com/multiplex-ai/muggle-ai-teams)** | Agent orchestration, workflow, skills, rules | `npm install @muggleai/teams` |
 
-1. **Check auth status**:
-   ```bash
-   muggle status
-   ```
+Want the full platform experience? [MuggleTest](https://www.muggletest.com) gives you everything out of the box — no setup, no configuration.
 
-2. **Re-authenticate**:
-   ```bash
-   muggle login
-   ```
+---
 
-3. **Clear and retry** (if login keeps failing):
-   ```bash
-   muggle logout
-   muggle login
-   ```
+## CLI Reference
 
-### "unauthorized_client" Error During Login
+```bash
+# Server (main command — starts MCP server for AI clients)
+muggle serve              # Start with all tools (default)
+muggle serve --qa         # Cloud QA tools only
+muggle serve --local      # Local QA tools only
 
-This error indicates a mismatch between your Auth0 client configuration and the target environment.
+# Setup and Diagnostics
+muggle setup              # Download/update QA engine
+muggle setup --force      # Force re-download
+muggle doctor             # Diagnose installation issues
 
-**Cause**: The MCP is configured for one environment (dev/production) but trying to authenticate against another.
+# Authentication
+muggle login              # Manually trigger login
+muggle logout             # Clear credentials
+muggle status             # Show auth status
+
+# Info
+muggle --version          # Show version
+muggle --help             # Show help
+```
+
+---
 
-**Fix**: Ensure your MCP configuration matches your intended environment by setting the `MUGGLE_MCP_PROMPT_SERVICE_TARGET` environment variable in your MCP config:
+## Setup and Configuration
+
+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/`.
+
+<details>
+<summary>MCP client configuration examples</summary>
+
+When installed as a plugin, MCP server configuration is shipped by the plugin (`plugin/.mcp.json`) and does not require manual user-level file copy.
+
+**Environment targeting** — set `MUGGLE_MCP_PROMPT_SERVICE_TARGET` to switch between production and dev:
 
-**For Production** (`~/.cursor/mcp.json`):
 ```json
 {
   "mcpServers": {
@@ -288,39 +343,133 @@ This error indicates a mismatch between your Auth0 client configuration and the
 }
 ```
 
-**For Development** (local services):
+**Multi-repo config for /muggle:muggle-do** — create `muggle-repos.json` in your working directory:
+
 ```json
-{
-  "mcpServers": {
-    "muggle": {
-      "command": "muggle",
-      "args": ["serve"],
-      "env": {
-        "MUGGLE_MCP_PROMPT_SERVICE_TARGET": "dev"
-      }
-    }
-  }
-}
+[
+  { "name": "frontend", "path": "/absolute/path/to/frontend", "testCommand": "pnpm test" },
+  { "name": "backend", "path": "/absolute/path/to/backend", "testCommand": "pnpm test" }
+]
+```
+
+</details>
+
+<details>
+<summary>Data directory structure (~/.muggle-ai/)</summary>
+
+```
+~/.muggle-ai/
+├── auth.json             # OAuth tokens
+├── credentials.json      # API key for service calls
+├── projects/             # Local project cache
+├── sessions/             # QA sessions
+│   └── {runId}/
+│       ├── action-script.json    # Recorded browser steps
+│       ├── results.md            # Step-by-step report
+│       └── screenshots/          # Per-step images
+└── electron-app/         # Downloaded QA engine
+    └── {version}/
+```
+
+</details>
+
+---
+
+## What AI clients does it work with?
+
+Full support for Claude Code. MCP tools work with Cursor and any MCP-compatible client. Plugin skills (`/muggle:muggle-do`, `/muggle:test-feature-local`) require Claude Code plugin support.
+
+<details>
+<summary>Platform compatibility table</summary>
+
+| Platform | MCP Tools | /muggle:muggle-do | /muggle:test-feature-local |
+|----------|-----------|-----------|-------------------|
+| **Claude Code** | Yes | Yes | Yes |
+| **Cursor** | Yes (via MCP) | No (needs plugin) | No (needs plugin) |
+| **Others** | Via MCP if supported | No | No |
+
+</details>
+
+---
+
+<details>
+<summary>Troubleshooting</summary>
+
+### "unauthorized_client" during login
+
+**Cause**: MCP configured for one environment but authenticating against another.
+
+**Fix**: Set the correct `MUGGLE_MCP_PROMPT_SERVICE_TARGET` in your MCP config and restart your client.
+
+### QA engine not found
+
+```bash
+muggle setup --force    # Re-download
+muggle doctor           # Diagnose
+```
+
+### Authentication keeps expiring
+
+```bash
+muggle logout           # Clear all credentials
+rm ~/.muggle-ai/auth.json ~/.muggle-ai/credentials.json
+muggle login            # Fresh login
 ```
 
-After changing the configuration, restart your MCP client (e.g., restart Cursor).
+</details>
 
-### Credential Files
+---
+
+## About
+
+Built by the team behind [MuggleTest](https://www.muggletest.com) — [AI-powered QA testing](https://www.muggletest.com) for teams who ship fast.
+
+<details>
+<summary>For contributors</summary>
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build
+pnpm run build
+
+# Dev mode (watch)
+pnpm run dev
+
+# Test
+pnpm test
+pnpm run test:watch
 
-Credentials are stored in `~/.muggle-ai/`:
+# Lint
+pnpm run lint          # Auto-fix
+pnpm run lint:check    # Check only
 
-| File | Purpose |
-| :--- | :------ |
-| `auth.json` | OAuth tokens (access token, refresh token, expiry) |
-| `credentials.json` | API key for service calls |
+# Typecheck
+pnpm run typecheck
+```
+
+**CI/CD**
+
+| Workflow | Trigger | Description |
+|----------|---------|-------------|
+| `ci.yml` | Push/PR to `master` | Lint, test, build on multiple platforms |
+| `publish-works.yml` | Tag `v*` or manual | Verify, audit, smoke-install, publish to npm |
+
+**Publishing**
 
-If you need to reset authentication completely:
 ```bash
-rm ~/.muggle-ai/auth.json
-rm ~/.muggle-ai/credentials.json
-muggle login
+# Update version in package.json
+git tag v2.0.1 && git push --tags
+# publish-works.yml handles the rest
 ```
 
+</details>
+
+---
+
 ## License
 
-MIT
+[MIT](LICENSE) — Use it, fork it, make it yours.
+
+If this helps your development workflow, consider giving it a star. It helps others find it.