feat(extractor): add Google News headlines extractor with Foxcape headless and URL resolution

- Add standalone CLI script scripts/extract_google_news.py for Google News RSS scraping - Integrate foxcape in headless mode as primary stealth anti-bot engine - Implement parallel article URL resolution using googlenewsdecoder and ThreadPoolExecutor - Support language and regional locale mapping (-l, --lang, --locale) - Implement real-time progress logging in stderr and --silent flag - Add unit, integration, and live E2E tests in tests/test_extract_google_news.py - Add full SpecKit documentation (specs/002-google-news-extractor/) - Create comprehensive README.md covering both NLP Classifier and Google News Extractor
2026-08-20 11:50:16 -03:00
parent 67cc40f91a
commit 6e3d57619b
59 changed files with 16118 additions and 2160 deletions
@@ -0,0 +1,49 @@
+# CLI Contract: Google News Headlines Extractor
+
+## 1. Comando e Argumentos
+
+### Sintaxe
+```bash
+python scripts/extract_google_news.py --query <KEYWORD> [--lang <LANG>] [--locale <LOCALE>] [--max-pages <PAGES>] [--output <FILE>] [--pretty] [--no-resolve-urls] [--silent]
+```
+
+### Argumentos de Linha de Comando
+
+| Flag / Argumento | Tipo | Obrigatório | Padrão | Descrição |
+| :--- | :--- | :--- | :--- | :--- |
+| `-q`, `--query`, `--keyword` | `str` | **Sim** | — | Termo ou expressão de pesquisa no Google News. |
+| `-l`, `--lang`, `--language` | `str` | Não | `"pt"` | Código do idioma (ex: `pt`, `en`, `es`, `de`, `fr`, `it`). |
+| `--locale`, `--country` | `str` | Não | `None` | Código do país/região (ex: `BR`, `US`, `GB`, `MX`, `ES`, `AR`). |
+| `-p`, `--max-pages` | `int` | Não | `1` | Quantidade de páginas a extrair (1 a 10, onde cada página possui até 10 itens). |
+| `-o`, `--output` | `str` | Não | `None` | Caminho de arquivo opcional para salvar o JSON resultante diretamente (cria diretórios pais automaticamente). |
+| `--pretty` | `flag` | Não | `False` | Formata o JSON emitido no stdout com indentação legível (2 espaços). |
+| `--no-resolve-urls` | `flag` | Não | `False` | Desativa a decodificação automática para as URLs originais dos veículos (mantém os links brutos do feed). |
+| `-s`, `--silent`, `--quiet` | `flag` | Não | `False` | Suprime mensagens informativas de progresso emitidas no `stderr`. |
+
+---
+
+## 2. Códigos de Saída (Exit Codes)
+
+| Código | Significado | Descrição |
+| :--- | :--- | :--- |
+| `0` | **Sucesso** | Extração concluída com êxito (mesmo que 0 notícias sejam encontradas). |
+| `1` | **Erro de Validação** | Parâmetro obrigatório ausente, valor inválido ou flag desconhecida. |
+| `2` | **Erro de Rede/Scraping/I/O** | Falha de conectividade, bloqueio não recuperável ou erro de gravação. |
+
+---
+
+## 3. Protocolo de Streams (Stdout / Stderr)
+
+- **`stdout`**: Exclusivo para o payload JSON estruturado de saída. Permite redirecionamento direto para pipes e arquivos:
+  ```bash
+  python scripts/extract_google_news.py -q "tecnologia" | jq '.items[].titulo'
+  ```
+- **`stderr`**: Exclusivo para logs informativos de progresso e mensagens de erro:
+  ```text
+  [INFO] 🔍 Consultando Google News: 'River Plate' (idioma: es, locale: AR, max_pages: 2)...
+  [INFO] 📥 Feed RSS recebido (162117 bytes).
+  [INFO] 📰 20 artigos extraídos do feed XML.
+  [INFO] 🔗 Decodificando 20 URLs do Google News para os portais reais...
+  [INFO] ✅ 20/20 URLs resolvidas com sucesso para os domínios de origem.
+  [INFO] 💾 Arquivo salvo com sucesso: 'out/river_plate.json' (20 notícias).
+  ```