@wenathlan/saddle 1.8.16 → 1.8.18

package/docs/plans/41.o.que.falta.md

@@ -1,407 +0,0 @@
-# O Que Falta: Roadmap Técnico do webscrape
-
-> **Data:** 2026-06-08
-> **Versão:** 1.0
-> **Baseado em:** PESQUISA-CONCORRENCIA.md, COMPARATIVO-CONCORRENCIA.md, AUDITORIA-DADOS.md, análise de código-fonte
-
----
-
-## Sumário
-
-`@wenathlan/webscrape` é um toolkit all-in-one que combina scraping, serialização multi-formato, AI formatting e chunking para RAG — um posicionamento único no mercado. No entanto, 3 gaps críticos impedem a adoção em produção: ausência de anti-detection real, queue persistente e suporte Docker. Este documento lista tudo que falta, priorizado por impacto.
-
----
-
-## 1. Itens de Ação Prioritários
-
-| Prioridade | Item | Esforço | Impacto | Status |
-|-----------|------|---------|---------|--------|
-| **P0** | Anti-Detection (stealth plugin) | 1-2 dias | CRÍTICO | Opcional disponível, não integrado |
-| **P0** | Persistent Queue (SQLite) | 3-5 dias | ALTO | `better-sqlite3` já é dependência |
-| **P0** | Docker support | 1-2 dias | ALTO | Nenhum Dockerfile existe |
-| **P1** | MCP Server | 3-5 dias | MÉDIO-ALTO | Zero integração MCP |
-| **P1** | Session persistence | 2-3 dias | MÉDIO | `session.ts:83-105` é in-memory |
-| **P1** | Zod schema extraction | 2-3 dias | MÉDIO | `agent.ts:68-118` não valida com schema |
-| **P2** | PDF generation | 1 dia | MÉDIO | Playwright `page.pdf()` disponível |
-| **P2** | Configurable token prices | 1 dia | MÉDIO | `tokens.ts:37-44` hardcoded 2024 |
-| **P2** | Webhook support | 2-3 dias | MÉDIO | `server.ts` não notifica eventos |
-| **P2** | Video extraction | 2-3 dias | BAIXO-MÉDIO | Nenhum suporte |
-| **P3** | Mobile emulation | 1 dia | BAIXO | Playwright suporta nativamente |
-| **P3** | Tracing/debug | 3-5 dias | BAIXO | Playwright tracing disponível |
-| **P3** | Adaptive rendering cache | 1-2 dias | BAIXO | `fetch.ts:97-104` não cacheia decisões |
-
----
-
-## 2. Correções Críticas (P0)
-
-### 2.1 Anti-Detection / Stealth
-
-**Problema:** Nenhuma proteção real contra bots. O toolkit falha contra Cloudflare, DataDome, PerimeterX.
-
-**Estado atual:**
-- `browser.ts:13`: User-Agent único hardcoded como default do `AgentBrowser`
-- `browser.ts:37`: `'--disable-web-security'` hardcoded nos launch args (risco de segurança)
-- `headers.ts:9-38`: Apenas 4 profiles estáticos (Chrome/FF/Safari × Win/Mac)
-- `optionalDependencies` em `package.json:778-781`: `playwright-extra` e `puppeteer-extra-plugin-stealth` estão listados mas **não são importados em nenhum arquivo**
-
-**O que falta:**
-
-| Capacidade | Implementado | Referência do concorrente |
-|-----------|-------------|---------------------------|
-| Fingerprint randomization | ❌ | Crawlee: fingerprints human-like automáticos |
-| TLS fingerprint rotation | ❌ | Browserless: TLS fingerprint rotation |
-| Canvas/WebGL spoofing | ❌ | Firecrawl: stealth mode com proxy residential |
-| Navigator property randomization | ❌ | Browserless: BrowserQL |
-| Captcha solving | ❌ | Firecrawl: captcha handling integrado |
-| Proxy residential | ❌ | Firecrawl/Browserless: IP rotation gerenciada |
-
-**Implementação necessária:**
-1. Integrar `puppeteer-extra-plugin-stealth` em `browser.ts` — importar e aplicar ao browser launcher
-2. Usar `playwright-extra` como wrapper do Playwright em vez de `playwright` direto (já é dependência opcional)
-3. Remover `'--disable-web-security'` de `browser.ts:37` ou torná-lo opcional via config
-4. Expandir `headers.ts` para 20+ profiles com versões dinâmicas de Chrome/FF
-5. Adicionar config de `stealth: boolean` ao `AgentBrowser` (já existe em `browser.ts:21` como `stealth: true` mas não é usado)
-
-**Arquivos afetados:**
-- `browser.ts:28-44` — reescrever `launch()` para usar `playwright-extra`
-- `browser.ts:11-22` — expandir `DEFAULTS` com opções de stealth
-- `headers.ts:9-38` — adicionar profiles dinâmicos
-
----
-
-### 2.2 Persistent Queue
-
-**Problema:** Crawler usa `Set<string>` in-memory para visited tracking e `Array` como queue. Impossível resumir crawls após crash, impossível lidar com milhões de URLs.
-
-**Estado atual:**
-- `crawler.ts:56`: `const visited = new Set<string>();`
-- `crawler.ts:57`: `const queue: CrawlEntry[] = [{ url: startUrl, depth: 0 }];`
-- `crawler.ts:63`: `while (queue.length > 0 && results.length < maxPages)`
-- `crawler.ts:64`: `const batch = queue.splice(0, maxConcurrent);`
-- `better-sqlite3` já é dependência em `package.json:237`
-
-**O que falta:**
-
-| Capacidade | Implementado | Referência do concorrente |
-|-----------|-------------|---------------------------|
-| Queue persistente (sobrevive restarts) | ❌ | Crawlee: `RequestQueue` com SQLite/disk/cloud |
-| Dedup persistente | ❌ | Crawlee: URLs processadas sobrevivem a restarts |
-| Priorização de requests | ❌ | Crawlee: FIFO/LIFO |
-| Auto-skip de URLs processadas | ❌ | Crawlee |
-
-**Implementação necessária:**
-1. Criar `queue.ts` com `SqliteQueue` usando `better-sqlite3`
-2. Schema SQLite: `CREATE TABLE requests (url TEXT PRIMARY KEY, depth INT, status TEXT, created_at INT, processed_at INT)`
-3. Substituir `Set<string>` + `Array` em `crawler.ts` por `SqliteQueue`
-4. Adicionar `persist?: boolean | string` ao `CrawlOptions` (path do SQLite)
-5. Manter fallback in-memory para uso sem persistência
-
-**Arquivos afetados:**
-- Novo: `queue.ts` — classe `SqliteQueue`
-- `crawler.ts:39-115` — refatorar `crawl()` para usar queue
-- `types.ts` — adicionar `CrawlOptions.persist`
-
----
-
-### 2.3 Docker Support
-
-**Problema:** Nenhum container de deploy. Impossível rodar em Kubernetes, Railway, Fly.io.
-
-**Estado atual:**
-- Nenhum `Dockerfile` no repositório (verificado via glob)
-- Nenhum `docker-compose.yml`
-- `server.ts:128-134` — `createServer()` retorna Hono fetch handler
-- `server.ts:132` — host hardcoded `'0.0.0.0'` (AUDITORIA-DADOS.md)
-
-**O que falta:**
-- Todos os 7 concorrentes oferecem Docker (Crawlee templates, Browserless Docker-first, Firecrawl self-hosted)
-
-**Implementação necessária:**
-1. Criar `Dockerfile` multi-stage: build → production
-2. Criar `docker-compose.yml` com Redis/SQLite como opções
-3. Fixar `server.ts:132` — default para `127.0.0.1` (AUDITORIA-DADOS.md)
-4. Adicionar docs de deploy: Railway, Fly.io, AWS ECS
-
-**Arquivos afetados:**
-- Novo: `Dockerfile`
-- Novo: `docker-compose.yml`
-- `server.ts:132` — alterar default host
-
----
-
-## 3. Gaps Competitivos (P1)
-
-### 3.1 MCP Server
-
-**Problema:** Não pode ser usado por AI agents (Claude Desktop, Cursor, Windsurf) nativamente.
-
-**Estado atual:**
-- Zero integração MCP em qualquer arquivo
-- `server.ts` fornece REST API mas não MCP
-
-**Concorrentes com MCP:**
-- Playwright: `@playwright/mcp` — browser automation para AI agents
-- Firecrawl: `firecrawl-mcp` — scrape/crawl como MCP tools
-- Browserless: MCP server integrado
-- Puppeteer: `chrome-devtools-mcp`
-
-**Implementação necessária:**
-1. Criar pacote `@wenathlan/webscrape-mcp`
-2. Expor endpoints como MCP tools: `scrape`, `crawl`, `batch`, `extract`, `serialize`
-3. Usar SDK oficial `@modelcontextprotocol/sdk`
-4. Adicionar configuração MCP ao `cli.ts`
-
-**Arquivos afetados:**
-- Novo: `mcp.ts` ou pacote separado
-- `cli.ts` — adicionar subcomando `mcp`
-
----
-
-### 3.2 Session Persistence
-
-**Problema:** `CookieJar` e `ScrapingSession` são in-memory. Perdem estado entre execuções.
-
-**Estado atual:**
-- `session.ts:11-81`: `CookieJar` com `Map<string, Cookie>` in-memory
-- `session.ts:83-105`: `ScrapingSession` com `Map<string, unknown>` in-memory
-- Sem persistência em disco ou banco
-
-**Concorrentes:**
-- Browserless: 90 dias de retenção de cookies/cache/localStorage
-- Crawlee: persiste sessões em disco
-
-**Implementação necessária:**
-1. Adicionar opção de file-based storage ao `CookieJar`
-2. Adicionar opção SQLite para `ScrapingSession`
-3. Adicionar `save(path)` / `load(path)` methods
-4. Manter in-memory como default para backward compatibility
-
-**Arquivos afetados:**
-- `session.ts:11-105` — adicionar persistência
-
----
-
-### 3.3 Zod Schema Extraction
-
-**Problema:** Não é possível extrair dados estruturados com validação de schema.
-
-**Estado atual:**
-- `agent.ts:68-118`: `formatForAgent()` gera output genérico para AI agents
-- `tokens.ts:37-44`: `MODEL_PRICES` hardcoded
-- `zod` já é dependência (`package.json:421`)
-
-**Concorrentes:**
-- Firecrawl: structured output com Zod schemas
-- Crawlee: structured output
-
-**Implementação necessária:**
-1. Criar `extractWithSchema(url, schema)` — scrape + extrair + validar com Zod
-2. Usar LLM para extrair dados baseado no schema quando necessário
-3. Gerar output TypeScript tipado
-4. Integrar com `server.ts` como novo endpoint `/scrape/schema`
-
-**Arquivos afetados:**
-- Novo: `schema-extract.ts`
-- `server.ts` — novo endpoint
-- `types.ts` — tipos para schema extraction
-
----
-
-## 4. Nice-to-Have (P2/P3)
-
-### 4.1 PDF Generation (P2)
-
-**Estado atual:** Screenshots apenas. Sem geração de PDF.
-
-**Implementação:**
-- Usar Playwright `page.pdf()` — já disponível via `browser.ts`
-- Adicionar `pdf()` method ao `AgentBrowser`
-- Adicionar endpoint `/pdf` ao `server.ts`
-
-**Arquivos:** `browser.ts`, `server.ts`
-
----
-
-### 4.2 Configurable Token Prices (P2)
-
-**Estado atual:** `tokens.ts:37-44` com preços hardcoded de 2024.
-
-```typescript
-const PRICES = {
-  'gpt-4o': { input: 0.0025, output: 0.01 },      // ← DESATUALIZADO
-  'gpt-4o-mini': { input: 0.00015, output: 0.0006 },
-  // ... 7 modelos desatualizados
-};
-```
-
-**Implementação:**
-- Tornar `MODEL_PRICES` configurável via options
-- Adicionar `setModelPrices(prices)` function
-- Manter defaults como fallback
-
-**Arquivos:** `tokens.ts`
-
----
-
-### 4.3 Webhook Support (P2)
-
-**Estado atual:** `server.ts` não notifica eventos externos.
-
-**Implementação:**
-- Adicionar `webhook?: { url: string, events: string[] }` ao `CrawlOptions`
-- POST para webhook em: crawl started, batch completed, error occurred
-- Integrar com `events.ts` (já existe)
-
-**Arquivos:** `events.ts`, `crawler.ts`, `batch.ts`, `server.ts`
-
----
-
-### 4.4 Video Extraction (P2)
-
-**Estado atual:** Nenhum suporte.
-
-**Implementação:**
-- Detectar URLs de vídeo (YouTube, TikTok)
-- Extrair metadados (título, duração, thumbnail)
-- Não baixar vídeo (complexidade alta), apenas metadata + transcript
-
-**Arquivos:** Novo: `video.ts`
-
----
-
-### 4.5 Mobile Emulation (P3)
-
-**Estado atual:** Não implementado. Playwright suporta nativamente.
-
-**Implementação:**
-- Adicionar `device?: string` ao `BrowserAgentConfig`
-- Usar `playwright.devices[device]` para viewport + user agent
-
-**Arquivos:** `browser.ts`, `types.ts`
-
----
-
-### 4.6 Tracing/Debug (P3)
-
-**Estado atual:** Não implementado. Playwright tracing disponível.
-
-**Implementação:**
-- Adicionar `tracing?: boolean` ao `BrowserAgentConfig`
-- Usar `context.tracing.start()` / `tracing.stop()`
-- Salvar trace para debugging
-
-**Arquivos:** `browser.ts`
-
----
-
-### 4.7 Adaptive Rendering Cache (P3)
-
-**Estado atual:** `fetch.ts:97-104` — `detectRenderingMode()` é chamada toda vez.
-
-**Implementação:**
-- Cacheiar decisões de rendering mode por domínio usando `cache.ts`
-- Usar heurísticas: framework detection (React/Vue/Angular), API calls
-
-**Arquivos:** `fetch.ts`, `cache.ts`
-
----
-
-## 5. Roadmap de Implementação
-
-### Semana 1: Fundação de Produção
-
-| Dia | Tarefa | Arquivos |
-|-----|--------|----------|
-| 1-2 | Integrar stealth plugin | `browser.ts` |
-| 3 | Fixar `--disable-web-security`, expandir header profiles | `browser.ts`, `headers.ts` |
-| 4-5 | Criar `SqliteQueue` para crawler | `queue.ts` (novo), `crawler.ts` |
-| 6 | Criar `Dockerfile` + `docker-compose.yml` | Novos arquivos |
-| 7 | Fixar host hardcoded, criar docs Docker | `server.ts`, docs |
-
-### Semana 2: AI & Sessions
-
-| Dia | Tarefa | Arquivos |
-|-----|--------|----------|
-| 1-3 | Criar MCP server | `mcp.ts` (novo), `cli.ts` |
-| 4-5 | Session persistence (SQLite/file) | `session.ts` |
-| 6-7 | Zod schema extraction | `schema-extract.ts` (novo), `server.ts` |
-
-### Semana 3: Features e Polish
-
-| Dia | Tarefa | Arquivos |
-|-----|--------|----------|
-| 1 | PDF generation | `browser.ts`, `server.ts` |
-| 2 | Configurable token prices | `tokens.ts` |
-| 3-4 | Webhook support | `events.ts`, `crawler.ts`, `server.ts` |
-| 5 | Mobile emulation | `browser.ts` |
-| 6-7 | Adaptive rendering cache | `fetch.ts` |
-
----
-
-## 6. Resumo de Impacto
-
-### Antes vs Depois
-
-| Capacidade | Antes | Depois |
-|-----------|-------|--------|
-| Anti-detection | ❌ User-Agent fixo | ✅ Stealth plugin + fingerprint rotation |
-| Queue | ❌ In-memory, sem persistência | ✅ SQLite, sobrevive restarts |
-| Docker | ❌ Nenhum | ✅ Dockerfile multi-stage |
-| MCP | ❌ Nenhum | ✅ Server MCP para AI agents |
-| Sessions | ❌ In-memory | ✅ Persistente (SQLite/file) |
-| Schema extraction | ❌ Nenhum | ✅ Zod validation |
-| PDF | ❌ Screenshots apenas | ✅ Geração de PDF |
-| Deploy | ❌ Manual | ✅ Docker + docs Railway/Fly.io |
-
-### Posicionamento Atualizado
-
-```
-                    Mais Abstrato
-                         ↑
-                         │
-           Firecrawl ────┼──── Browserless
-           (API-first)   │    (DaaS)
-                         │
-     ←───────────────────┼──────────────────→
-   Mais simples          │          Mais complexo
-                         │
-          webscrape ─────┼──── Crawlee
-          (Toolkit+)     │    (Framework)
-                         │
-                         ↓
-                    Menos Abstrato
-```
-
-**Depois do roadmap:** webscrape sobe para "Toolkit+" — mantendo o diferencial AI/RAG e ganhando production readiness.
-
----
-
-## 7. Checklist de Validação
-
-### P0 — Obrigatório antes de qualquer release
-
-- [ ] `browser.ts` importa e usa `playwright-extra` + stealth plugin
-- [ ] `--disable-web-security` removido ou configurável
-- [ ] `queue.ts` implementa `SqliteQueue` com better-sqlite3
-- [ ] `crawler.ts` usa queue persistente quando `persist` habilitado
-- [ ] `Dockerfile` existe e builda com sucesso
-- [ ] `docker-compose.yml` existe com opções de storage
-- [ ] `server.ts:132` default para `127.0.0.1`
-
-### P1 — Obrigatório para v3.0
-
-- [ ] MCP server funcional com endpoints scrape/crawl/batch
-- [ ] `session.ts` suporta persistência SQLite/file
-- [ ] `schema-extract.ts` implementa `extractWithSchema(url, zodSchema)`
-- [ ] Testes unitários para cada nova feature
-
-### P2 — Nice-to-have para v3.x
-
-- [ ] PDF generation via `page.pdf()`
-- [ ] Token prices configuráveis
-- [ ] Webhook support para crawl/batch events
-- [ ] Video metadata extraction
-
----
-
-*Documento gerado em 2026-06-08. Baseado em análise de código-fonte e documentos de pesquisa existentes.*