mars_agents/cli/

output.rs

//! Shared output formatting for CLI commands.
//!
//! Supports two modes: human-readable tables and JSON.
//! Respects `NO_COLOR` env var for colored output.

use std::io::Write;

use serde::Serialize;
use termcolor::{Color, ColorChoice, ColorSpec, StandardStream, WriteColor};

use crate::diagnostic::Diagnostic;
use crate::sync::SyncReport;
use crate::sync::apply::{ActionOutcome, ActionTaken};
use crate::types::managed_cmd;

/// Check if colored output should be used.
///
/// Respects `NO_COLOR` env var (https://no-color.org/).
pub fn use_color() -> bool {
    std::env::var_os("NO_COLOR").is_none()
}

fn color_choice() -> ColorChoice {
    if use_color() {
        ColorChoice::Auto
    } else {
        ColorChoice::Never
    }
}

/// Entry in the list command output.
#[derive(Debug, Serialize)]
pub struct ListEntry {
    pub source: String,
    pub item: String,
    pub kind: String,
    pub version: String,
    pub status: String,
}

/// Catalog entry — name + description for discovery.
#[derive(Debug, Serialize)]
pub struct CatalogEntry {
    pub name: String,
    pub description: String,
    pub kind: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub variants: Option<String>,
}

/// Print catalog view (name: description, grouped by kind).
pub fn print_catalog(
    agents: &[CatalogEntry],
    skills: &[CatalogEntry],
    bootstrap: &[CatalogEntry],
    kind_filter: Option<&str>,
) {
    let show_agents =
        kind_filter.is_none() || kind_filter == Some("agents") || kind_filter == Some("agent");
    let show_skills =
        kind_filter.is_none() || kind_filter == Some("skills") || kind_filter == Some("skill");
    let show_bootstrap = kind_filter.is_none()
        || kind_filter == Some("bootstrap")
        || kind_filter == Some("bootstrap-doc");

    if show_agents && !agents.is_empty() {
        println!("AGENTS");
        for entry in agents {
            let variant_suffix = entry
                .variants
                .as_ref()
                .map(|variants| format!(" [variants: {variants}]"))
                .unwrap_or_default();
            if entry.description.is_empty() {
                println!("- {}{}", entry.name, variant_suffix);
            } else {
                println!("- {}{}: {}", entry.name, variant_suffix, entry.description);
            }
        }
    }

    if show_agents && !agents.is_empty() && show_skills && !skills.is_empty() {
        println!();
    }

    if show_skills && !skills.is_empty() {
        println!("SKILLS");
        for entry in skills {
            let variant_suffix = entry
                .variants
                .as_ref()
                .map(|variants| format!(" [variants: {variants}]"))
                .unwrap_or_default();
            if entry.description.is_empty() {
                println!("- {}{}", entry.name, variant_suffix);
            } else {
                println!("- {}{}: {}", entry.name, variant_suffix, entry.description);
            }
        }
    }

    if ((show_agents && !agents.is_empty()) || (show_skills && !skills.is_empty()))
        && show_bootstrap
        && !bootstrap.is_empty()
    {
        println!();
    }

    if show_bootstrap && !bootstrap.is_empty() {
        println!("BOOTSTRAP");
        for entry in bootstrap {
            if entry.description.is_empty() {
                println!("- {}", entry.name);
            } else {
                println!("- {}: {}", entry.name, entry.description);
            }
        }
    }

    if (show_agents
        && agents.is_empty()
        && show_skills
        && skills.is_empty()
        && show_bootstrap
        && bootstrap.is_empty())
        || (show_agents && !show_skills && agents.is_empty())
        || (show_skills && !show_agents && !show_bootstrap && skills.is_empty())
        || (show_bootstrap && !show_agents && !show_skills && bootstrap.is_empty())
    {
        println!("  no managed items");
    }
}

