navegator/docs/BINARIOS.md

# Binarios de Automatización - Navegator

Herramientas CLI standalone para automatizar navegación web.

## 🎯 Características Principales

✅ **Perfiles Personalizables**: Cada binario puede usar cualquier perfil
✅ **Cookies Separadas**: Simula usuarios diferentes sin conflictos
✅ **Sin Dependencias**: Solo el binario ejecutable
✅ **Output Estructurado**: JSON, PNG, logs
✅ **Stealth Completo**: Flags anti-detección incluidas

---

## 📦 Binarios Disponibles

### 1. `screenshot` - Captura de Pantalla

Captura screenshots de cualquier página web.

```bash
# Compilar
go build -o screenshot cmd/screenshot.go

# Uso básico
./screenshot -url https://example.com

# Con perfil específico
./screenshot -url https://github.com -profile mi-usuario -o github.png

# Página completa, modo visible
./screenshot -url https://news.ycombinator.com -full=true -headless=false

# Resolución personalizada
./screenshot -url https://google.com -width=1920 -height=1080 -o google_hd.png
```

**Parámetros:**
- `-url` (requerido): URL a capturar
- `-profile` (default: screenshot-bot): Perfil de navegador
- `-o` (default: screenshot.png): Archivo de salida
- `-headless` (default: true): Modo headless
- `-full` (default: false): Captura página completa
- `-width` (default: 1280): Ancho de ventana
- `-height` (default: 720): Alto de ventana

---

### 2. `buscar` - Motor de Búsqueda

Busca en DuckDuckGo y extrae resultados estructurados.

```bash
# Compilar
go build -o buscar cmd/buscar.go

# Uso básico
./buscar -q "golang tutorial"

# Con perfil y más resultados
./buscar -q "python web scraping" -n 20 -profile researcher-bot

# Guardar en JSON
./buscar -q "nodejs frameworks" -output resultados.json

# Modo visible para debugging
./buscar -q "react hooks" -headless=false -profile dev-session
```

**Parámetros:**
- `-q` (requerido): Consulta de búsqueda
- `-profile` (default: search-bot): Perfil de navegador
- `-n` (default: 10): Número máximo de resultados
- `-output` (opcional): Guardar resultados en JSON
- `-headless` (default: true): Modo headless

**Output JSON:**
```json
[
  {
    "titulo": "Tutorial de Golang",
    "url": "https://...",
    "descripcion": "Aprende Go desde cero..."
  }
]
```

---

### 3. `navegar` - Navegación Interactiva

Navega a URLs, interactúa con elementos, y registra acciones.

```bash
# Compilar
go build -o navegar cmd/navegar.go

# Navegación simple
./navegar -url https://example.com -profile usuario1

# Con click en elemento
./navegar -url https://github.com -click "a[href='/explore']" -profile dev1

# Llenar formulario
./navegar -url https://httpbin.org/forms/post \
  -type "input[name='custname']" \
  -text "Juan Pérez" \
  -profile test-user

# Mantener abierto más tiempo
./navegar -url https://reddit.com -duration 30 -headless=false -profile lurker

# Sesión completa con recording
./navegar -url https://example.com \
  -profile session-abc \
  -click "button.primary" \
  -duration 15
```

**Parámetros:**
- `-url` (requerido): URL a visitar
- `-profile` (default: user-default): Perfil de navegador
- `-click` (opcional): Selector CSS para hacer click
- `-type` (opcional): Selector CSS donde escribir
- `-text` (opcional): Texto a escribir (requiere -type)
- `-headless` (default: false): Modo headless
- `-duration` (default: 10): Segundos que mantener abierto

**Genera:** `recording_<profile>.log` con todas las acciones

---

## 🎭 Simulación de Usuarios Orgánicos

### Concepto de Perfiles

Cada perfil es un **usuario virtual independiente**:

```
perfiles/
├── usuario-juan/       # Juan - desarrollador
├── usuario-maria/      # Maria - diseñadora
├── bot-research-1/     # Bot de investigación #1
├── bot-research-2/     # Bot de investigación #2
└── session-temp/       # Sesión temporal
```

Cada perfil mantiene:
- ✅ Cookies propias
- ✅ LocalStorage separado
- ✅ Historial independiente
- ✅ Cache aislado
- ✅ User-Agent persistente

### Ejemplo: Múltiples Usuarios

```bash
# Usuario 1: Busca tutoriales de Go
./buscar -q "golang tutorial" -profile dev-juan -n 10

# Usuario 2: Busca Python
./buscar -q "python basics" -profile student-maria -n 15

# Usuario 3: Captura diseños
./screenshot -url https://dribbble.com -profile designer-pedro

# Reutilizar perfil de Juan (tiene sus cookies)
./navegar -url https://github.com -profile dev-juan
```

### Script de Demostración

```bash
./ejemplos_perfiles.sh
```

Simula 3 usuarios diferentes navegando automáticamente.

---

## 🔄 Casos de Uso

