feat(cli): standardize documented exit codes across command dispatch

[ajulaybeeb]

Summary

• Define standardized, stable process exit codes across all starforge CLI commands for scriptability and CI/CD automation
• Implement ExitCode enum (src/utils/exit_codes.rs) representing success (0), general failure (1), usage error (2), configuration error (3), network error (4), signing error (5), execution error (6), and environment error (7)
• Implement determine_exit_code(&anyhow::Error) error classifier that inspects error types, error messages, and cause chains
• Update main() dispatch to exit with determine_exit_code(&e).exit() instead of generic exit(1)
• Add unit and integration tests (tests/cli_exit_codes.rs) and update README.md and DEVELOPER_GUIDE.md with exit code documentation

Why

Issue #672 requires usage, configuration, network, signing, execution, and environment failures to be mapped to stable, documented exit codes. Previously, all command failures exited with generic status code 1 (except correlation ID validation which used 2). This prevented shell scripts and CI/CD pipelines from distinguishing between transient network glitches, invalid arguments, passphrase authentication failures, or missing local system dependencies.

Implementation

src/utils/exit_codes.rs (new)

• ExitCode (#[repr(i32)]):
  • 0 (Success): Command executed successfully
  • 1 (GeneralFailure): Unclassified runtime or execution failure
  • 2 (Usage): Invalid CLI arguments, syntax, or input parameter
  • 3 (Config): Configuration file missing, invalid, or schema migration failure
  • 4 (Network): Network connectivity, RPC node, or Horizon request failure
  • 5 (Signing): Cryptographic keypair, secret decryption passphrase mismatch, or signature failure
  • 6 (Execution): Contract WASM compilation, verification, or transaction revert
  • 7 (Environment): Missing system dependency (e.g. Docker, curl), permission denied, or unsupported host OS/arch
• determine_exit_code(): Classification engine that pattern-matches top-level error strings and full anyhow cause chains to return the matching ExitCode variant
• ExitCode::exit(): Helper invoking std::process::exit(self.code())

src/main.rs

• Updated command error dispatch block to classify errors via utils::exit_codes::determine_exit_code(&e) and exit with code.exit()
• Updated correlation ID error exit path to use ExitCode::Usage.exit()

tests/cli_exit_codes.rs (new, 10 tests)

• test_exit_code_numeric_values: Verifies numeric i32 code mappings (0 through 7)
• test_exit_code_names_and_descriptions: Verifies machine-readable names and descriptions
• test_classify_usage_errors: Tests classification for bad args, invalid keys, invalid correlation IDs
• test_classify_signing_errors: Tests classification for secret key errors and passphrase decryption failures
• test_classify_network_errors: Tests classification for Horizon, Friendbot, and RPC connection/timeout errors
• test_classify_config_errors: Tests classification for config.toml parse errors and unsupported networks
• test_classify_execution_errors: Tests classification for WASM errors, contract compilation, and simulation reverts
• test_classify_environment_errors: Tests classification for Docker, permission, and unsupported OS/arch errors
• test_classify_general_failure_fallback: Tests fallback to code 1 for unclassified runtime errors
• test_classify_chained_context_error: Tests classification over nested anyhow cause chains

Documentation

• README.md: Added CLI exit codes reference matrix detailing code values, names, descriptions, triggers, and shell script usage examples
• DEVELOPER_GUIDE.md: Added Standardized CLI Exit Codes architecture overview, error return guidelines for command handlers, and test commands

Testing

Ran automated integration suite:

cargo test --test cli_exit_codes
running 10 tests
test test_classify_environment_errors ... ok
test test_classify_execution_errors ... ok
test test_classify_config_errors ... ok
test test_classify_general_failure_fallback ... ok
test test_classify_network_errors ... ok
test test_classify_chained_context_error ... ok
test test_classify_signing_errors ... ok
test test_exit_code_names_and_descriptions ... ok
test test_exit_code_numeric_values ... ok
test test_classify_usage_errors ... ok
test result: ok. 10 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
Scope / Risk
Risk: Low — exiting with specific non-zero status codes improves scriptability; happy-path code (0) remains unaffected
Breaking change: Scripts expecting exit code 1 for all non-zero failures should be updated to check $rc -ne 0 (standard shell practice)
Affected area: src/main.rs, src/utils/exit_codes.rs, tests/cli_exit_codes.rs, README.md, DEVELOPER_GUIDE.md
Issue
Closes #672

[drips-wave]

@ajulaybeeb Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits