ralph-agent-loop 0.4.0

A Rust CLI for managing AI agent loops with a structured JSON task queue
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

//! Output formatting for doctor reports.
//!
//! Responsibilities:
//! - Print doctor reports in human-readable text format.
//! - Format check results with appropriate severity indicators.
//! - Display fix status, suggestions, and canonical blocking-state diagnosis.
//!
//! Not handled here:
//! - JSON serialization (handled by serde in types).
//! - Report generation logic.
//!
//! Invariants/assumptions:
//! - Uses outpututil for consistent formatting.
//! - Respects the report's success state for final messaging.
//! - Blocking-state narration reuses the canonical contracts vocabulary.

use crate::commands::doctor::types::{CheckSeverity, DoctorReport};
use crate::contracts::{BlockingReason, BlockingState, BlockingStatus};
use crate::outpututil;

/// Print doctor report in human-readable text format.
pub fn print_doctor_report_text(report: &DoctorReport) {
    for check in &report.checks {
        match check.severity {
            CheckSeverity::Success => {
                outpututil::log_success(&check.message);
            }
            CheckSeverity::Warning => {
                outpututil::log_warn(&check.message);
            }
            CheckSeverity::Error => {
                outpututil::log_error(&check.message);
            }
        }

        if let Some(fix_applied) = check.fix_applied {
            if fix_applied {
                outpututil::log_success(&format!("  [FIXED] {}", check.message));
            } else {
                outpututil::log_error("  [FIX FAILED] Unable to apply fix");
            }
        } else if check.fix_available
            && !report.success
            && let Some(ref suggestion) = check.suggested_fix
        {
            log::info!("  Suggested fix: {}", suggestion);
        }
    }

    if let Some(blocking) = &report.blocking {
        render_blocking_state(blocking);
    }

    if report.summary.fixes_applied > 0 {
        log::info!("Applied {} auto-fix(es)", report.summary.fixes_applied);
    }
    if report.summary.fixes_failed > 0 {
        log::warn!("Failed to apply {} fix(es)", report.summary.fixes_failed);
    }

    match (&report.blocking, report.success) {
        (None, true) => {
            log::info!("Doctor check passed. System is ready.");
        }
        (Some(blocking), true) => {
            let summary = match blocking.status {
                BlockingStatus::Waiting => {
                    "Doctor check passed. Ralph is healthy, but it is currently waiting."
                }
                BlockingStatus::Blocked => {
                    "Doctor check passed. Ralph is healthy, but current work is blocked."
                }
                BlockingStatus::Stalled => {
                    "Doctor check passed, but Ralph is stalled and needs operator attention."
                }
            };
            match blocking.status {
                BlockingStatus::Waiting => log::info!("{}", summary),
                BlockingStatus::Blocked => log::warn!("{}", summary),
                BlockingStatus::Stalled => outpututil::log_error(summary),
            }
        }
        (_, false) => {
            outpututil::log_error(&format!("Doctor found {} issue(s):", report.summary.errors));
        }
    }
}

fn render_blocking_state(blocking: &BlockingState) {
    let header = match blocking.status {
        BlockingStatus::Waiting => "Blocking state: waiting",
        BlockingStatus::Blocked => "Blocking state: blocked",
        BlockingStatus::Stalled => "Blocking state: stalled",
    };

    match blocking.status {
        BlockingStatus::Waiting => outpututil::log_warn(header),
        BlockingStatus::Blocked | BlockingStatus::Stalled => outpututil::log_error(header),
    }

    log::info!("  Reason: {}", blocking_reason_name(&blocking.reason));
    log::info!("  {}", blocking.message);
    if !blocking.detail.trim().is_empty() {
        log::info!("  {}", blocking.detail);
    }
    if let Some(task_id) = &blocking.task_id {
        log::info!("  Task: {}", task_id);
    }
}

fn blocking_reason_name(reason: &BlockingReason) -> &'static str {
    match reason {
        BlockingReason::Idle { .. } => "idle",
        BlockingReason::DependencyBlocked { .. } => "dependency_blocked",
        BlockingReason::ScheduleBlocked { .. } => "schedule_blocked",
        BlockingReason::LockBlocked { .. } => "lock_blocked",
        BlockingReason::CiBlocked { .. } => "ci_blocked",
        BlockingReason::RunnerRecovery { .. } => "runner_recovery",
        BlockingReason::OperatorRecovery { .. } => "operator_recovery",
        BlockingReason::MixedQueue { .. } => "mixed_queue",
    }
}