# ABE — Autonomous Bug Explorer

An open-source framework that autonomously explores web applications, provokes failures, and generates reproducible bug reports for developers and AI coding assistants.

## Quick Start

```bash
# Install dependencies
npm install

# Install Playwright browser
npx playwright install chromium

# Run ABE against your app
npm run explore -- --url http://localhost:3000 --output ./reports

# Replay a discovered bug
npm run replay -- --report reports/<anomaly-id>/report.json
```

## What ABE Does

1. Launches a headless browser and navigates to the target URL
2. Discovers interactive elements (links, buttons, inputs)
3. Executes actions deterministically using a seed
4. Observes HTTP responses, JS exceptions, and console errors
5. Detects anomalies using heuristic rules
6. Captures screenshots and DOM snapshots at anomaly moments
7. Generates a JSON + Markdown bug report with exact reproduction steps

## Project Structure

```
src/
├── core/               # Interfaces, StateGraph, ExplorationEngine, AnomalyDetector
└── plugins/
    ├── agents/         # PlaywrightAgent
    ├── collectors/     # Screenshot, Network, DOMSnapshot
    ├── exporters/      # JSON, Markdown
    └── reproducers/    # PlaywrightReproducer

tests/                  # Unit and integration tests (mirrors src/)
reports/                # Generated bug reports (runtime)
logs/                   # Session logs in .jsonl format (runtime)
```

## CLI Options

| Option | Default | Description |
|--------|---------|-------------|
| `--url` | `http://localhost:3000` | Target URL |
| `--output` | `./reports` | Output directory |
| `--seed` | `42` | Random seed for determinism |
| `--max-steps` | `100` | Maximum exploration steps |

## Web UI (API Server + Dashboard)

ABE also ships a web dashboard for launching explorations and watching results in real time.

```bash
# Start both the API server (port 3001) and the React frontend (port 5173)
npm run dev:all
```

Then open `http://localhost:5173` in your browser.

### API Server only

```bash
npm run server
```

REST endpoints available at `http://localhost:3001/api/`:

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/sessions` | Start a new exploration |
| `GET` | `/sessions` | List all sessions |
| `GET` | `/sessions/:id` | Session detail |
| `DELETE` | `/sessions/:id` | Stop a running session |
| `GET` | `/anomalies` | List all anomalies |
| `GET` | `/anomalies/:id` | Anomaly detail |
| `GET` | `/anomalies/:id/screenshot` | Bug screenshot (PNG) |
| `POST` | `/anomalies/:id/replay` | Trigger anomaly replay |

WebSocket events are emitted via socket.io (connect to `http://localhost:3001`).

## Docker

Run the full stack (backend + frontend) with a single command:

```bash
docker-compose up --build
```

| Service | Host port | Description |
|---------|-----------|-------------|
| Backend | `3001` | Express API + socket.io |
| Frontend | `5173` | React dashboard (nginx) |

Then open `http://localhost:5173` in your browser.

Reports and logs are persisted via Docker volumes (`./reports`, `./logs`).

## Development

```bash
npm run build       # Compile TypeScript
npm test            # Run all tests
npm run typecheck   # Type-check without compiling
```

## Architecture

```
frontend/ (React + Vite, port 5173)
    ↕ HTTP REST + WebSocket
src/server/ (Express + socket.io, port 3001)
    ↕ imports
src/core/ + src/plugins/ (ABE engine)
```

Core principles:
- **Deterministic**: all random choices are seeded and logged
- **Plugin-oriented**: core engine never imports concrete plugin classes
- **Reproducible**: every anomaly includes an exact action trace and replay script