jarvis-ai-framework 2.0.0 → 2.1.1

package/skills/eng-scraper/SKILL.md

@@ -145,446 +145,22 @@ curl -s "https://exemplo.com/robots.txt"
 
 > Se houver restrições legais ou éticas significativas, comunicar ao usuário antes de prosseguir.
 
-### Puppeteer — Ferramenta Principal (padrão do projeto)
-
-Puppeteer é a ferramenta padrão para scraping com browser headless. Todo código de scraping deve ser em TypeScript e, quando integrado ao sistema, implementado como `@Injectable()` NestJS.
-
-#### Setup básico
-
-```typescript
-import puppeteer, { Browser, Page } from 'puppeteer'
-
-async function createBrowser(): Promise<Browser> {
-  return puppeteer.launch({
-    headless: true,
-    args: [
-      '--no-sandbox',
-      '--disable-setuid-sandbox',
-      '--disable-blink-features=AutomationControlled',
-    ],
-  })
-}
-
-// ✅ Sempre fechar browser após uso
-async function withBrowser<T>(fn: (browser: Browser) => Promise<T>): Promise<T> {
-  const browser = await createBrowser()
-  try {
-    return await fn(browser)
-  } finally {
-    await browser.close()
-  }
-}
-```
-
-#### NestJS — ScraperService como @Injectable
-
-```typescript
-import { Injectable, Logger } from '@nestjs/common'
-import puppeteer, { Browser, Page } from 'puppeteer'
-
-@Injectable()
-export class ScraperService {
-  private readonly logger = new Logger(ScraperService.name)
-
-  async scrapeProducts(url: string): Promise<Product[]> {
-    const browser = await puppeteer.launch({ headless: true, args: ['--no-sandbox'] })
-
-    try {
-      const page = await browser.newPage()
-      await page.setUserAgent('Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...')
-
-      await page.goto(url, { waitUntil: 'networkidle2', timeout: 30_000 })
-      await page.waitForSelector('[data-testid="product-card"]', { timeout: 10_000 })
-
-      const products = await page.evaluate(() =>
-        Array.from(document.querySelectorAll('[data-testid="product-card"]')).map((card) => ({
-          name: card.querySelector('h2')?.textContent?.trim() ?? null,
-          price: card.querySelector('[data-price]')?.getAttribute('data-price') ?? null,
-          url: (card.querySelector('a') as HTMLAnchorElement)?.href ?? null,
-        }))
-      )
-
-      const valid = products.filter((p) => p.name && p.price)
-      if (valid.length < products.length) {
-        this.logger.warn(`${products.length - valid.length} produtos com dados incompletos ignorados`)
-      }
-
-      return valid as Product[]
-    } finally {
-      await browser.close()
-    }
-  }
-}
-```
-
-#### Interceptar chamadas de API interna
-
-```typescript
-// ✅ Mais estável que scraping de HTML — dados estruturados direto da API interna
-async function interceptApiData(url: string, apiPattern: RegExp): Promise<unknown[]> {
-  return withBrowser(async (browser) => {
-    const page = await browser.newPage()
-    const captured: unknown[] = []
-
-    await page.setRequestInterception(true)
-
-    page.on('request', (req) => req.continue())
-
-    page.on('response', async (response) => {
-      if (apiPattern.test(response.url()) && response.headers()['content-type']?.includes('json')) {
-        try {
-          captured.push(await response.json())
-        } catch {
-          // ignorar responses não-JSON
-        }
-      }
-    })
-
-    await page.goto(url, { waitUntil: 'networkidle2', timeout: 30_000 })
-
-    return captured
-  })
-}
-
-// Uso: interceptar chamadas de /api/products/*
-const data = await interceptApiData('https://loja.com/produtos', /\/api\/products/)
-```
-
-#### Paginação automática
-
-```typescript
-async function scrapeAllPages(baseUrl: string): Promise<unknown[]> {
-  return withBrowser(async (browser) => {
-    const page = await browser.newPage()
-    const allItems: unknown[] = []
-    let pageNum = 1
-    let hasNextPage = true
-
-    while (hasNextPage) {
-      await page.goto(`${baseUrl}?page=${pageNum}`, { waitUntil: 'networkidle2' })
-
-      const items = await page.evaluate(() =>
-        Array.from(document.querySelectorAll('.item')).map((el) => ({
-          title: el.querySelector('h3')?.textContent?.trim() ?? null,
-        }))
-      )
-
-      allItems.push(...items)
-
-      hasNextPage = (await page.$('[aria-label="Próxima página"]:not([disabled])')) !== null
-      pageNum++
-
-      await randomDelay(1000, 3000)
-    }
-
-    return allItems
-  })
-}
-```
-
-### Playwright — Alternativa (quando necessário)
-
-Usar Playwright quando Puppeteer não resolver o caso de uso (ex: multi-browser testing, maior controle de contexto).
-
-```typescript
-import { chromium } from 'playwright'
-
-// Mesma lógica do Puppeteer — API similar com pequenas diferenças:
-// page.goto(url, { waitUntil: 'networkidle' }) → sem o "2" no Playwright
-// page.$() → page.locator() é o padrão moderno no Playwright
-// page.evaluate() → idêntico
-```
-
-### Cheerio — Scraping de HTML Estático
-
-```typescript
-import * as cheerio from 'cheerio'
-
-async function scrapeWithCheerio(url: string) {
-  const response = await fetch(url, {
-    headers: {
-      'User-Agent': 'Mozilla/5.0 (compatible; MyBot/1.0; +https://meusite.com/bot)',
-      'Accept-Language': 'pt-BR,pt;q=0.9',
-    },
-  })
-
-  if (!response.ok) {
-    throw new Error(`HTTP ${response.status}: ${url}`)
-  }
-
-  const html = await response.text()
-  const $ = cheerio.load(html)
-
-  // ✅ Extração com Cheerio
-  const articles = $('article.post').map((_, el) => ({
-    title: $(el).find('h2').text().trim() || null,
-    date: $(el).find('time').attr('datetime') || null,
-    url: $(el).find('a.read-more').attr('href') || null,
-    summary: $(el).find('.excerpt').text().trim() || null,
-  })).get()
-
-  return articles.filter((a) => a.title && a.url)
-}
-```
-
-### Parsing de PDFs
-
-```typescript
-import pdfParse from 'pdf-parse'
-import { readFileSync } from 'fs'
-
-async function extractTextFromPdf(filePath: string): Promise<string> {
-  const buffer = readFileSync(filePath)
-  const { text, numpages } = await pdfParse(buffer)
-  console.log(`PDF processado: ${numpages} páginas`)
-  return text
-}
-
-// ✅ Extrair tabela de texto de PDF (regex + heurística)
-function extractTableFromText(text: string, headers: string[]): Record<string, string>[] {
-  const lines = text.split('\n').map((l) => l.trim()).filter(Boolean)
-  const results: Record<string, string>[] = []
-
-  for (const line of lines) {
-    // lógica específica para o formato do PDF alvo
-    const match = line.match(/(\w+)\s+([\d,.]+)\s+([\d,.]+)/)
-    if (match) {
-      results.push({
-        [headers[0]]: match[1],
-        [headers[1]]: match[2],
-        [headers[2]]: match[3],
-      })
-    }
-  }
-
-  return results
-}
-```
-
-### Técnicas Anti-Bot
-
-#### Headers realistas
-
-```typescript
-// ✅ Headers que imitam browser real
-const realisticHeaders = {
-  'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
-  'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8',
-  'Accept-Language': 'pt-BR,pt;q=0.9,en-US;q=0.8,en;q=0.7',
-  'Accept-Encoding': 'gzip, deflate, br',
-  'Connection': 'keep-alive',
-  'Upgrade-Insecure-Requests': '1',
-}
-```
-
-#### Rate limiting e delays aleatórios
-
-```typescript
-// ✅ Delay com jitter para comportamento orgânico
-function randomDelay(minMs: number, maxMs: number): Promise<void> {
-  const ms = Math.floor(Math.random() * (maxMs - minMs + 1)) + minMs
-  return new Promise((resolve) => setTimeout(resolve, ms))
-}
-
-// ✅ Controle de concorrência (evitar sobrecarga no alvo)
-import PQueue from 'p-queue'
-
-const queue = new PQueue({
-  concurrency: 2,         // máximo 2 requests simultâneos
-  intervalCap: 5,         // máximo 5 requests
-  interval: 10_000,       // por 10 segundos
-})
-
-async function scrapeUrls(urls: string[]) {
-  return Promise.all(
-    urls.map((url) => queue.add(async () => {
-      await randomDelay(500, 1500)
-      return scrapeUrl(url)
-    }))
-  )
-}
-```
-
-#### Puppeteer — reduzir fingerprint de automação
-
-```typescript
-import puppeteer from 'puppeteer'
-import { executablePath } from 'puppeteer'
-
-// ✅ Ocultar sinais de automação via page.evaluateOnNewDocument
-async function createStealthPage(browser: Browser): Promise<Page> {
-  const page = await browser.newPage()
-
-  await page.setUserAgent(
-    'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36'
-  )
-
-  await page.setViewport({ width: 1366, height: 768 })
-
-  // Remover propriedades que identificam automação
-  await page.evaluateOnNewDocument(() => {
-    Object.defineProperty(navigator, 'webdriver', { get: () => undefined })
-    Object.defineProperty(navigator, 'plugins', { get: () => [1, 2, 3] })
-    Object.defineProperty(navigator, 'languages', { get: () => ['pt-BR', 'pt', 'en'] })
-  })
-
-  return page
-}
-```
-
-#### Rotação de proxies
-
-```typescript
-// ✅ Pool de proxies com rotação
-const proxies = [
-  'http://user:pass@proxy1:8080',
-  'http://user:pass@proxy2:8080',
-  'http://user:pass@proxy3:8080',
-]
-
-function getRandomProxy(): string {
-  return proxies[Math.floor(Math.random() * proxies.length)]
-}
-
-const browser = await puppeteer.launch({
-  headless: true,
-  args: [`--proxy-server=${getRandomProxy()}`, '--no-sandbox'],
-})
-```
-
-### 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}` }
-)
-```
+### Referências (leia só o tema que a tarefa pedir)
 
-#### Detectar mudanças de estrutura
+Leia **só** o arquivo do tema que a tarefa pedir; o restante fica fora do contexto.
 
-```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)
+| Tema | Quando ler | Arquivo |
+|------|-----------|---------|
+| Puppeteer | A tarefa usar Puppeteer (ferramenta principal do projeto) para navegar e extrair dados | `references/1-puppeteer.md` |
+| Playwright, Cheerio e parsing de PDFs | A tarefa exigir Playwright, scraping de HTML estático com Cheerio ou extração de PDFs | `references/2-playwright-cheerio-pdf.md` |
+| Técnicas Anti-Bot | O site bloquear requests (403/429, captcha, fingerprint) | `references/3-anti-bot.md` |
+| Resiliência, ETL leve e monitoramento de mudanças | A tarefa precisar de retry, pipeline ETL leve ou monitoramento de mudanças no site | `references/4-resiliencia-etl-monitoramento.md` |
 
