docs: enterprise refactor plan with ralph specs

2026-03-04 16:17:03 -05:00
parent 4c92712d20
commit f8191133c8
204 changed files with 32722 additions and 422 deletions
--- a/README.md
+++ b/README.md
@@ -1 +1,126 @@
-# abe
+# 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