Add --health flag for self-diagnostics and monitoring

[rz1989s]

Summary

Add a --health flag to statusline.sh for automated health checks and self-diagnostics.

Background

From production readiness audit (2025-12-13): No health check endpoint exists for automated monitoring or verification.

Requirements

• Add --health flag to statusline.sh
• Check all required dependencies (jq, curl, bash version)
• Verify all modules load successfully
• Validate configuration file exists and is parseable
• Check cache directory permissions
• Return exit code 0 for healthy, non-zero for issues
• Output JSON format for machine parsing

Example Output

$ ./statusline.sh --health
{
  "status": "healthy",
  "version": "2.11.5",
  "modules_loaded": 11,
  "modules_failed": 0,
  "dependencies": {
    "jq": "1.7",
    "curl": "8.4.0",
    "bash": "5.2.21"
  },
  "config": "valid",
  "cache": "writable"
}

Use Cases

• Automated monitoring systems
• Installation verification
• Troubleshooting diagnostics
• CI/CD health checks

Priority

🟡 Medium Priority

References

• Production Readiness Report: docs/production-readiness-report.md

[rz1989s]

✅ Issue Resolved - --health Flag Added

Implementation Complete

Commit: 8d40fa7 on dev branch
CI Status: All checks passing ✅

Features Added

Flag	Format	Purpose
--health	Human-readable	Terminal diagnostic output
--health=json	JSON	Machine-parseable for scripts/monitoring
--health-json	JSON	Alternative flag name

Health Checks Performed

Critical Dependencies:

• bash version (4.0+ required)
• jq (JSON parsing)
• curl (API calls)

System Status:

• Modules loaded/failed count
• Config.toml presence and validity
• Cache directory writability

Optional Dependencies:

• ccusage (cost tracking)
• git (repository features)

Output Examples

Human-readable:

Claude Code Statusline Health Check
====================================

Status: healthy
Version: 2.11.6

Dependencies:
  ✓ bash 5.3.3
  ✓ jq 1.8.1
  ✓ curl 8.7.1
  ✓ git 2.51.0

Optional:
  ✓ ccusage: available

Modules: 10 loaded, 0 failed
Config: valid
Cache: writable

JSON:

{
  "status": "healthy",
  "version": "2.11.6",
  "modules_loaded": 10,
  "modules_failed": 0,
  "dependencies": {
    "bash": "5.3.3",
    "jq": "1.8.1",
    "curl": "8.7.1",
    "git": "2.51.0"
  },
  "optional": {
    "ccusage": "available"
  },
  "config": "valid",
  "cache": "writable"
}

Exit Codes

• 0 - Healthy (all critical deps present)
• 1 - Unhealthy (missing critical dependency)

Use Cases

# Terminal check
./statusline.sh --health

# CI/CD integration
./statusline.sh --health=json | jq -e '.status == "healthy"'

# Docker health check
docker compose run run --health

Tests

20 new tests added in tests/unit/test_health_flag.bats

Closing as complete.