jarvis-ai-framework 2.1.1 → 3.2.0

package/skills/eng-scraper/references/4-resiliencia-etl-monitoramento.md

@@ -1,137 +0,0 @@
-# Resiliência, ETL leve e monitoramento de mudanças
-
-> Parte do skill `eng-scraper`. Leia este arquivo quando a tarefa precisar de retry, pipeline ETL leve ou monitoramento de mudanças no site.
-
-### Resiliência e Retry
-
-```typescript
-// ✅ Retry com backoff exponencial
-async function withRetry<T>(
-  fn: () => Promise<T>,
-  options: { attempts?: number; baseDelay?: number; label?: string } = {}
-): Promise<T> {
-  const { attempts = 3, baseDelay = 1000, label = 'operação' } = options
-
-  for (let attempt = 1; attempt <= attempts; attempt++) {
-    try {
-      return await fn()
-    } catch (error) {
-      if (attempt === attempts) throw error
-
-      const delay = baseDelay * Math.pow(2, attempt - 1)
-      console.warn(`${label} falhou (tentativa ${attempt}/${attempts}). Retry em ${delay}ms...`)
-      await new Promise((resolve) => setTimeout(resolve, delay))
-    }
-  }
-
-  throw new Error('Unreachable')
-}
-
-// Uso
-const data = await withRetry(
-  () => scrapePage(url),
-  { attempts: 3, baseDelay: 2000, label: `scrape ${url}` }
-)
-```
-
-#### Detectar mudanças de estrutura
-
-```typescript
-// ✅ Validar que os dados extraídos fazem sentido
-function validateExtractedData(data: unknown[], schema: { field: string; required: boolean }[]) {
-  const requiredFields = schema.filter((s) => s.required).map((s) => s.field)
-
-  const issues = data.filter((item) =>
-    requiredFields.some((field) => !item[field as keyof typeof item])
-  )
-
-  if (issues.length > 0) {
-    const pct = Math.round((issues.length / data.length) * 100)
-    console.warn(`ALERTA: ${issues.length}/${data.length} (${pct}%) itens com campos obrigatórios ausentes`)
-    console.warn('Possível mudança de estrutura no site alvo. Verificar seletores.')
-  }
-
-  return data.filter((item) => requiredFields.every((f) => item[f as keyof typeof item]))
-}
-```
-
-### Pipelines ETL Leve
-
-#### Estrutura básica de pipeline
-
-```typescript
-interface PipelineConfig {
-  sources: string[]       // URLs a processar
-  transform: (raw: unknown) => unknown  // transformação de dados
-  output: string          // caminho do arquivo de saída
-  concurrency?: number    // requests simultâneos
-}
-
-async function runPipeline(config: PipelineConfig) {
-  console.log(`Iniciando pipeline: ${config.sources.length} fontes`)
-
-  // Extract
-  const rawData = await scrapeUrls(config.sources)
-
-  // Transform
-  const transformed = rawData
-    .flat()
-    .map(config.transform)
-    .filter(Boolean)
-
-  // Deduplicação por URL ou ID
-  const deduped = [...new Map(transformed.map((item) => [item.id ?? item.url, item])).values()]
-
-  // Load
-  await saveToFile(config.output, deduped)
-  console.log(`Pipeline concluído: ${deduped.length} registros salvos em ${config.output}`)
-
-  return deduped
-}
-```
-
-#### Formatos de saída
-
-```typescript
-import { writeFileSync } from 'fs'
-import { stringify } from 'csv-stringify/sync'
-
-function saveToFile(path: string, data: unknown[]) {
-  if (path.endsWith('.json')) {
-    writeFileSync(path, JSON.stringify(data, null, 2), 'utf-8')
-  } else if (path.endsWith('.csv')) {
-    const csv = stringify(data as object[], { header: true })
-    writeFileSync(path, csv, 'utf-8')
-  } else if (path.endsWith('.ndjson')) {
-    const ndjson = data.map((d) => JSON.stringify(d)).join('\n')
-    writeFileSync(path, ndjson, 'utf-8')
-  }
-}
-```
-
-### Monitoramento de Mudanças
-
-```typescript
-// ✅ Detectar mudanças em páginas monitoradas
-async function checkForChanges(url: string, storePath: string) {
-  const current = await scrapeWithCheerio(url)
-  const currentHash = crypto.createHash('md5').update(JSON.stringify(current)).digest('hex')
-
-  let previous: { hash: string; data: unknown; timestamp: string } | null = null
-  try {
-    previous = JSON.parse(readFileSync(storePath, 'utf-8'))
-  } catch {
-    // primeira execução
-  }
-
-  if (previous?.hash === currentHash) {
-    console.log('Sem mudanças detectadas.')
-    return { changed: false }
-  }
-
-  // Persistir estado atual
-  writeFileSync(storePath, JSON.stringify({ hash: currentHash, data: current, timestamp: new Date().toISOString() }))
-
-  return { changed: true, current, previous: previous?.data }
-}
-```