/// Print sync report as human-readable text or JSON.
pub fn print_sync_report(report: &SyncReport, json: bool, no_upgrade_hint: bool) {
    if json {
        print_sync_report_json(report);
    } else {
        print_sync_report_human(report, no_upgrade_hint);
    }
}

/// Whether this report is from a dry run (`--diff`).
/// Returns true when the report was produced without writing any files.
fn is_dry_run(report: &SyncReport) -> bool {
    report.dry_run
}

fn print_sync_report_json(report: &SyncReport) {
    println!("{}", sync_report_json(report));
}

pub fn sync_report_json(report: &SyncReport) -> serde_json::Value {
    #[derive(Serialize)]
    struct JsonTargetOutcome {
        name: String,
        synced: usize,
        removed: usize,
        errors: Vec<String>,
    }

    #[derive(Serialize)]
    struct JsonReport {
        ok: bool,
        dry_run: bool,
        installed: usize,
        updated: usize,
        removed: usize,
        kept: usize,
        skipped: usize,
        native_emitted: usize,
        native_removed: usize,
        upgrades_available: usize,
        targets: Vec<JsonTargetOutcome>,
        diagnostics: Vec<Diagnostic>,
        engine_fallbacks: Vec<crate::resolve::EngineFallback>,
        #[serde(skip_serializing_if = "Option::is_none")]
        recovery_halt: Option<crate::sync::RecoveryHalt>,
    }

    let mut installed = 0;
    let mut updated = 0;
    let mut removed = 0;
    let mut kept = 0;
    let mut skipped = 0;

    for outcome in &report.applied.outcomes {
        match outcome.action {
            ActionTaken::Installed => installed += 1,
            ActionTaken::Updated => updated += 1,
            ActionTaken::Removed => removed += 1,
            ActionTaken::Kept => kept += 1,
            ActionTaken::Skipped => skipped += 1,
        }
    }

    let targets = report
        .target_outcomes
        .iter()
        .map(|outcome| JsonTargetOutcome {
            name: outcome.target.clone(),
            synced: outcome.items_synced,
            removed: outcome.items_removed,
            errors: outcome.errors.clone(),
        })
        .collect();

    serde_json::to_value(JsonReport {
        ok: report.recovery_halt.is_none(),
        dry_run: report.dry_run,
        installed,
        updated,
        removed,
        kept,
        skipped,
        native_emitted: report.native_emitted.len(),
        native_removed: report.native_removed.len(),
        upgrades_available: report.upgrades_available,
        targets,
        diagnostics: report.diagnostics.clone(),
        engine_fallbacks: report.engine_fallbacks.clone(),
        recovery_halt: report.recovery_halt.clone(),
    })
    .unwrap_or_else(|_| serde_json::json!({}))
}

