navegator/README.md

# Navegator

Sistema en Go para control de Chrome/Chromium via Chrome DevTools Protocol (CDP) diseñado para automatización sigilosa con LLMs.

## Características

- **Control CDP Directo**: Comunicación WebSocket con Chrome sin dependencias de librerías de alto nivel
- **Stealth Completo**: Flags optimizadas para evitar detección de automatización
- **Perfiles Persistentes**: Gestión de perfiles de usuario con cookies y sesiones reutilizables
- **API Completa**: Navegación, interacción, cookies, storage, interceptación de red, evaluación de JavaScript

## Instalación

```bash
# Clonar repositorio
git clone <repo-url>
cd navegator

# Descargar dependencias
go mod download

# Compilar ejemplo básico
go build -o navegator-basic examples/basic.go

# Ejecutar
./navegator-basic
```

## Requisitos

- Go 1.21+
- Chrome o Chromium instalado en el sistema
- WebSocket support (gorilla/websocket)

## Uso Básico

```go
package main

import (
    "context"
    "log"
    "navegator/pkg/browser"
)

func main() {
    ctx := context.Background()

    // Configuración por defecto
    config := browser.DefaultConfig()
    config.ProfileName = "mi-perfil"

    // Lanzar navegador
    b, err := browser.Launch(ctx, config)
    if err != nil {
        log.Fatal(err)
    }
    defer b.Close()

    // Navegar
    b.Navigate(ctx, "https://example.com", nil)

    // Obtener HTML
    html, _ := b.GetHTML(ctx, "")
    log.Println(html)
}
```

## Estructura del Proyecto

```
navegator/
├── bin/                    # Binarios compilados
│   ├── screenshot          # Capturador de pantalla
│   ├── buscar             # Motor de búsqueda
│   └── navegar            # Navegador interactivo
├── cmd/                    # Código fuente de binarios
│   ├── screenshot.go
│   ├── buscar.go
│   └── navegar.go
├── pkg/                    # Librerías reutilizables
│   ├── cdp/               # Cliente CDP de bajo nivel
│   ├── browser/           # API de alto nivel del navegador
│   └── stealth/           # Configuración de flags stealth
├── scripts/                # Scripts de utilidad
│   ├── clonar_perfil.sh   # Clonar perfiles para uso paralelo
│   ├── demo_paralelo.sh   # Demo de múltiples usuarios
│   └── ejemplos_perfiles.sh
├── docs/                   # Documentación
│   ├── STEALTH_FLAGS.md   # Flags anti-detección
│   ├── BINARIOS.md        # Guía de binarios
│   ├── PERFILES_AVANZADO.md  # Gestión de perfiles
│   └── TESTING.md         # Guía de testing
├── e2e/                    # Tests E2E
│   ├── e2e_test.sh        # Tests de binarios
│   └── integration_test.sh # Tests de integración
├── examples/               # Ejemplos de código
│   ├── basic.go
│   └── advanced.go
├── Makefile                # Comandos de build y test
└── README.md
```

## Capacidades

### Navegación
- Navigate, Reload, GoBack, GoForward
- WaitForSelector con timeout
- Click, Type, Focus
- Screenshot (viewport o página completa)
- GetHTML, GetText

### Cookies & Storage
- GetCookies, SetCookie, DeleteCookie, ClearCookies
- LocalStorage: Get, Set, Remove, Clear
- SessionStorage: Get, Set, Remove, Clear
- ClearDataForOrigin

### Network
- EnableNetworkInterception
- BlockURLs, BlockResourceTypes
- ModifyHeaders
- SetExtraHTTPHeaders
- SetUserAgent
- EmulateNetworkConditions
- DisableCache

### JavaScript
- Evaluate (sync)
- EvaluateAsync (promises)
- CallFunction con argumentos
- AddBinding (exponer funciones Go a JS)
- OnConsole (monitorear console.log)
- WaitForFunction

## Perfiles Persistentes

Los perfiles se guardan en `~/.navegator/profiles/<nombre>/`:

```go
config := browser.DefaultConfig()
config.ProfileName = "session-1"  // Reutilizable entre ejecuciones
```

Cada perfil mantiene:
- Cookies
- LocalStorage/SessionStorage
- Historial
- Extensiones
- Preferencias

## Stealth Flags

Ver `docs/STEALTH_FLAGS.md` para documentación completa de todas las flags.

Configuración básica:
```go
config.StealthFlags.Headless = true
config.StealthFlags.NoSandbox = false  // Solo en Docker
config.StealthFlags.UserAgent = "Mozilla/5.0 ..."
config.StealthFlags.WindowSize = [2]int{1920, 1080}
```

## Ejemplos

### Ejemplo 1: Navegación Básica
```bash
go run examples/basic.go
```

### Ejemplo 2: Capacidades Avanzadas
```bash
go run examples/advanced.go
```

## Para LLMs

Este sistema está diseñado para ser controlado por LLMs. La API es:

1. **Declarativa**: Métodos claros como `Navigate()`, `Click()`, `Type()`
2. **Contextual**: Usa selectores CSS estándar
3. **Asíncrona**: Manejo de timeouts y esperas automáticas
4. **Completa**: Todas las capacidades CDP disponibles

Ejemplo de prompt para LLM:
```
Usando el sistema navegator:
1. Lanza un navegador con perfil "agent-123"
2. Navega a https://example.com
3. Obtén el texto del h1
4. Toma un screenshot
5. Cierra el navegador
```

## Flags Stealth Críticas

**SIEMPRE ACTIVADAS**:
- `--disable-blink-features=AutomationControlled`
- `--exclude-switches=enable-automation`
- `--user-data-dir=<path>` (perfiles persistentes)

**CONTEXTUALES**:
- `--headless=new` (modo headless moderno)
- `--no-sandbox` (SOLO en Docker/containers)
- `--disable-web-security` (SOLO en testing)

## Debugging

```go
config.StealthFlags.EnableLogging = true
config.StealthFlags.LogLevel = 0  // INFO
```

URL de debugging disponible en `b.DebugURL()`:
```
http://127.0.0.1:<port>
```

## Seguridad

⚠️ **IMPORTANTE**:
- `--no-sandbox` es PELIGROSO - solo usar en entornos confiables
- `--disable-web-security` desactiva CORS - solo para testing
- Los perfiles pueden contener datos sensibles - proteger adecuadamente

## Licencia

MIT

## Referencias

- [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/)
- [Chrome Command Line Switches](https://peter.sh/experiments/chromium-command-line-switches/)
- [Puppeteer Stealth Plugin](https://github.com/berstend/puppeteer-extra/tree/master/packages/puppeteer-extra-plugin-stealth)