mucker-dashboard

Files (1)

• SKILL.md

SKILL.md (first lines)

# Mucker Dashboard Development & Modularity Guide

This skill guides AI agents and developers in creating modular plugins, custom panels, or completely new custom frontends for **Mucker** (the zero-cert CDP-compatible OkHttp mock engine for Android).

---

## 1. Architectural Overview

Mucker adopts a headless, protocol-first design:
* **Backend**: An embedded NanoHTTPD micro-server running inside the Android debug process (default port: `8080`).
* **CORS**: Fully open (`Access-Control-Allow-Origin: *`), allowing any frontend (Vite, Next.js, local files) to connect directly.
* **REST API**: Provides JSON CRUD endpoints for mock rules, traffic history, and breakpoint state.
* **WebSocket (`/devtools/page`)**: Bi-directional event stream compatible with the Chrome DevTools Protocol (CDP) **Fetch Domain** (`Fetch.requestPaused`, `Fetch.fulfillRequest`, `Fetch.continueRequest`).
* **Static Asset Host**: The server serves static files located in Android assets `mucker-web/` (i.e., `mucker/src/main/assets/mucker-web/index.html`).

---

## 2. When to Use This Skill

Activate this skill when:
- Adding custom panels or tabs to the existing Mucker Dashboard (e.g. GraphQL inspector, Chaos latency injector, HAR exporter).
- Building an entirely new frontend using React, Vue, Svelte, or SolidJS to manage Mucker mock rules.
- Embedding a custom web dashboard into the Android library APK.
- Automating dashboard interactions with headless scripts.

---

## 3. Developing Modular Plugins for the Default Dashboard

The default dashboard (`dashboard/index.html`) supports dynamic plugin registration.

### Plugin Interface Structure

```javascript
window.MuckerDashboard.registerPlugin({
  id: 'plugin-id',              // Unique string
  name: 'Plugin Name',          // Rendered tab/menu title
  icon: '⚡',                    // Emoji or SVG markup
  
  // Lifecycle hooks:
  init(container, state) {
    // Render custom UI into `container`
  },
  onRequest(record) {
    // Fired when an OkHttp request is intercepted
  },
  onResponse(record) {
    // Fired when an OkHttp response completes
  }
});
```

### Example: Custom Latency & Chaos Plugin
```javascript
window.MuckerDashboard.registerPlugin({
  id: 'chaos',
  name: 'Chaos Engine',
  icon: '🎲',
  init(container, state) {
    container.innerHTML = `
      <div class="card p-4">
        <h3>Network Chaos Engine</h3>
        <p>Inject latency and error rates dynamically.</p>
        <button id="btnFlaky" class="btn btn-warning">Simulate 500 Server Error</button>
      </div>
    `;
    container.querySelector('#btnFlaky').addEventListener('click', async () => {
      await fetch('/api/rules', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          id: 'chaos_error',
          urlPattern: '.*',
          method: 'ALL',
          statusCode: 500,
          responseBody: '{"error": "Simulated Chaos Outage"}',
          isEnabled: true
        })
      });
      showToast('Simulated 500 rule applied!', 'warning');
    });
  }
});
```

---

## 4. Interactive Timeline & Programmatic API

The dashboard includes a high-performance Canvas waterfall timeline with interactive time range selection and zooming:
* **Interactive Interval Brush**: Click and drag to create a time filter window; drag the window body or resize handles to filter requests in real time.
* **Zoom Controls**: Mouse wheel zoom, `[+]` Zoom In (1.35x), `[−]` Zoom Out (1.35x), and `[Fit All]` buttons.
* **Programmatic Control**: Use `window.MuckerDashboard.timeline`:
  ```javascript
  const { timeline } = window.MuckerDashboard;
  timeline.zoom(0.67);                      // Zoom in
  timeline.fitAll();                         // Fit all traffic in view
  timeline.setSelection(startMs, endMs);     // Filter to time range
  timeline.clearSelection();                 // Clear filter
  timeline.highlightRequest('req_123');      // Highlight request bar
  ```

---

## 5. Building a Custom Dashboard from Scratch

### Connection Checklist
1. **ADB Port Forwarding**:
   ```bash
   adb forward tcp:8080 tcp:8080
   ```
2. **API Base URL**: `http://localhost:8080` (or `http://<device-ip>:8080` if on same Wi-Fi).
3. **WebSocket URL**: `ws://localhost:8080/devtools/page`.

### REST Endpoints
* `GET /api/status`: Engine metrics and client counts.
* `GET /api/rules`: Array of all active mock rules.
* `POST /api/rules`: Add/update rule (`{ id, urlPattern, method, statusCode, delayMs, responseBody, responseHeaders, isEnabled }`).
* `DELETE /api/rules?id=<id>`: Remove rule.

From yongjhih/mucker, MIT.

More from yongjhih/mucker