-  const issues = data.filter((item) =>
-    requiredFields.some((field) => !item[field as keyof typeof item])
-  )
+### Skills invocados durante a execução do skill
 
-  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 }
-}
-```
+| Passo | Skill | Condição |
+|-------|-------|----------|
+| — | Nenhuma — skill autocontida | — |
 
 ---
 

package/skills/eng-scraper/references/1-puppeteer.md

@@ -0,0 +1,140 @@
+# Puppeteer
+
+> Parte do skill `eng-scraper`. Leia este arquivo quando a tarefa usar Puppeteer (ferramenta principal do projeto) para navegar e extrair dados.
+
+### Puppeteer — Ferramenta Principal (padrão do projeto)
+
+Puppeteer é a ferramenta padrão para scraping com browser headless. Todo código de scraping deve ser em TypeScript e, quando integrado ao sistema, implementado como `@Injectable()` NestJS.
+
+#### Setup básico
+
+```typescript
+import puppeteer, { Browser, Page } from 'puppeteer'
+
+async function createBrowser(): Promise<Browser> {
+  return puppeteer.launch({
+    headless: true,
+    args: [
+      '--no-sandbox',
+      '--disable-setuid-sandbox',
+      '--disable-blink-features=AutomationControlled',
+    ],
+  })
+}
+
+// ✅ Sempre fechar browser após uso
+async function withBrowser<T>(fn: (browser: Browser) => Promise<T>): Promise<T> {
+  const browser = await createBrowser()
+  try {
+    return await fn(browser)
+  } finally {
+    await browser.close()
+  }
+}
+```
+
+#### NestJS — ScraperService como @Injectable
+
+```typescript
+import { Injectable, Logger } from '@nestjs/common'
+import puppeteer, { Browser, Page } from 'puppeteer'
+
+@Injectable()
+export class ScraperService {
+  private readonly logger = new Logger(ScraperService.name)
+
+  async scrapeProducts(url: string): Promise<Product[]> {
+    const browser = await puppeteer.launch({ headless: true, args: ['--no-sandbox'] })
+
+    try {
+      const page = await browser.newPage()
+      await page.setUserAgent('Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...')
+
+      await page.goto(url, { waitUntil: 'networkidle2', timeout: 30_000 })
+      await page.waitForSelector('[data-testid="product-card"]', { timeout: 10_000 })
+
+      const products = await page.evaluate(() =>
+        Array.from(document.querySelectorAll('[data-testid="product-card"]')).map((card) => ({
+          name: card.querySelector('h2')?.textContent?.trim() ?? null,
+          price: card.querySelector('[data-price]')?.getAttribute('data-price') ?? null,
+          url: (card.querySelector('a') as HTMLAnchorElement)?.href ?? null,
+        }))
+      )
+
+      const valid = products.filter((p) => p.name && p.price)
+      if (valid.length < products.length) {
+        this.logger.warn(`${products.length - valid.length} produtos com dados incompletos ignorados`)
+      }
+
+      return valid as Product[]
+    } finally {
+      await browser.close()
+    }
+  }
+}
+```
+
+#### Interceptar chamadas de API interna
+
+```typescript
+// ✅ Mais estável que scraping de HTML — dados estruturados direto da API interna
+async function interceptApiData(url: string, apiPattern: RegExp): Promise<unknown[]> {
+  return withBrowser(async (browser) => {
+    const page = await browser.newPage()
+    const captured: unknown[] = []
+
+    await page.setRequestInterception(true)
+
+    page.on('request', (req) => req.continue())
+
+    page.on('response', async (response) => {
+      if (apiPattern.test(response.url()) && response.headers()['content-type']?.includes('json')) {
+        try {
+          captured.push(await response.json())
+        } catch {
+          // ignorar responses não-JSON
+        }
+      }
+    })
+
+    await page.goto(url, { waitUntil: 'networkidle2', timeout: 30_000 })
+
+    return captured
+  })
+}
+
+// Uso: interceptar chamadas de /api/products/*
+const data = await interceptApiData('https://loja.com/produtos', /\/api\/products/)
+```
+
+#### Paginação automática
+
+```typescript
+async function scrapeAllPages(baseUrl: string): Promise<unknown[]> {
+  return withBrowser(async (browser) => {
+    const page = await browser.newPage()
+    const allItems: unknown[] = []
+    let pageNum = 1
+    let hasNextPage = true
+
+    while (hasNextPage) {
+      await page.goto(`${baseUrl}?page=${pageNum}`, { waitUntil: 'networkidle2' })
+
+      const items = await page.evaluate(() =>
+        Array.from(document.querySelectorAll('.item')).map((el) => ({
+          title: el.querySelector('h3')?.textContent?.trim() ?? null,
+        }))
+      )
+
+      allItems.push(...items)
+
+      hasNextPage = (await page.$('[aria-label="Próxima página"]:not([disabled])')) !== null
+      pageNum++
+
+      await randomDelay(1000, 3000)
+    }
+
+    return allItems
+  })
+}
+```

package/skills/eng-scraper/references/2-playwright-cheerio-pdf.md

@@ -0,0 +1,82 @@
+# Playwright, Cheerio e parsing de PDFs
+
+> Parte do skill `eng-scraper`. Leia este arquivo quando a tarefa exigir Playwright, scraping de HTML estático com Cheerio ou extração de PDFs.
+
+### Playwright — Alternativa (quando necessário)
+
+Usar Playwright quando Puppeteer não resolver o caso de uso (ex: multi-browser testing, maior controle de contexto).
+
+```typescript
+import { chromium } from 'playwright'
+
+// Mesma lógica do Puppeteer — API similar com pequenas diferenças:
+// page.goto(url, { waitUntil: 'networkidle' }) → sem o "2" no Playwright
+// page.$() → page.locator() é o padrão moderno no Playwright
+// page.evaluate() → idêntico
+```
+
+### Cheerio — Scraping de HTML Estático
+
+```typescript
+import * as cheerio from 'cheerio'
+
+async function scrapeWithCheerio(url: string) {
+  const response = await fetch(url, {
+    headers: {
+      'User-Agent': 'Mozilla/5.0 (compatible; MyBot/1.0; +https://meusite.com/bot)',
+      'Accept-Language': 'pt-BR,pt;q=0.9',
+    },
+  })
+
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status}: ${url}`)
+  }
+
+  const html = await response.text()
+  const $ = cheerio.load(html)
+
+  // ✅ Extração com Cheerio
+  const articles = $('article.post').map((_, el) => ({
+    title: $(el).find('h2').text().trim() || null,
+    date: $(el).find('time').attr('datetime') || null,
+    url: $(el).find('a.read-more').attr('href') || null,
+    summary: $(el).find('.excerpt').text().trim() || null,
+  })).get()
+
+  return articles.filter((a) => a.title && a.url)
+}
+```
+
+### Parsing de PDFs
+
+```typescript
+import pdfParse from 'pdf-parse'
+import { readFileSync } from 'fs'
+
+async function extractTextFromPdf(filePath: string): Promise<string> {
+  const buffer = readFileSync(filePath)
+  const { text, numpages } = await pdfParse(buffer)
+  console.log(`PDF processado: ${numpages} páginas`)
+  return text
+}
+
+// ✅ Extrair tabela de texto de PDF (regex + heurística)
+function extractTableFromText(text: string, headers: string[]): Record<string, string>[] {
+  const lines = text.split('\n').map((l) => l.trim()).filter(Boolean)
+  const results: Record<string, string>[] = []
+
+  for (const line of lines) {
+    // lógica específica para o formato do PDF alvo
+    const match = line.match(/(\w+)\s+([\d,.]+)\s+([\d,.]+)/)
+    if (match) {
+      results.push({
+        [headers[0]]: match[1],
+        [headers[1]]: match[2],
+        [headers[2]]: match[3],
+      })
+    }
+  }
+
+  return results
+}
+```