Autonomous-Bug-Explorer/.ralph/PROMPT.md

ABE — Autonomous Bug Explorer

Instrucciones Maestras para Claude Code (via Ralph)

---

Visión del proyecto

ABE es una plataforma enterprise self-hosted de descubrimiento autónomo de bugs en aplicaciones web. Explora apps como un usuario real, inyecta inputs inválidos (fuzzing), detecta anomalías, y genera bug reports reproducibles.

Posicionamiento: "Playwright discovers what you test. ABE discovers what you miss."

Modelo open-core enterprise self-hosted:

• Free/OSS: exploración autónoma + reports básicos
• Pro: dashboards avanzados, integraciones, CLI/CI
• Enterprise: SSO, RBAC avanzado, LDAP, audit logs, licencia

---

Estado actual del código

Las fases 1-11 del proyecto original están implementadas con esta estructura:

src/
├── core/           ← interfaces.ts, ExplorationEngine, StateGraph, AnomalyDetector
├── plugins/        ← PlaywrightAgent, collectors, exporters, fuzzers, reproducers
├── server/         ← Express API server + socket.io
├── db/             ← SQLite repositories (better-sqlite3)
├── cli.ts          ← CLI entry point
frontend/           ← React + Vite + Tailwind (básico)

El objetivo es REFACTORIZAR este código existente hacia una arquitectura modular hexagonal, migrando pieza por pieza sin romper funcionalidad.

ESTRATEGIA DE MIGRACIÓN: No reescribir de cero. Mover código existente a la nueva estructura, adaptar interfaces, y verificar que todo sigue funcionando después de cada movimiento.

---

Arquitectura objetivo: Modular Monolith Hexagonal

Principio fundamental

Infrastructure → Application → Domain
(el código SIEMPRE apunta hacia adentro, nunca al revés)

Estructura de carpetas OBJETIVO

src/
├── shared/
│   ├── domain/
│   │   ├── Entity.ts
│   │   ├── AggregateRoot.ts
│   │   ├── ValueObject.ts
│   │   ├── UniqueId.ts
│   │   ├── Result.ts
│   │   └── DomainEvent.ts
│   ├── application/
│   │   ├── UseCase.ts
│   │   ├── EventBus.ts
│   │   └── EventHandler.ts
│   └── infrastructure/
│       ├── InProcessEventBus.ts
│       ├── DatabaseConnection.ts
│       ├── Logger.ts
│       ├── Config.ts
│       └── StorageProvider.ts
│
├── modules/
│   ├── crawling/
│   │   ├── domain/        (entities, value-objects, events, ports)
│   │   ├── application/   (commands, queries, event-handlers)
│   │   └── infrastructure/(adapters, repositories, http)
│   ├── fuzzing/           (misma estructura)
│   ├── findings/          (misma estructura)
│   ├── auth/              (misma estructura)
│   ├── reporting/         (misma estructura)
│   ├── integrations/      (misma estructura)
│   ├── scheduling/        (misma estructura)
│   └── licensing/         (misma estructura)
│
├── api/
│   ├── server.ts
│   ├── router.ts
│   └── middleware/
├── realtime/
│   └── SocketGateway.ts
├── jobs/
│   ├── JobQueue.ts
│   ├── SQLiteJobQueue.ts
│   └── workers/
├── cli/
│   └── abe.ts
└── main.ts               ← composition root

---

Reglas de arquitectura INQUEBRANTABLES

1. Domain layer NO importa nada externo — ni Kysely, ni Express, ni Playwright.
2. Cross-module communication SOLO via EventBus — NUNCA import directo entre módulos.
3. Cada módulo exporta SOLO su facade via index.ts.
4. Controllers son THIN — parsean request, llaman use case, formatean response.
5. Use Cases retornan Result<T, E> — NUNCA throw para errores de negocio.
6. Un archivo = una clase = una responsabilidad.
7. Determinista — no usar Math.random() sin seed. Loguear siempre el seed.
8. Serializable — entities y value objects JSON.stringify-able.
9. No AI en el core loop — AIEnrichment es post-proceso opcional.
10. Plugins nunca se importan desde core — core solo define interfaces/ports.

---

Stack tecnológico

Backend

• Runtime: Node.js 20 + TypeScript 5.x (strict mode)
• HTTP: Express.js 4.x
• WebSocket: socket.io 4.x
• Database: Kysely (query builder) + better-sqlite3 (default) | pg (enterprise)
• Validation: Zod (schemas compartidos frontend/backend)
• Auth: Better Auth + CASL
• Browser: Playwright
• Logger: Pino + pino-pretty (dev)
• Jobs: SQLite-backed queue custom con worker_threads
• Scheduler: node-cron
• Security: Helmet, express-rate-limit, cors
• API docs: zod-to-openapi + Scalar UI
• Testing: Vitest + supertest (integration)

Frontend

• React 18 + Vite + TypeScript
• shadcn/ui (Radix UI + Tailwind CSS)
• Tremor + Recharts (charts/dashboards)
• TanStack Table + TanStack Query
• Zustand (client state)
• React Hook Form + Zod resolver
• socket.io-client
• Framer Motion

---

REGLAS OBLIGATORIAS PARA CADA TAREA

Antes de empezar

1. Leer la tarea actual del fix_plan.md
2. Leer la spec correspondiente en .ralph/specs/ SI existe
3. Verificar que las dependencias (tareas previas) están completas

Después de CADA tarea individual

1. npm run build — DEBE compilar sin errores
2. cd frontend && npm run build — DEBE compilar sin errores
3. npm run test — DEBE pasar (o no romper tests existentes)
4. Si ALGUNO falla → NO marcar tarea → arreglar PRIMERO

Después de marcar tarea como completa

1. git add -A
2. git commit -m "fase(X.Y): descripción breve de la tarea" Ejemplo: git commit -m "fase(1.3): create ValueObject base class with equals"
3. Verificar que el commit se hizo correctamente

Reglas de código

• Todo nuevo código DEBE tener tipos explícitos (CERO any)
• Imports ordenados: node_modules → shared → modules → relative
• Nombres: PascalCase para clases, camelCase para funciones/variables
• Cada módulo nuevo DEBE tener al menos un test unitario
• Código existente que se MUEVE debe seguir funcionando igual

---

Señal de completado

Cuando TODAS las tareas en fix_plan.md estén marcadas [x]:

RALPH_STATUS: completion_indicators: done EXIT_SIGNAL: true summary: "ABE enterprise refactor complete."