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,56 @@
+# General Readiness Checklist: Google News Headlines Extractor
+
+**Purpose**: Validate the completeness, clarity, consistency, and testability of requirements for the standalone Google News CLI extractor before implementation.
+**Created**: 2026-08-20
+**Validated**: 2026-08-20 (Audited against guide, spec, research, plan, data-model, and cli_contract)
+**Feature**: [spec.md](../spec.md) | [plan.md](../plan.md) | [cli_contract.md](../contracts/cli_contract.md) | [data-model.md](../data-model.md) | [research.md](../research.md)
+
+**Note**: This custom checklist is generated by the `/speckit-checklist` command based on feature context and requirements.
+**Review Ownership**: This checklist is a reviewer-owned requirements-quality review artifact. Mark an item `[x]` only when the reviewer determines the requirements-quality criterion is satisfied.
+**Marker Semantics**: `[x]` means the criterion has been reviewed and satisfied for requirements quality. It does not mean implementation work is complete.
+
+## CLI Interface & Parameter Contracts
+
+- [x] CHK001 - Are all required CLI arguments (e.g., `--query` / `--keyword`) and their aliases explicitly specified? [Completeness, Spec §FR-003, Contract §1]
+- [x] CHK002 - Are default values clearly defined for optional parameters (`--lang`, `--locale`, `--max-pages`)? [Clarity, Spec §FR-003, Contract §1]
+- [x] CHK003 - Is the allowed range for pagination (`1` to `10` pages) explicitly bounded and unambiguous? [Clarity, Spec §FR-006, DataModel §1.1]
+- [x] CHK004 - Are exit codes defined for each distinct execution outcome (success, validation failure, scraping/network error)? [Completeness, Contract §2]
+- [x] CHK005 - Are stream separation requirements (clean JSON on `stdout`, diagnostics/errors on `stderr`) strictly documented? [Consistency, Spec §FR-009, Contract §3]
+
+## Scraping Engine & Feed Mapping
+
+- [x] CHK006 - Is the integration role of the `foxcape` library and its anti-bot evasion responsibilities clearly documented? [Completeness, Spec §FR-002, Plan §Summary]
+- [x] CHK007 - Is the RSS search URL template and its encoding rules (`q`, `hl`, `gl`, `ceid`) precisely defined? [Clarity, Research §Decision 2, Research §Decision 3]
+- [x] CHK008 - Is the locale inference fallback rule (when `--locale` is omitted) explicitly specified across standard language codes? [Consistency, Spec §FR-005, Research §Decision 3]
+- [x] CHK009 - Is the override behavior when a custom `--locale` is passed alongside a different language documented? [Completeness, Spec §User Story 2, Research §Decision 3]
+
+## Data Sanitization & Article Extraction
+
+- [x] CHK010 - Are the target extraction fields (`titulo`, `subtitulo`, `quando_publicado`, `url`, `pagina`) mapped to specific RSS XML tags? [Completeness, Spec §FR-007, DataModel §1.2]
+- [x] CHK011 - Is the HTML tag stripping requirement for description/snippets specified with unambiguous criteria? [Clarity, Spec §FR-008, SC-003]
+- [x] CHK012 - Is the deduplication rule for subtitles identical to titles clearly documented with expected null/empty behavior? [Consistency, Spec §Edge Cases, DataModel §1.2]
+- [x] CHK013 - Are filtering rules specified for discarding incomplete items missing title or link? [Coverage, Spec §Edge Cases, SC-002]
+- [x] CHK014 - Is the consolidated JSON schema defined with all mandatory metadata fields (`query`, `language`, `locale`, `total_itens`, `scraped_at`)? [Completeness, Spec §FR-009, DataModel §2]
+
+## Error Handling & Edge Cases
+
+- [x] CHK015 - Are validation requirements specified for empty or whitespace-only search keywords? [Coverage, Spec §Edge Cases, Spec §FR-010]
+- [x] CHK016 - Is the behavior for queries yielding zero matching news articles specified without raising unhandled errors? [Coverage, Spec §User Story 1, SC-004]
+- [x] CHK017 - Are network interruption or upstream HTTP block error handling requirements documented? [Coverage, Spec §Edge Cases, Contract §2]
+- [x] CHK018 - Are character encoding and URL parameter escaping requirements documented for special characters and accents? [Clarity, Spec §Edge Cases]
+
+## Non-Functional & Operational Readiness
+
+- [x] CHK019 - Is the performance target (< 2.0s for standard single-page extractions) quantified with measurable criteria? [Measurability, Spec §SC-001, Plan §Technical Context]
+- [x] CHK020 - Are JSON output compatibility requirements with terminal streaming tools (e.g., `jq`, shell pipes) defined? [Completeness, Spec §SC-005, Contract §3]
+- [x] CHK021 - Is the execution isolation assumption (pure RSS feed extraction without mandatory Playwright browser runtime) clearly stated? [Traceability, Spec §Assumptions, Research §Decision 1]
+
+## Notes
+
+- Mark items `[x]` only after review confirms the requirement-quality criterion is satisfied
+- Leave items unchecked when they still require clarification, correction, or reviewer evaluation
+- `/speckit-implement` reads checklist checkbox state as a gate and must not modify markers
+- `checklists/requirements.md` has a separate built-in lifecycle maintained by `/speckit-specify` and `/speckit-clarify`
+- Add comments or findings inline
+- Link to relevant resources or documentation
+- Items are numbered sequentially for easy reference
@@ -0,0 +1,34 @@
+# Specification Quality Checklist: Google News Headlines Extractor
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-08-20
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- Feature spec ready for planning phase (`/speckit-plan`).
@@ -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).
+  ```
@@ -0,0 +1,72 @@
+# Data Model: Google News Headlines Extractor
+
+## 1. Entidades de Domínio & DTOs
+
+### 1.1 SearchQuery (Parâmetros da Busca)
+Representa os parâmetros de entrada sanitizados e validados para a consulta ao feed do Google News.
+
+| Atributo | Tipo | Obrigatório | Padrão | Validação / Regra |
+| :--- | :--- | :--- | :--- | :--- |
+| `keyword` | `str` | Sim | — | Não vazio, sem espaços em branco apenas. |
+| `language` | `str` | Não | `"pt"` | Mínimo 2 caracteres, normalizado em minúsculas. |
+| `locale` | `str | None` | Não | `None` | Código ISO alpha-2 de país ou inferido do idioma. |
+| `max_pages` | `int` | Não | `1` | Intervalo entre `1` e `10` (correspondente a 10 até 100 itens). |
+
+### 1.2 NewsArticle (Item de Notícia)
+Representa uma notícia individual extraída do feed RSS.
+
+| Atributo | Tipo | Descrição | Origem no Feed |
+| :--- | :--- | :--- | :--- |
+| `titulo` | `str` | Título da manchete | Nó `<title>` |
+| `subtitulo` | `str | None` | Resumo textual limpo de tags HTML (ou `None` se ausente/idêntico ao título) | Nó `<description>` sanitizado |
+| `quando_publicado` | `str | None` | Data original de publicação do feed (RFC 822) | Nó `<pubDate>` |
+| `url` | `str` | Link de acesso à notícia | Nó `<link>` |
+| `pagina` | `int` | Número da página lógica calculada | `(idx // 10) + 1` |
+
+### 1.3 ExtractionResult (Saída Estruturada Consolidada)
+Pacote consolidado emitido para consumo/stdout.
+
+| Atributo | Tipo | Descrição |
+| :--- | :--- | :--- |
+| `query` | `str` | Palavra-chave/expressão pesquisada |
+| `language` | `str` | Código do idioma utilizado na busca |
+| `locale` | `str` | Código da região/país utilizado |
+| `total_paginas` | `int` | Total de páginas lógicas solicitadas/extraídas |
+| `total_itens` | `int` | Quantidade total de notícias retornadas na lista |
+| `scraped_at` | `str` | Data/hora ISO 8601 UTC do momento da extração |
+| `items` | `list[NewsArticle]` | Lista ordenada de notícias |
+
+---
+
+## 2. Esquema JSON de Saída
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ExtractionResult",
+  "type": "object",
+  "required": ["query", "language", "locale", "total_paginas", "total_itens", "scraped_at", "items"],
+  "properties": {
+    "query": { "type": "string" },
+    "language": { "type": "string" },
+    "locale": { "type": "string" },
+    "total_paginas": { "type": "integer", "minimum": 1, "maximum": 10 },
+    "total_itens": { "type": "integer", "minimum": 0 },
+    "scraped_at": { "type": "string", "format": "date-time" },
+    "items": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["titulo", "url", "pagina"],
+        "properties": {
+          "titulo": { "type": "string" },
+          "subtitulo": { "type": ["string", "null"] },
+          "quando_publicado": { "type": ["string", "null"] },
+          "url": { "type": "string", "format": "uri" },
+          "pagina": { "type": "integer", "minimum": 1 }
+        }
+      }
+    }
+  }
+}
+```
@@ -0,0 +1,74 @@
+# Implementation Plan: Google News Headlines Extractor
+
+**Branch**: `002-google-news-extractor` | **Date**: 2026-08-20 | **Spec**: [spec.md](./spec.md)
+
+**Input**: Feature specification from `specs/002-google-news-extractor/spec.md`
+
+## Summary
+
+Implementar um script CLI Python simples, robusto e autônomo ([`scripts/extract_google_news.py`](file:///c:/Users/aferr/Projects/AFTech/DunaMedia/TextNLPClassifierApp/scripts/extract_google_news.py)) para extrair manchetes do Google News RSS por assunto, idioma e região geográfica (*locale*). A solução utiliza a biblioteca [`foxcape`](https://pypi.org/project/foxcape/) em modo `headless=True` para garantir evasão anti-bot stealth, a biblioteca [`googlenewsdecoder`](https://pypi.org/project/googlenewsdecoder/) para resolver automaticamente as URLs intermediárias para os links finais dos portais de notícias em paralelo (`ThreadPoolExecutor`), e logging em tempo real via `sys.stderr`.
+
+## Technical Context
+
+**Language/Version**: Python >= 3.10 (3.11 / 3.12 / 3.13 / 3.14)  
+**Primary Dependencies**:
+* `foxcape>=0.1.1` (scraping stealth & evasão anti-bot Camoufox em modo headless)
+* `googlenewsdecoder>=0.1.7` (decodificação de URLs intermediárias do Google News)
+* `selectolax>=0.3.27` (parser ultra-rápido de nós e atributos)
+* `beautifulsoup4>=4.12.0` (limpeza HTML e higienização de resumos/snippets)
+* `argparse` (parser CLI na biblioteca padrão)
+* `concurrent.futures` (resolução paralela em pool de threads)
+
+**Storage**: N/A (stateless; saída via `stdout` ou arquivo especificado por flag `-o / --output`)  
+**Testing**: `pytest` com fixtures de feeds RSS, testes unitários mockados e testes End-to-End (E2E) ao vivo  
+**Target Platform**: Multiplataforma (Windows / Linux / macOS)  
+**Project Type**: Standalone CLI script + módulo utilitário de scripts  
+**Constraints**: Separação estrita de streams (`stdout` para JSON e `stderr` para logs informativos/erros)  
+
+## Architecture & Pipeline
+
+```mermaid
+flowchart LR
+    A[SearchQuery CLI] --> B[Foxcape Headless Fetch]
+    B --> C[parse_google_news_rss XML/HTML]
+    C --> D[ThreadPoolExecutor URL Resolution]
+    D --> E[ExtractionResult JSON Output]
+    E --> F[stdout / File Output]
+```
+
+1. **Ingestão & Validação**: `SearchQuery` valida palavra-chave não-vazia, idioma e limites de páginas (1 a 10).
+2. **Coleta RSS via Foxcape**: `Foxcape.fetch(url, config=FoxcapeConfig(headless=True))` busca o feed com evasões anti-bot.
+3. **Higienização XML/HTML**: `parse_google_news_rss` extrai nós, limpa resumos com `BeautifulSoup` e deduplica subtítulos redundantes.
+4. **Decodificação de Links**: `resolve_articles_urls` decodifica as URLs intermediárias do Google News em paralelo via `googlenewsdecoder`.
+5. **Emissão Estruturada**: JSON formatado no `stdout` ou gravado em arquivo (`--output`).
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/002-google-news-extractor/
+├── spec.md              # Especificação de requisitos da feature
+├── plan.md              # Este plano de implementação
+├── research.md          # Pesquisa técnica e decisões de design
+├── data-model.md        # Entidades, DTOs e esquema JSON
+├── contracts/
+│   └── cli_contract.md  # Contrato de argumentos CLI e I/O streams
+├── quickstart.md        # Guia rápido de execução e validação
+└── checklists/
+    ├── requirements.md  # Checklist de qualidade dos requisitos
+    └── readiness.md     # Checklist de prontidão e completude
+```
+
+### Source Code
+
+```text
+scripts/
+├── __init__.py                # Identificador de pacote Python
+└── extract_google_news.py     # Script CLI principal e lógica de extração
+
+tests/
+├── fixtures/
+│   └── google_news_sample.xml # Amostra de feed RSS para testes offline
+└── test_extract_google_news.py# Testes unitários, integração e E2E ao vivo
+```
@@ -0,0 +1,78 @@
+# Quickstart: Google News Headlines Extractor
+
+Guia rápido para execução e validação de ponta a ponta do extrator de notícias via linha de comando.
+
+---
+
+## 1. Pré-requisitos e Instalação
+
+Instale as dependências necessárias no ambiente Python:
+```bash
+pip install -r requirements.txt
+```
+
+Baixe os binários de browser stealth do Camoufox (executado uma única vez):
+```bash
+python -m camoufox fetch
+```
+
+---
+
+## 2. Cenários Práticos de Uso
+
+### Cenário 1: River Plate — Argentina (Espanhol / 2 Páginas / Salvar em Arquivo)
+```bash
+python scripts/extract_google_news.py -q "River Plate" -l es --locale AR -p 2 -o out/river_plate.json
+```
+* **Logs no terminal**:
+  ```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).
+  ```
+
+---
+
+### Cenário 2: Cruzeiro — Brasil (Português / Formatado no Terminal)
+```bash
+python scripts/extract_google_news.py --query "Cruzeiro" --lang pt --locale BR --pretty
+```
+* Retorna JSON formatado com 10 manchetes e links diretos (*ge.globo.com, lance.com.br, gazetaesportiva.com*).
+
+---
+
+### Cenário 3: Fórmula 1 — Reino Unido (Inglês)
+```bash
+python scripts/extract_google_news.py --query "Formula 1" --lang en --locale GB --pretty
+```
+* Retorna notícias de veículos britânicos (*BBC Sport, Sky Sports F1, Autosport*).
+
+---
+
+### Cenário 4: Integração em Pipeline com `jq` (Modo Silencioso)
+```bash
+python scripts/extract_google_news.py -q "inteligência artificial" -s | jq '.items[].url'
+```
+
+---
+
+### Cenário 5: Extração Rápida com Links Brutos (Sem Resolução de URLs)
+```bash
+python scripts/extract_google_news.py -q "São Paulo" --no-resolve-urls --pretty
+```
+
+---
+
+## 3. Validação dos Testes Automatizados e Linter
+
+```bash
+# Executa todos os testes unitários e E2E ao vivo
+pytest tests/test_extract_google_news.py -v
+
+# Validação estática com Ruff e Mypy
+ruff check scripts/extract_google_news.py tests/test_extract_google_news.py
+mypy scripts/ tests/test_extract_google_news.py
+```
@@ -0,0 +1,47 @@
+# Research: Google News Headlines Extractor
+
+## 1. Technical Decisions & Tradeoffs
+
+### Decision 1: Motor de Requisição e Scraping com `foxcape` em Modo Headless
+- **Decision**: Adotar o pacote `foxcape` com `FoxcapeConfig(headless=True, humanize=False)` como motor de requisição primário.
+- **Rationale**: `foxcape` integra Camoufox e BeautifulSoup com evasões de fingerprinting TLS, runtime JS e headers avançados, impedindo bloqueios (429/403/Captchas) frequentes do Google News. A configuração `headless=True` garante que a execução ocorra 100% em segundo plano sem abrir janelas gráficas no sistema.
+- **Alternatives Considered**:
+  - `curl_cffi` + `beautifulsoup4` manual: Boa alternativa, mas exige orquestração manual de impersonação de TLS e headers.
+  - `requests` padrão: Alto risco de bloqueio anti-bot pelo Google News.
+  - Foxcape padrão sem configuração (`headless=False`): Abre janela visual do Firefox indesejada em execuções CLI e servidores.
+
+---
+
+### Decision 2: Endpoint RSS do Google News vs. Scraping de DOM
+- **Decision**: Utilizar o endpoint oficial de busca RSS do Google News: `https://news.google.com/rss/search?q={query}&hl={hl}&gl={gl}&ceid={gl}:{hl}`.
+- **Rationale**: Formato estruturado em XML padrão, com carregamento rápido e direto de todos os metadados necessários (`title`, `link`, `pubDate`, `description`), sem necessidade de lidar com seletores CSS voláteis da interface web renderizada.
+- **Alternatives Considered**:
+  - Scraping direto da interface HTML do Google News (`news.google.com/search`): Classes CSS ofuscadas e alteradas frequentemente pelo Google, quebrando facilmente a extração.
+
+---
+
+### Decision 3: Mapeamento de Idioma e Locale (`hl`, `gl`, `ceid`)
+- **Decision**: Tabela de mapeamento determinística com fallback dinâmico.
+  - `pt` → `hl=pt-BR`, `gl=BR`, `ceid=BR:pt-BR`
+  - `es` → `hl=es-419`, `gl=AR`, `ceid=AR:es-419`
+  - `en` → `hl=en-US`, `gl=US`, `ceid=US:en-US`
+  - `de` → `hl=de`, `gl=DE`, `ceid=DE:de`
+  - `fr` → `hl=fr`, `gl=FR`, `ceid=FR:fr`
+  - `it` → `hl=it`, `gl=IT`, `ceid=IT:it`
+  - Customizado: se fornecido `--locale MX`, sobrescreve o `gl` e ajusta `ceid={gl}:{hl}`.
+- **Rationale**: Garante notícias contextualmente adequadas por país sem que o usuário precise memorizar os códigos técnicos internos do Google News.
+
+---
+
+### Decision 4: Resolução de URLs do Google News via `googlenewsdecoder`
+- **Decision**: Resolver automaticamente as URLs intermediárias (`news.google.com/rss/articles/CBMi...`) para os links originais dos veículos de imprensa em lote com `concurrent.futures.ThreadPoolExecutor(max_workers=5)`.
+- **Rationale**: Os links gerados pelo Google News contêm tokens RPC intermediários que dificultam a leitura e ingestão direta. A decodificação em lote resolve até 50 URLs em menos de 1 segundo sem sobrecarga.
+- **Alternatives Considered**:
+  - Resolução via Playwright headless para cada link: Muito lenta para listas de 20 a 50 notícias (demora 30 a 60 segundos).
+  - Manter apenas a URL do Google News: Prejudica o usuário e sistemas downstream que precisam do domínio e link real do portal de notícias.
+
+---
+
+### Decision 5: Logging em Tempo Real no `stderr` e Segregação de Streams
+- **Decision**: Enviar mensagens de status (`[INFO] ...`) para `sys.stderr` e reservar `sys.stdout` exclusivamente para o JSON.
+- **Rationale**: Permite que o operador acompanhe o progresso em tempo real no terminal (`Consultando...`, `Decodificando URLs...`, `Arquivo salvo...`) sem quebrar a interoperabilidade com ferramentas de pipe como `jq` ou redirecionamentos de arquivo.
@@ -0,0 +1,98 @@
+# Feature Specification: Google News Headlines Extractor
+
+**Feature Branch**: `002-google-news-extractor`  
+**Created**: 2026-08-20  
+**Status**: Implemented & Validated  
+**Input**: User description: "Extrator de manchetes do Google News de acordo com assunto, idioma, locale, com Foxcape headless, resolução de URLs reais e logging"
+
+---
+
+## Clarifications
+
+### Session 2026-08-20
+- Q: Como o extrator de notícias do Google News deve ser disponibilizado e consumido dentro do projeto? → A: Apenas Script CLI autônomo para execução direta via linha de comando no terminal (`scripts/extract_google_news.py`).
+- Q: Qual biblioteca/mecanismo de requisição e raspagem deve ser utilizado no script CLI? → A: Biblioteca `foxcape` (https://pypi.org/project/foxcape/) em modo `headless=True` com proteção anti-bot e fingerprinting stealth.
+- Q: Como lidar com as URLs intermediárias do Google News? → A: Resolução e decodificação automática das URLs intermediárias (`https://news.google.com/rss/articles/...`) para as URLs reais e finais dos portais de notícias via `googlenewsdecoder`.
+- Q: Como acompanhar o progresso de extração no terminal? → A: Logs informativos em tempo real enviados exclusivamente para `sys.stderr`, mantendo `sys.stdout` limpo para pipes JSON e suportando a flag `-s / --silent`.
+
+---
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - Extração Básica de Notícias com URLs Finais Resolvidas (Priority: P1) 🌟 MVP
+
+Como analista ou operador no terminal, quero fornecer um termo de busca e um idioma de interesse via linha de comando para obter rapidamente uma lista estruturada de manchetes recentes com as URLs finais reais dos veículos de imprensa (ex: *Olé, TyC Sports, ge, ESPN*).
+
+**Why this priority**: É o valor fundamental do produto. Sem a capacidade de buscar, obter manchetes e fornecer os links diretos dos veículos, o extrator não cumpre sua função de pesquisa e ingestão.
+
+**Independent Test**: Executar `python scripts/extract_google_news.py -q "River Plate" -l es --locale AR -p 1` e verificar se o JSON retornado contém notícias com URLs apontando para os domínios finais (`tycsports.com`, `ole.com.ar`, etc.).
+
+**Acceptance Scenarios**:
+1. **Given** um termo de busca válido e idioma, **When** o script for executado com o motor `foxcape` em modo headless, **Then** o sistema extrai o feed RSS e decodifica as URLs de cada artigo para os sites de origem.
+2. **Given** um termo de busca sem notícias correspondentes, **When** o script for executado, **Then** o sistema retorna uma coleção vazia com código de saída 0.
+
+---
+
+### User Story 2 - Filtragem Regional e Edição Geográfica (Priority: P2)
+
+Como usuário que monitora notícias em mercados específicos, quero definir a região/país geográfica (*locale*) além do idioma (por exemplo, espanhol da Argentina `--locale AR` vs. México `--locale MX`, ou inglês do Reino Unido `--locale GB` vs. Estados Unidos `--locale US`) para receber manchetes contextualmente relevantes àquele território.
+
+**Why this priority**: Garante relevância e precisão geográfica para análises de mídia multinacionais e segmentadas.
+
+**Independent Test**: Executar o script com idioma "es" e locale "AR" e verificar que portais e manchetes são da Argentina.
+
+**Acceptance Scenarios**:
+1. **Given** um termo de busca, idioma "es" e país/região "AR", **When** o script CLI for executado, **Then** as manchetes retornadas priorizam a edição e veículos argentinos.
+2. **Given** um idioma informado sem país explícito (ex: "pt"), **When** o script for solicitado, **Then** o sistema aplica o mapeamento padrão correspondente (ex: Brasil / pt-BR).
+
+---
+
+### User Story 3 - Paginação, Exportação em Arquivo e Feedback Visual (Priority: P3)
+
+Como operador de automação de dados, quero parametrizar o número de páginas de resultados (`--max-pages 1..10`), exportar direto para arquivo (`--output`) e acompanhar o progresso no terminal com mensagens descritivas de log.
+
+**Why this priority**: Permite flexibilidade de uso em rotinas batch, pipelines de ETL e depuração interativa.
+
+**Independent Test**: Executar com `-p 2 -o out/resultado.json` e verificar criação do arquivo com diretórios pais automáticos e logs em `stderr`.
+
+**Acceptance Scenarios**:
+1. **Given** uma execução CLI com `-p 2 -o out/teste.json`, **When** o processo é executado, **Then** o terminal exibe logs em `stderr` (`[INFO] 🔍 Consultando...`, `[INFO] 🔗 Decodificando...`, `[INFO] 💾 Arquivo salvo...`) e grava o JSON final com 20 itens.
+2. **Given** o uso da flag `-s` ou `--silent`, **When** o script é executado, **Then** os logs em `stderr` são suprimidos.
+
+---
+
+## Edge Cases
+
+- **Termo de busca vazio ou composto apenas por espaços**: O script rejeita a solicitação com mensagem de erro em `stderr` e código de saída 1.
+- **Falha de conectividade ou bloqueio**: O Foxcape executa com evasões anti-bot em modo headless, com captura de exceções e emissão de erro em `stderr` com código de saída 2.
+- **Resumo da notícia idêntico ao título**: Subtítulo redundante vira `None`.
+- **Caminho de saída em pasta inexistente**: O script cria os diretórios pais automaticamente antes de salvar.
+- **Falha na decodificação de URL específica**: Mantém a URL original como fallback gracioso sem abortar a execução dos demais itens.
+
+---
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: O sistema DEVE ser disponibilizado como script CLI autônomo em `scripts/extract_google_news.py`.
+- **FR-002**: O script DEVE utilizar a biblioteca `foxcape` com `FoxcapeConfig(headless=True)` como motor primário de requisição com proteção anti-bot.
+- **FR-003**: O CLI DEVE aceitar argumento obrigatório para o termo de busca (`-q, --query, --keyword`).
+- **FR-004**: O CLI DEVE suportar argumentos opcionais para código de idioma (`-l, --lang, --language`, padrão `pt`) e região/país (`--locale, --country`).
+- **FR-005**: O sistema DEVE aplicar mapeamento padrão de região quando apenas o idioma for informado (`pt` → BR, `es` → AR, `en` → US, `de` → DE, `fr` → FR, `it` → IT).
+- **FR-006**: O CLI DEVE permitir configurar a paginação lógica (`-p, --max-pages`, de 1 a 10 páginas / 10 a 100 itens).
+- **FR-007**: O sistema DEVE extrair: título, URL, data de publicação, subtítulo higienizado de HTML e número da página.
+- **FR-008**: O sistema DEVE resolver e decodificar automaticamente as URLs intermediárias do Google News para as URLs finais dos portais de notícias em paralelo.
+- **FR-009**: O CLI DEVE emitir logs informativos de progresso em `sys.stderr` e suportar a flag `-s, --silent` para supressão.
+- **FR-010**: O CLI DEVE suportar a flag `--no-resolve-urls` para obter as URLs brutas do feed RSS quando desejado.
+- **FR-011**: O CLI DEVE suportar gravação em arquivo via `-o, --output` com criação de diretórios pais e formatação legível com `--pretty`.
+
+---
+
+## Success Criteria *(mandatory)*
+
+- **SC-001**: Extração executada com sucesso utilizando Foxcape headless e alta taxa de entrega.
+- **SC-002**: 100% das URLs de notícias decodificadas para os portais reais dos veículos quando a resolução de URLs estiver ativa.
+- **SC-003**: 100% dos resumos/subtítulos livres de marcações HTML.
+- **SC-004**: Formato JSON no `stdout` 100% compatível com utilitários como `jq` e pipelines shell.
+- **SC-005**: 100% dos testes unitários e E2E aprovados no pytest.
@@ -0,0 +1,95 @@
+# Implementation Tasks: Google News Headlines Extractor
+
+**Feature**: Google News Headlines Extractor  
+**Branch**: `002-google-news-extractor` | **Date**: 2026-08-20  
+**Spec**: [spec.md](./spec.md) | **Plan**: [plan.md](./plan.md) | **Contracts**: [cli_contract.md](./contracts/cli_contract.md)
+
+---
+
+## Phase 1: Setup (Shared Infrastructure)
+
+**Purpose**: Instalar dependências necessárias e configurar fixtures de teste.
+
+- [X] T001 Adicionar `foxcape`, `beautifulsoup4`, `googlenewsdecoder` e `selectolax` ao requirements.txt e validar instalação
+- [X] T002 [P] Criar fixture XML de exemplo em tests/fixtures/google_news_sample.xml para testes offline
+
+---
+
+## Phase 2: Foundational (Blocking Prerequisites)
+
+**Purpose**: Estruturas de dados base e utilitários de localização que sustentam todas as histórias de usuário.
+
+- [X] T003 Definir as dataclasses `SearchQuery`, `NewsArticle` e `ExtractionResult` em scripts/extract_google_news.py
+- [X] T004 [P] Implementar utilitário de mapeamento de idioma e país `get_hl_gl_ceid` em scripts/extract_google_news.py
+
+---
+
+## Phase 3: User Story 1 - Extração Básica de Notícias por Assunto e Idioma (Priority: P1) 🌟 MVP
+
+**Goal**: Permitir a extração de notícias de um termo e idioma via CLI, retornando JSON formatado com títulos, links e datas de publicação.
+
+**Independent Test**: Executar `python scripts/extract_google_news.py --query "tecnologia" --lang pt` e verificar retorno de JSON válido no `stdout` contendo itens com título e URL.
+
+### Tests for User Story 1 🧪
+- [X] T005 [P] [US1] Criar testes unitários para parsing XML do RSS e limpeza de tags HTML em tests/test_extract_google_news.py
+
+### Implementation for User Story 1
+- [X] T006 [US1] Implementar função `parse_google_news_rss` com limpeza de tags HTML e deduplicação de subtítulos em scripts/extract_google_news.py
+- [X] T007 [US1] Implementar função `extract_google_news` utilizando a biblioteca `foxcape` em modo headless como motor primário em scripts/extract_google_news.py
+- [X] T008 [US1] Implementar interface CLI básica com `argparse` emitindo JSON para `stdout` em scripts/extract_google_news.py
+
+**Checkpoint**: User Story 1 (MVP) 100% funcional e testável de forma independente.
+
+---
+
+## Phase 4: User Story 2 - Filtragem Regional e Edição Geográfica (Priority: P2)
+
+**Goal**: Permitir direcionamento de notícias por região/país com a flag `--locale` (ex: `es` com `MX` vs `ES`).
+
+**Independent Test**: Executar `python scripts/extract_google_news.py --query "futebol" --lang es --locale MX` e verificar que a query foi montada com os parâmetros de edição regional correspondentes.
+
+### Tests for User Story 2 🧪
+- [X] T009 [P] [US2] Adicionar testes unitários para a flag `--locale` e resolução de `ceid` em tests/test_extract_google_news.py
+
+### Implementation for User Story 2
+- [X] T010 [US2] Integrar suporte à flag `--locale` / `--country` no CLI e fluxo de requisição em scripts/extract_google_news.py
+
+**Checkpoint**: User Stories 1 e 2 funcionais e testáveis de forma independente.
+
+---
+
+## Phase 5: User Story 3 - Paginação e Controle de Volume de Resultados (Priority: P3)
+
+**Goal**: Permitir configuração de quantidade de páginas/itens (`--max-pages` de 1 a 10) e salvamento em arquivo (`--output`).
+
+**Independent Test**: Executar com `--max-pages 2 --output out/test_news.json` e verificar arquivo gerado com até 20 itens divididos em páginas 1 e 2.
+
+### Tests for User Story 3 🧪
+- [X] T011 [P] [US3] Adicionar testes unitários para limite de páginas e exportação em arquivo em tests/test_extract_google_news.py
+
+### Implementation for User Story 3
+- [X] T012 [US3] Implementar fatiamento de páginas lógicas (`--max-pages 1..10`) e flag `--output` para gravação de arquivo com criação automática de diretórios pais em scripts/extract_google_news.py
+
+**Checkpoint**: Todas as histórias de usuário funcionais e integradas.
+
+---
+
+## Phase 6: URL Resolution, Headless Configuration & Real-Time Logging
+
+**Purpose**: Resolver URLs reais dos veículos, suprimir janelas visuais de navegador e emitir feedback de progresso no terminal.
+
+- [X] T013 Implementar `resolve_article_url` e `resolve_articles_urls` com `googlenewsdecoder` e pool concorrente em scripts/extract_google_news.py
+- [X] T014 Configurar `FoxcapeConfig(headless=True)` garantindo raspagem 100% em background sem interface gráfica em scripts/extract_google_news.py
+- [X] T015 Adicionar logging em tempo real em `sys.stderr` e flag `-s / --silent` para supressão em scripts/extract_google_news.py
+- [X] T016 Adicionar flag `--no-resolve-urls` para permitir acesso às URLs brutas do feed quando desejado em scripts/extract_google_news.py
+
+---
+
+## Phase 7: Verification & E2E Testing
+
+**Purpose**: Testes automatizados de ponta a ponta e auditoria de tipagem e estilo.
+
+- [X] T017 Criar testes unitários para o resolvedor de URLs em tests/test_extract_google_news.py
+- [X] T018 Criar testes E2E ao vivo (`test_e2e_resolve_real_google_news_url`, `test_e2e_extract_google_news_live_pipeline`, `test_e2e_cli_live_file_output`) em tests/test_extract_google_news.py
+- [X] T019 Validar 100% de conformidade com `ruff check`, `ruff format` e `mypy` estrito
+- [X] T020 Executar suite completa do repositório garantindo 0 regressões