# 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).
  ```