# OpenCode Browser Tool

Herramienta browser externa para OpenCode, pensada para navegar e interactuar con aplicaciones web desde un navegador real controlado por `Playwright + Chromium`, con integracion por `MCP`.

## Estado actual

Proyecto en preparacion de la v1.

La prioridad actual es lograr una integracion efectiva entre OpenCode y el browser manteniendo la solucion totalmente desacoplada del core de OpenCode.

## Onboarding recomendado para agentes nuevos

Al iniciar una sesion en un equipo nuevo, pide primero:

- `browser_help` para descubrir capacidades, defaults y ejemplos
- `browser_health` para ver estado operativo, actividad y artifacts recientes

Default relevante en v1:

- `browser_report` usa `saveToFile=true` por defecto (configurable de forma persistente con `browser_config`)

## Objetivo de la v1

- exponer una tool browser externa por `MCP`
- abrir `Chromium` en modo visible por defecto
- permitir navegacion e interaccion base con apps locales
- recoger evidencia minima util para diagnostico

## Stack fijado para la v1

- `Node.js 20+`
- `TypeScript`
- `Playwright`
- `Chromium`
- `MCP` por `stdio`

## Modos de navegador en runtime

- `testing`: navegador gestionado por Playwright (default)
- `system`: navegador del sistema (ej. `/usr/bin/google-chrome`)

Ambos modos pueden abrir con perfil efimero o perfil persistente (`userDataDir`) segun configuracion y parametros de `browser_open`.

Defaults operativos relevantes:

- `recordVideo=false` (grabacion bajo demanda)
- `verbose=true` y `verboseOverlay=true` en modo visible
- delay humano de interaccion `1000-3000ms` para acciones click-like

## Estructura actual

```text
opencode-browser-tool/
  artifacts/
  config/
  docs/
  scripts/
  src/
    browser/
    tools/
    types/
  check.sh
  install.sh
  opencode.mcp.example.json
  package.json
  README.md
  tsconfig.json
```

## Documentacion principal

- `docs/PLAN_DE_DESARROLLO.md`
- `docs/TODO.md`
- `docs/manual_de_uso_heramienta.md`
- `docs/QUICKSTART.md`
- `docs/VALIDACION_ENTORNO_LIMPIO.md`
- `docs/PLAN_CIERRE_INSTALABLE.md`
- `docs/REGISTRO_SITUACIONES.md`
- `docs/contexto_workspace/` (snapshot de docs globales clave para continuidad)

## Instalacion prevista

La idea es que este proyecto pueda copiarse o descargarse en un PC con OpenCode y dejarse listo mediante:

- `./install.sh`
- una guia de instalacion clara
- o instrucciones que un agente de OpenCode pueda ejecutar

### Que hace `install.sh` con Chromium

El script instala dependencias y luego ejecuta:

- `npx playwright install chromium`

Esto instala el `Chromium managed by Playwright` para garantizar compatibilidad estable en la v1.

Si el sistema ya tiene un Chromium propio, en esta fase igualmente se usa el gestionado por Playwright.

## Nota

Este proyecto debe seguir siendo externo a OpenCode para que las actualizaciones del propio OpenCode no afecten a esta herramienta.