fn print_sync_report_human(report: &SyncReport, no_upgrade_hint: bool) {
    if let Some(halt) = &report.recovery_halt {
        let mut stderr = StandardStream::stderr(color_choice());
        let _ = stderr.set_color(ColorSpec::new().set_fg(Some(Color::Yellow)));
        let _ = writeln!(stderr, "  recovery halted before materialization");
        let _ = stderr.reset();
        for persisted in &halt.persisted {
            let _ = writeln!(stderr, "  {persisted}");
        }
        for blocker in &halt.blockers {
            let _ = writeln!(
                stderr,
                "  blocked by {}@{} (hooks: {})",
                blocker.package,
                blocker.version,
                blocker.hook_names.join(", ")
            );
            let _ = writeln!(stderr, "  {}", blocker.guidance);
            let _ = writeln!(stderr, "  suggested: `{}`", blocker.suggested_command);
        }
        let _ = writeln!(stderr, "  {}", halt.next_step);
        for diagnostic in &report.diagnostics {
            let _ = writeln!(stderr, "  {diagnostic}");
        }
        return;
    }

    let mut stdout = StandardStream::stdout(color_choice());

    let mut installed = 0usize;
    let mut updated = 0usize;
    let mut removed = 0usize;
    let mut kept = 0usize;

    // Print per-item actions
    for outcome in &report.applied.outcomes {
        match outcome.action {
            ActionTaken::Installed => {
                installed += 1;
                print_action_line(&mut stdout, "+", Color::Green, outcome);
            }
            ActionTaken::Updated => {
                updated += 1;
                print_action_line(&mut stdout, "~", Color::Yellow, outcome);
            }
            ActionTaken::Removed => {
                removed += 1;
                print_action_line(&mut stdout, "-", Color::Red, outcome);
            }
            ActionTaken::Kept => {
                kept += 1;
            }
            ActionTaken::Skipped => {}
        }
    }

    let native_emitted = report.native_emitted.len();
    let native_removed = report.native_removed.len();
    for (target_root, dest_path) in &report.native_removed {
        print_native_line(&mut stdout, "-", Color::Red, target_root, dest_path);
    }
    for (target_root, dest_path) in &report.native_emitted {
        print_native_line(&mut stdout, "+", Color::Green, target_root, dest_path);
    }

    // Summary line — use "would ..." wording for dry runs
    let _ = writeln!(stdout);
    let dry = is_dry_run(report);
    if installed > 0 {
        if dry {
            let _ = writeln!(stdout, "  would install {installed} new items");
        } else {
            let _ = writeln!(stdout, "  installed   {installed} new items");
        }
    }
    if updated > 0 {
        if dry {
            let _ = writeln!(stdout, "  would update  {updated} items");
        } else {
            let _ = writeln!(stdout, "  updated     {updated} items");
        }
    }
    if removed > 0 {
        if dry {
            let _ = writeln!(stdout, "  would remove  {removed} orphans");
        } else {
            let _ = writeln!(stdout, "  removed     {removed} orphans");
        }
    }
    if native_emitted > 0 {
        if dry {
            let _ = writeln!(stdout, "  would emit   {native_emitted} native agents");
        } else {
            let _ = writeln!(stdout, "  emitted     {native_emitted} native agents");
        }
    }
    if native_removed > 0 {
        if dry {
            let _ = writeln!(stdout, "  would remove {native_removed} native agents");
        } else {
            let _ = writeln!(stdout, "  removed     {native_removed} native agents");
        }
    }
    if kept > 0 {
        let _ = writeln!(stdout, "  kept        {kept} locally modified");
    }

    if installed == 0
        && updated == 0
        && removed == 0
        && kept == 0
        && native_emitted == 0
        && native_removed == 0
    {
        let _ = stdout.set_color(ColorSpec::new().set_fg(Some(Color::Green)));
        let _ = writeln!(stdout, "  already up to date");
        let _ = stdout.reset();
    }

    // Print diagnostics to stderr so machine-readable stdout remains stable.
    let mut stderr = StandardStream::stderr(color_choice());
    for diag in &report.diagnostics {
        let color = match diag.level {
            crate::diagnostic::DiagnosticLevel::Error => Color::Red,
            crate::diagnostic::DiagnosticLevel::Warning => Color::Yellow,
            crate::diagnostic::DiagnosticLevel::Info => Color::Cyan,
        };
        let _ = stderr.set_color(ColorSpec::new().set_fg(Some(color)));
        let _ = writeln!(stderr, "  {diag}");
        let _ = stderr.reset();
    }

    if report.upgrades_available > 0 && !report.dry_run && !no_upgrade_hint {
        let noun = if report.upgrades_available == 1 {
            "upgrade"
        } else {
            "upgrades"
        };
        let _ = stderr.set_color(ColorSpec::new().set_fg(Some(Color::Cyan)));
        let _ = writeln!(
            stderr,
            "  ℹ {} {noun} available — run `{cmd}` to update",
            report.upgrades_available,
            cmd = managed_cmd("mars upgrade"),
        );
        let _ = stderr.reset();
    }
}

fn print_action_line(
    stdout: &mut StandardStream,
    prefix: &str,
    color: Color,
    outcome: &ActionOutcome,
) {
    let _ = stdout.set_color(ColorSpec::new().set_fg(Some(color)));
    let _ = write!(stdout, "  {prefix} ");
    let _ = stdout.reset();
    let _ = writeln!(stdout, "{} ({})", outcome.dest_path, outcome.item_id.kind);
}

fn print_native_line(
    stdout: &mut StandardStream,
    prefix: &str,
    color: Color,
    target_root: &str,
    dest_path: &str,
) {
    let _ = stdout.set_color(ColorSpec::new().set_fg(Some(color)));
    let _ = write!(stdout, "  {prefix} ");
    let _ = stdout.reset();
    let _ = writeln!(stdout, "{target_root}/{dest_path} (native agent)");
}

/// Print a list of items as a table or JSON.
pub fn print_list(entries: &[ListEntry], json: bool) {
    if json {
        println!("{}", serde_json::to_string(entries).unwrap_or_default());
    } else {
        print_list_human(entries);
    }
}

fn print_list_human(entries: &[ListEntry]) {
    if entries.is_empty() {
        println!("  no managed items");
        return;
    }

    // Compute column widths
    let source_w = entries
        .iter()
        .map(|e| e.source.len())
        .max()
        .unwrap_or(6)
        .max(6);
    let item_w = entries
        .iter()
        .map(|e| e.item.len())
        .max()
        .unwrap_or(4)
        .max(4);
    let version_w = entries
        .iter()
        .map(|e| e.version.len())
        .max()
        .unwrap_or(7)
        .max(7);

    // Header
    println!(
        "{:<source_w$}  {:<item_w$}  {:<version_w$}  STATUS",
        "SOURCE", "ITEM", "VERSION"
    );

    let mut stdout = StandardStream::stdout(color_choice());
    for entry in entries {
        let _ = write!(
            stdout,
            "{:<source_w$}  {:<item_w$}  {:<version_w$}  ",
            entry.source, entry.item, entry.version
        );
        let color = match entry.status.as_str() {
            "ok" => Color::Green,
            "modified" => Color::Yellow,
            "conflicted" => Color::Red,
            _ => Color::White,
        };
        let _ = stdout.set_color(ColorSpec::new().set_fg(Some(color)));
        let _ = writeln!(stdout, "{}", entry.status);
        let _ = stdout.reset();
    }
}

/// Print doctor report.
pub fn print_doctor(errors: &[String], warnings: &[String], json: bool) {
    if json {
        #[derive(Serialize)]
        struct DoctorReport {
            ok: bool,
            errors: Vec<String>,
            warnings: Vec<String>,
        }
        let report = DoctorReport {
            ok: errors.is_empty(),
            errors: errors.to_vec(),
            warnings: warnings.to_vec(),
        };
        println!("{}", serde_json::to_string(&report).unwrap_or_default());
    } else {
        let mut stdout = StandardStream::stdout(color_choice());
        if errors.is_empty() && warnings.is_empty() {
            let _ = stdout.set_color(ColorSpec::new().set_fg(Some(Color::Green)));
            let _ = writeln!(stdout, "  all checks passed");
            let _ = stdout.reset();
        } else {
            for warning in warnings {
                let _ = stdout.set_color(ColorSpec::new().set_fg(Some(Color::Yellow)));
                let _ = write!(stdout, "  ⚠ ");
                let _ = stdout.reset();
                let _ = writeln!(stdout, "{warning}");
            }

            for error in errors {
                let _ = stdout.set_color(ColorSpec::new().set_fg(Some(Color::Red)));
                let _ = write!(stdout, "  ✗ ");
                let _ = stdout.reset();
                let _ = writeln!(stdout, "{error}");
            }
            let _ = writeln!(stdout);
            if !warnings.is_empty() {
                let _ = writeln!(stdout, "  {} warning(s)", warnings.len());
            }
            if !errors.is_empty() {
                let _ = writeln!(stdout, "  {} error(s)", errors.len());
            }
        }
    }
}

