TextNLPClassifierApp/specs/003-article-content-extractor/contracts/cli-contract.md

CLI Contract: Article Content Multi-Engine Extractor

1. Comando de Execução

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:

  [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.