# CLI Contract: Article Content Multi-Engine Extractor

## 1. Comando de Execução

```bash
python scripts/extract_article_contents.py [OPTIONS]
```

---

## 2. Argumentos e Flags

| Flag Curta | Flag Longa | Tipo | Obrigatório | Padrão | Descrição |
|---|---|---|---|---|---|
| `-i` | `--input` | String (Path) | **Sim** | — | Caminho para o arquivo JSON de entrada (ex: `out/river_plate.json`). |
| `-o` | `--output` | String (Path) | Não | `<input_stem>_extracted.json` | Caminho do arquivo JSON de destino. Se omitido, salva no mesmo diretório com sufixo `_extracted.json`. |
| `-l` | `--limit` | Inteiro | Não | Todos | Limita a quantidade máxima de artigos a serem processados (útil para amostragem/testes). |
| `--lang` | `--language` | String | Não | Do JSON / `"en"` | Sobrescreve o código de idioma para o módulo de NLP do Newspaper4k (ex: `pt`, `es`, `en`). |
| `-t` | `--timeout` | Inteiro | Não | `30` | Timeout em segundos para o carregamento do DOM de cada página no Foxcape. |
| `-s` | `--silent` | Flag booleana | Não | `False` | Suprime mensagens visuais de progresso e logs em `stderr`. |
| `-h` | `--help` | Flag booleana | Não | `False` | Exibe manual de ajuda com todos os parâmetros disponíveis. |

---

## 3. Códigos de Saída (Exit Codes)

| Código | Significado | Condição |
|---|---|---|
| `0` | **Sucesso** | Execução concluída e arquivo JSON de saída gravado com êxito (mesmo que artigos individuais tenham falhado). |
| `1` | **Erro de Argumento** | Arquivo de entrada inexistente, formato inválido ou parâmetros numéricos fora dos limites. |
| `2` | **Erro de Inicialização** | Falha ao inicializar o motor Foxcape/navegador headless ou falta de dependências essenciais. |

---

## 4. Comportamento de Streams (I/O)

- **`stderr`**: Recebe mensagens de status informativas em tempo real:
  ```text
  [INFO] 🚀 Iniciando extração de 10 artigos a partir de 'out/river_plate.json'
  [INFO] 🌐 [1/10] Foxcape navegando: https://www.tycsports.com/...
  [INFO] ⚙️ [1/10] Extraindo dados (Trafilatura, Newspaper4k, Readability)...
  [INFO] ✅ [1/10] Sucesso (Título: "Los puntajes de River...")
  ...
  [INFO] 💾 Relatório final gravado com sucesso em: 'out/river_plate_extracted.json'
  [INFO] 📊 Resumo: 10 total | 10 sucessos | 0 falhas | Tempo: 14.2s
  ```
- **`stdout`**: Mantém-se silencioso se `--output` for fornecido (ou padrão), ou emite o JSON final caso o usuário redirecione a saída explicitamente.