/// Print simple JSON value.
pub fn print_json<T: Serialize>(value: &T) {
    println!("{}", serde_json::to_string(value).unwrap_or_default());
}

/// Print a simple success message.
pub fn print_success(msg: &str) {
    let mut stdout = StandardStream::stdout(color_choice());
    let _ = stdout.set_color(ColorSpec::new().set_fg(Some(Color::Green)));
    let _ = write!(stdout, "  ✓ ");
    let _ = stdout.reset();
    let _ = writeln!(stdout, "{msg}");
}

/// Print pipeline diagnostics to stderr (same format as sync report output).
pub fn print_diagnostics(diagnostics: &[Diagnostic]) {
    let mut stderr = StandardStream::stderr(color_choice());
    for diag in diagnostics {
        let color = match diag.level {
            crate::diagnostic::DiagnosticLevel::Error => Color::Red,
            crate::diagnostic::DiagnosticLevel::Warning => Color::Yellow,
            crate::diagnostic::DiagnosticLevel::Info => Color::Cyan,
        };
        let _ = stderr.set_color(ColorSpec::new().set_fg(Some(color)));
        let _ = writeln!(stderr, "  {diag}");
        let _ = stderr.reset();
    }
}

/// Print a warning message (yellow).
pub fn print_warn(msg: &str) {
    let mut stdout = StandardStream::stdout(color_choice());
    let _ = stdout.set_color(ColorSpec::new().set_fg(Some(Color::Yellow)));
    let _ = write!(stdout, "  ⚠ ");
    let _ = stdout.reset();
    let _ = writeln!(stdout, "{msg}");
}

/// Print an error message (red).
pub fn print_error(msg: &str) {
    let mut stdout = StandardStream::stdout(color_choice());
    let _ = stdout.set_color(ColorSpec::new().set_fg(Some(Color::Red)));
    let _ = write!(stdout, "  ✗ ");
    let _ = stdout.reset();
    let _ = writeln!(stdout, "{msg}");
}

/// Print an info message.
pub fn print_info(msg: &str) {
    println!("  {msg}");
}

#[cfg(test)]
mod tests {
    use super::*;

    fn report(engine_fallbacks: Vec<crate::resolve::EngineFallback>) -> SyncReport {
        SyncReport {
            applied: crate::sync::apply::ApplyResult {
                outcomes: Vec::new(),
            },
            diagnostics: Vec::new(),
            dependency_changes: Vec::new(),
            upgrades_available: 0,
            target_outcomes: Vec::new(),
            dry_run: false,
            native_emitted: Vec::new(),
            native_removed: Vec::new(),
            recovery_halt: None,
            engine_fallbacks,
        }
    }

    #[test]
    fn sync_json_reports_engine_fallback_details() {
        let fallback = crate::resolve::EngineFallback {
            source: "base".into(),
            skipped: vec![crate::resolve::EngineFallbackSkippedVersion {
                version: "2.0.0".into(),
                requirements: vec![crate::resolve::EngineFallbackRequirement {
                    engine: "mars".into(),
                    requirement: ">=0.12".into(),
                }],
            }],
            selected_version: "1.5.0".into(),
            engines: vec!["mars".into()],
        };

        assert_eq!(
            sync_report_json(&report(vec![fallback]))["engine_fallbacks"],
            serde_json::json!([{
                "source": "base",
                "skipped": [{
                    "version": "2.0.0",
                    "requirements": [{"engine": "mars", "requirement": ">=0.12"}]
                }],
                "selected_version": "1.5.0",
                "engines": ["mars"]
            }])
        );
    }

    #[test]
    fn sync_json_has_empty_engine_fallbacks_without_fallback() {
        assert_eq!(
            sync_report_json(&report(Vec::new()))["engine_fallbacks"],
            serde_json::json!([])
        );
    }
}