package/skills/eng-scraper-robot-builder/SKILL.md

@@ -1,377 +0,0 @@
----
-name: eng-scraper-robot-builder
-description: >
-  Converte descrição de passos em linguagem natural (feitos pelo produto/dev manualmente no site)
-  em código Playwright TypeScript pronto para produção. Usa Stagehand para explorar a página real,
-  descobrir seletores via observe() e gerar automação resiliente.
-  Trigger: Use quando precisar criar um robô de automação a partir de um fluxo descrito manualmente,
-  converter passo a passo do produto em código, ou gerar scripts Playwright sem escrever seletores.
-license: AGPL-3.0
-compatibility: Designed for Claude Code (or similar products)
-allowed-tools: Read Write Edit Grep Glob Bash
-metadata:
-  author: jarvis-team
-  version: "1.0"
-  area: scraper
-# Campos Claude Code-specific (não fazem parte da spec oficial agentskills.io):
-argument-hint: "[url-alvo] [descrição do fluxo]"
-disable-model-invocation: false
----
-
-# Eng Scraper Robot Builder - Gerador de Automação Playwright
-
-Você é um **especialista em automação de browsers** que transforma descrições em linguagem natural de fluxos manuais em código Playwright TypeScript limpo e resiliente, usando Stagehand como ferramenta exploratória.
-
-## Objetivo
-
-Receber o passo a passo que o produto ou dev fez manualmente em um site e gerar código Playwright pronto para produção — sem precisar inspecionar o HTML manualmente.
-
-**Stagehand é exploratório aqui**: ele roda os passos na página real, descobre os seletores via `observe()`, e o output final é **Playwright puro** — sem dependência de LLM em runtime.
-
-## Entrada
-
-- `$ARGUMENTS` - URL do site alvo + descrição do fluxo a automatizar
-  - Exemplo: `https://app.exemplo.com "fazer login, ir para pedidos, filtrar por status pendente, exportar CSV"`
-
-## Recursos
-
-- **Referência**: https://docs.stagehand.dev
-- **Saída**: script TypeScript em `scripts/robots/{nome-do-robo}.ts` ou no repositório atual
-
----
-
-## Pré-requisito
-
-### Dependências necessárias no projeto
-
-```bash
-npm install @browserbasehq/stagehand playwright zod dotenv
-```
-
-### Variáveis de ambiente
-
-```bash
-# .env
-BROWSERBASE_API_KEY=...         # Chave da Browserbase (cloud) — OU rodar local
-BROWSERBASE_PROJECT_ID=...      # ID do projeto na Browserbase
-OPENAI_API_KEY=...              # Modelo padrão para observe/act (ou ANTHROPIC_API_KEY)
-```
-
-> Se não tiver conta Browserbase, usar `env: "LOCAL"` no Stagehand — roda com Chromium local.
-
----
-
-## Quando Usar
-
-Use este skill quando:
-- Produto ou dev descreveu um fluxo manual que precisa virar automação
-- Precisar criar um robô sem conhecer os seletores CSS/XPath do site
-- O site tem UI dinâmica onde seletores manuais seriam frágeis
-- Quiser gerar um script Playwright como ponto de partida para edição
-
-**NÃO usar quando:**
-- O fluxo já tem seletores conhecidos e estáveis → usar `eng-scraper` diretamente
-- A automação precisa rodar em produção com LLM em runtime → avaliar `eng-qa-e2e`
-- O objetivo é extração de dados estruturados → usar `eng-scraper` com `extract()`
-
----
-
-## Validação de Entrada
-
-```
-Se $ARGUMENTS está vazio:
-  → Solicitar: URL do site alvo e descrição do fluxo passo a passo
-  → Exemplo: "https://site.com 'login → ir para relatórios → exportar últimos 30 dias'"
-
-Se apenas URL fornecida:
-  → Perguntar: "Descreva o passo a passo que você fez manualmente no site"
-```
-
----
-
-## Padrões Críticos
-
-### Padrão 1: Stagehand é exploratório — Playwright é o output
-
-O processo tem duas fases distintas:
-
-```
-Fase 1 — EXPLORAÇÃO (Stagehand)
-  → Recebe passos em linguagem natural
-  → Executa cada passo com act() na página real
-  → Usa observe() para descobrir seletores XPath reais
-  → Coleta: selector + description + method para cada interação
-
-Fase 2 — GERAÇÃO (Playwright)
-  → Converte seletores descobertos em código Playwright
-  → Substitui linguagem natural por chamadas determinísticas
-  → Output: arquivo .ts sem dependência de LLM
-```
-
-### Padrão 2: Converter observe() → Playwright
-
-`observe()` retorna `Action[]` com seletores XPath reais. Use esses seletores para gerar Playwright:
-
-```typescript
-// Stagehand observe() retorna:
-// { selector: "/html/body/main/button[@type='submit']", method: "click", description: "botão enviar" }
-
-// Converter para Playwright:
-await page.locator("xpath=/html/body/main/button[@type='submit']").click()
-// Ou XPath mais legível descoberto:
-await page.locator("//button[@type='submit']").click()
-```
-
-### Padrão 3: Roteiro de exploração comentado
-
-O script de exploração Stagehand deve ter um comentário por passo, mapeando linguagem natural → ação:
-
-```typescript
-// Passo 1 (produto): "faça login com usuário admin"
-await stagehand.act("preencha o campo de email com admin@empresa.com")
-await stagehand.act("preencha o campo de senha com a senha")
-await stagehand.act("clique no botão de entrar")
-
-// Passo 2 (produto): "vá para a seção de pedidos"
-await stagehand.act("clique no menu de pedidos")
-```
-
----
-
-## Fluxo de Trabalho
-
-### 1. Coletar o passo a passo do produto/dev
-
-Perguntar ao usuário (se não fornecido nos argumentos):
-
-```
-Descreva cada passo que você fez manualmente, em ordem:
-
-Exemplo:
-1. Acessei https://app.exemplo.com
-2. Fiz login com email e senha
-3. Cliquei em "Relatórios" no menu lateral
-4. Selecionei o período "Últimos 30 dias"
-5. Cliquei em "Exportar CSV"
-6. O download começou automaticamente
-```
-
-### 2. Gerar script de exploração Stagehand
-
-Criar `scripts/robots/explore-{nome}.ts` — script temporário para descoberta:
-
-```typescript
-import "dotenv/config";
-import { Stagehand } from "@browserbasehq/stagehand";
-
-// Script de EXPLORAÇÃO — não vai para produção
-// Objetivo: descobrir seletores reais para gerar Playwright
-
-async function explore() {
-  const stagehand = new Stagehand({
-    env: "LOCAL", // ou "BROWSERBASE" se tiver conta
-    verbose: 2,   // logs detalhados para ver o que está descobrindo
-  });
-
-  await stagehand.init();
-  const page = stagehand.context.pages()[0];
-
-  // ─────────────────────────────────────────────
-  // PASSO 1: {descrição do passo em português}
-  // ─────────────────────────────────────────────
-  await page.goto("{url-alvo}");
-
-  // Descobrir elementos disponíveis para entender a estrutura
-  const loginElements = await stagehand.observe("encontre os campos de login e botão de entrar");
-  console.log("Elementos de login:", JSON.stringify(loginElements, null, 2));
-
-  // Executar a ação
-  await stagehand.act("{passo em linguagem natural}");
-
-  // ─────────────────────────────────────────────
-  // PASSO N: {próximo passo}
-  // ─────────────────────────────────────────────
-  const nextElements = await stagehand.observe("{o que procurar neste passo}");
-  console.log("Próximos elementos:", JSON.stringify(nextElements, null, 2));
-
-  await stagehand.act("{próximo passo}");
-
-  await stagehand.close();
-}
-
-explore().catch(console.error);
-```
-
-### 3. Executar o script de exploração
-
-```bash
-npx tsx scripts/robots/explore-{nome}.ts 2>&1 | tee scripts/robots/explore-{nome}.log
-```
-
-Analisar o output do `console.log` para coletar os seletores reais retornados pelo `observe()`.
-
-### 4. Gerar o script Playwright final
-
-Com os seletores descobertos, gerar `scripts/robots/{nome}.ts`:
-
-```typescript
-import { chromium, Browser, Page } from "playwright";
-
-// ─────────────────────────────────────────────────────────────
-// Robô: {nome do robô}
-// Origem: fluxo manual descrito por {produto/dev}
-// Seletores descobertos via Stagehand em {data}
-// ─────────────────────────────────────────────────────────────
-
-async function run{NomeRobo}() {
-  const browser: Browser = await chromium.launch({ headless: true });
-  const context = await browser.newContext({
-    userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
-  });
-  const page: Page = await context.newPage();
-
-  try {
-    // Passo 1: {descrição original do produto}
-    await page.goto("{url}", { waitUntil: "networkidle" });
-
-    // Passo 2: {descrição}
-    await page.locator("{seletor-descoberto-pelo-stagehand}").click();
-    await page.waitForLoadState("networkidle");
-
-    // Passo N: {descrição}
-    await page.locator("{seletor}").fill("{valor}");
-
-    // Validação: confirmar que o fluxo funcionou
-    await page.waitForSelector("{seletor-de-confirmação}", { timeout: 10_000 });
-
-  } finally {
-    await browser.close();
-  }
-}
-
-run{NomeRobo}().catch((err) => {
-  console.error("Robô falhou:", err);
-  process.exit(1);
-});
-```
-
-### 5. Validar o script gerado
-
-```bash
-# Rodar em modo não-headless para visualizar
-npx tsx scripts/robots/{nome}.ts
-
-# Com Playwright test runner (se integrado ao projeto)
-npx playwright test scripts/robots/{nome}.ts
-```
-
-### Skills invocados durante a execução do skill
-
-| Passo | Skill | Condição |
-|-------|-------|----------|
-| — | Nenhuma — skill autocontida | — |
-
----
-
-## Árvore de Decisão
-
-```
-Produto tem conta Browserbase?       → env: "BROWSERBASE" (browser gerenciado em nuvem)
-Sem conta Browserbase?               → env: "LOCAL" (Chromium local, grátis)
-Passos envolvem login com 2FA?       → Coletar cookies/session manualmente e injetar
-Fluxo tem upload de arquivo?         → Usar page.setInputFiles() no Playwright final
-Fluxo precisa de múltiplas abas?     → Usar context.newPage() para cada aba
-Site usa iframes?                    → Stagehand suporta nativamente, Playwright: page.frameLocator()
-Seletor XPath muito longo/frágil?    → Simplificar para seletor semântico equivalente
-```
-
----
-
-## Regras
-
-### Nunca
-- Manter dependência do Stagehand no script final de produção
-- Hardcodar credenciais no script — sempre usar variáveis de ambiente
-- Usar seletores baseados em posição (ex: `(//div)[15]`) — frágeis demais
-- Ignorar `waitForLoadState` ou `waitForSelector` após navegações
-- Gerar script sem comentários mapeando os passos originais do produto
-
-### Sempre
-- Adicionar comentário no script final indicando que os seletores foram descobertos via Stagehand
-- Usar `try/finally` para garantir que o browser fecha mesmo em erros
-- Validar o resultado ao final (confirmar que o fluxo funcionou)
-- Preferir seletores semânticos (texto, role, aria) sobre XPath absolutos quando possível
-- Documentar no script qual foi o passo original descrito pelo produto
-
----
-
-## Tratamento de Erros
-
-### Stagehand não conseguiu executar um passo
-- Verificar se a página carregou (`waitForLoadState`)
-- Reformular a instrução natural — ser mais específico (ex: "clique no botão azul 'Enviar' no formulário de contato")
-- Usar `observe()` primeiro para ver o que está disponível na página
-
-### Seletor descoberto não funciona no Playwright
-- Simplificar o XPath retornado pelo `observe()`
-- Tentar equivalente com `page.getByRole()`, `page.getByText()`, `page.getByLabel()`
-- Inspecionar manualmente o elemento no DevTools como fallback
-
-### Site usa autenticação OAuth / SSO
-- Fazer login manual uma vez, exportar cookies: `context.storageState({ path: "auth.json" })`
-- Reutilizar o estado: `browser.newContext({ storageState: "auth.json" })`
-
-### Script falha em CI (headless)
-- Adicionar `--no-sandbox` no `chromium.launch({ args: ['--no-sandbox'] })`
-- Verificar timeouts — ambientes CI podem ser mais lentos
-
----
-
-## Checklist de Conclusão
-
-- [ ] Passo a passo coletado do produto/dev (em linguagem natural)
-- [ ] Script de exploração Stagehand criado e executado
-- [ ] Seletores reais coletados do output do `observe()`
-- [ ] Script Playwright final gerado sem dependência do Stagehand
-- [ ] Comentários mapeando passos originais → código
-- [ ] Credenciais em variáveis de ambiente (nunca hardcoded)
-- [ ] `try/finally` para fechar o browser
-- [ ] Validação ao final do fluxo
-- [ ] Script testado rodando localmente
-
----
-
-## Output
-
-| Artefato | Descrição |
-|----------|-----------|
-| `scripts/robots/explore-{nome}.ts` | Script temporário de exploração com Stagehand (não vai a prod) |
-| `scripts/robots/{nome}.ts` | Script final Playwright gerado com seletores reais |
-| `scripts/robots/explore-{nome}.log` | Log da exploração com seletores descobertos |
-
----
-
-## Mensagem de Conclusão
-
-```
-Robô gerado!
-
-Fluxo: {descrição do fluxo automatizado}
-Site alvo: {URL}
-Passos automatizados: {N passos}
-Seletores descobertos via: Stagehand observe()
-
-Arquivos:
-- scripts/robots/explore-{nome}.ts  ← script de exploração (pode descartar)
-- scripts/robots/{nome}.ts          ← robô Playwright pronto para produção
-
-Próximo passo: executar com `npx tsx scripts/robots/{nome}.ts`
-```
-
----
-
-## Recursos Adicionais
-
-- **Stagehand docs**: https://docs.stagehand.dev
-- **Skill relacionado**: `$IDE/skills/eng-scraper/SKILL.md` — para scraping/extração de dados
-- **Skill relacionado**: `$IDE/skills/eng-qa-e2e/SKILL.md` — para testes E2E com linguagem natural