prometeu-runtime/docs/pull-requests/PR-006-cli-preserve-child-exit-status.md

PR-006: CLI Preserve Child Exit Status

Briefing

O wrapper prometeu despacha para outros binarios do ecossistema. Hoje, se o processo filho terminar sem exit code convencional, o CLI usa unwrap_or(0) e pode reportar sucesso mesmo quando houve abort, sinal ou encerramento anormal.

Este PR corrige a propagacao de status do processo filho para tornar o CLI confiavel em automacao, CI e uso por scripts.

Problema

• status.code() pode retornar None.
• unwrap_or(0) transforma falha anormal em sucesso.
• Isso mascara erros reais em run, debug, build e verify.

Escopo

• Preservar corretamente o resultado do processo filho.
• Melhorar a mensagem de erro quando nao houver codigo numerico.
• Cobrir o comportamento com testes.

Fora de Escopo

• Reestruturar todo o dispatcher.
• Implementar subcomandos ainda nao existentes.
• Alterar o protocolo entre CLI e bins filhos.

Abordagem

1. Remover unwrap_or(0) no ponto de saida.
2. Tratar dois casos:
   • filho retorna exit code numerico: repassar exatamente;
   • filho termina sem codigo numerico: encerrar com codigo nao-zero e mensagem clara.
3. Se necessario, extrair a traducao de ExitStatus para uma funcao pequena e testavel.

Algoritmo

Entrada: ExitStatus do processo filho.

Passos:

1. Chamar status.code().
2. Se retornar Some(code):
   • encerrar o wrapper com code.
3. Se retornar None:
   • escrever mensagem de erro indicando encerramento anormal;
   • encerrar o wrapper com 1.

Criterios de Aceite

• Se o processo filho sair com 0, o wrapper sai com 0.
• Se o processo filho sair com codigo nao-zero, o wrapper replica o mesmo codigo.
• Se o processo filho terminar sem codigo numerico, o wrapper sai com codigo nao-zero.
• O comportamento fica coberto por teste unitario.

Tests

• Extrair funcao pura ou quase pura para mapear ExitStatus -> i32 e testá-la.
• Cobrir:
  • 0;
  • 1;
  • outro codigo nao-zero;
  • status sem code numerico quando a plataforma permitir criar esse caso em teste.
• Se o caso None depender de plataforma:
  • encapsular sob cfg(unix) ou cfg(windows) conforme apropriado;
  • manter ao menos o contrato da funcao testado por unidade.
• Rodar:
  • cargo test -p prometeu-cli
  • cargo test --workspace

Risco

Muito baixo. A mudanca corrige semantica operacional do CLI e tende a melhorar observabilidade sem alterar a logica de dispatch.