### 1. Monitoreo Multi-Cuenta
```bash
# Revisar 5 cuentas diferentes
for i in {1..5}; do
  ./navegar -url https://miapp.com/dashboard \
    -profile account-$i \
    -duration 5
done
```

### 2. A/B Testing
```bash
# Probar con diferentes perfiles (cookies diferentes)
./screenshot -url https://miapp.com -profile user-a -o version-a.png
./screenshot -url https://miapp.com -profile user-b -o version-b.png
```

### 3. Scraping Distribuido
```bash
# Buscar desde múltiples "usuarios"
./buscar -q "keyword1" -profile bot-1 -output bot1.json &
./buscar -q "keyword2" -profile bot-2 -output bot2.json &
./buscar -q "keyword3" -profile bot-3 -output bot3.json &
wait
```

### 4. Testing de Sesiones
```bash
# Login con usuario A
./navegar -url https://app.com/login \
  -type "#username" -text "userA" \
  -profile session-a

# Verificar que usuario B no tiene acceso
./navegar -url https://app.com/dashboard \
  -profile session-b
```

---

## 🐍 Integración con Python

```python
import subprocess
import json

# Buscar desde Python con perfil específico
result = subprocess.run([
    './buscar',
    '-q', 'python tutorial',
    '-n', '10',
    '-profile', 'python-bot',
    '-output', 'temp.json'
], capture_output=True, text=True)

# Parsear resultados
with open('temp.json') as f:
    results = json.load(f)
    for r in results:
        print(f"{r['titulo']}: {r['url']}")

# Screenshot con perfil rotativo
profiles = ['user1', 'user2', 'user3']
for i, profile in enumerate(profiles):
    subprocess.run([
        './screenshot',
        '-url', 'https://example.com',
        '-profile', profile,
        '-o', f'capture_{i}.png'
    ])
```

---

## 🛡️ Stealth y Anti-Detección

Todos los binarios incluyen automáticamente:

✅ `navigator.webdriver = false`
✅ Sin banners de "controlado por automatización"
✅ Headers realistas
✅ Timing humano en Type
✅ User-Agent personalizable
✅ Sin extensiones sospechosas

Para máximo stealth:
```bash
# Usar modo visible (menos detectable)
./navegar -url https://sitio-estricto.com -headless=false -profile real-user

# Mantener sesión larga (más orgánico)
./navegar -url https://ejemplo.com -duration 60 -profile organic-session
```

---

## 📝 Logs y Debugging

Cada binario genera logs:

```bash
# buscar y navegar generan logs automáticos
./navegar -url https://example.com -profile test1
# Crea: recording_test1.log

# Ver log
cat recording_test1.log
```

Formato del log:
```json
{"timestamp":"...","type":"Navigate","params":{"url":"..."}}
# 22:49:11 - Navigate: https://example.com

{"timestamp":"...","type":"Click","params":{"selector":"button"}}
# 22:49:12 - Click: button
```

---

## 🚀 Performance

**Headless vs Visible:**
- Headless: Más rápido, menos memoria
- Visible: Más sigiloso, debugging más fácil

**Perfiles:**
- Primer uso: ~2-3 segundos (crea perfil)
- Usos siguientes: ~1 segundo (reutiliza)

**Limitar perfiles:**
```bash
# Limpiar perfiles viejos
rm -rf perfiles/temp-*
rm -rf perfiles/bot-old-*
```

---

## 💡 Tips

1. **Nombres descriptivos de perfiles:**
   ```bash
   ./buscar -q "query" -profile "research-$(date +%Y%m%d)"
   ```

2. **Rotación automática:**
   ```bash
   PROFILE="user-$RANDOM"
   ./screenshot -url https://example.com -profile "$PROFILE"
   ```

3. **Perfiles temporales:**
   ```bash
   ./navegar -url https://test.com -profile "temp-$$"
   rm -rf perfiles/temp-*  # Limpiar después
   ```

4. **Compartir perfil entre binarios:**
   ```bash
   # Misma sesión, diferentes tools
   ./navegar -url https://github.com -profile dev-session
   ./screenshot -url https://github.com/trending -profile dev-session
   # Ambos comparten las mismas cookies!
   ```

---

## 🔧 Compilar Todos

```bash
# Compilar todos los binarios
go build -o screenshot cmd/screenshot.go
go build -o buscar cmd/buscar.go
go build -o navegar cmd/navegar.go

# O con un script
for cmd in cmd/*.go; do
    name=$(basename "$cmd" .go)
    go build -o "$name" "$cmd"
    echo "✅ $name compilado"
done
```

---

## 📚 Crear Tus Propios Binarios

Usa el patrón de `cmd/*.go`:

```go
package main

import (
    "flag"
    "navegator/pkg/browser"
)

func main() {
    url := flag.String("url", "", "URL")
    profile := flag.String("profile", "mi-bot", "Perfil")
    flag.Parse()

    config := browser.DefaultConfig()
    config.ProfileName = *profile
    // ... tu lógica
}
```

Ventajas:
- ✅ Cada binario es independiente
- ✅ Fácil de distribuir
- ✅ Parámetros CLI estándar
- ✅ Perfiles automáticos