soma_cli/

doctor.rs

//! doctor — pre-flight environment validation command.
//!
//! Pattern §48: Every server binary MUST implement a `doctor` subcommand that
//! validates the environment and reports what's missing before the user tries
//! to start the server.
//!
//! # Usage
//!
//! ```text
//! example doctor           # human-readable coloured output; exit 0/1
//! example doctor --json    # machine-readable JSON; exit 0/1
//! ```
//!
//! # CUSTOMIZE
//!
//! This is the reference implementation for the soma family. When you
//! clone Soma for a real service, the things you MUST change are:
//!
//! 1. Replace `SOMA_API_URL` / `SOMA_API_KEY` with your service's env vars.
//! 2. Replace `"soma"` binary name with your binary name in `check_binary_in_path`.
//! 3. Replace `~/.soma/` data dir with your service's data dir (see `config::default_data_dir`).
//! 4. Add any service-specific checks (e.g. database connectivity, auth token format).
//! 5. Update the `print_doctor_report` section headings and hint text to match your service.
//!
//! Nothing else here needs changing for a basic deployment. Business logic for the
//! checks belongs in the individual `check_*` functions — never in `run_doctor`.

mod checks;

use checks::{
    check_auth_config, check_binary_in_path, check_config_file, check_dir_writable,
    check_port_available, check_required_var, check_upstream,
};

use anyhow::{bail, Result};
use serde::Serialize;

use soma_config::{default_data_dir, Config};

// ── Public entry point ────────────────────────────────────────────────────────

/// Run the doctor command.
///
/// Executes all pre-flight checks in order and prints a summary. Exits with
/// code 1 if any check fails; 0 if all pass.
///
/// # CUSTOMIZE
/// This function is the canonical §48 implementation. Add calls to new
/// `check_*` functions below to extend the set of checks for your service.
pub async fn run_doctor(config: &Config, json: bool) -> Result<()> {
    let mut checks: Vec<DoctorCheck> = Vec::new();

    // ── 1. Config and filesystem ──────────────────────────────────────────────
    //
    // CUSTOMIZE: The data dir is resolved via `config::default_data_dir()`.
    //           In Docker it resolves to /data; bare-metal to ~/.soma/.
    //           Replace ".example" with your service name in config.rs.
    let data_dir = default_data_dir()?;

    checks.push(check_config_file(&data_dir));
    checks.push(check_dir_writable("Data directory", &data_dir));
    checks.push(check_dir_writable("Log directory", &data_dir.join("logs")));

    // ── 2. Binary in PATH ─────────────────────────────────────────────────────
    //
    // CUSTOMIZE: Replace "soma" with your binary name (Cargo.toml [[bin]] name).
    checks.push(check_binary_in_path("soma"));

    // ── 3. Required environment variables / config ────────────────────────────
    //
    // CUSTOMIZE: Replace these with your service's required vars. Mark vars that
    //           have safe defaults as optional (they will warn, not fail).
    //
    // Required vars fail with ✗.  Optional vars warn with ⚠.
    checks.push(check_required_var("SOMA_API_URL", &config.soma.api_url));
    checks.push(check_required_var("SOMA_API_KEY", &config.soma.api_key));

    // ── 4. Upstream connectivity ──────────────────────────────────────────────
    //
    // CUSTOMIZE: Adjust the health path for your upstream service.
    //           If the URL is empty we skip the check — the required-var check
    //           above already flagged it.
    if !config.soma.api_url.is_empty() {
        // CUSTOMIZE: Replace "/health" with your upstream's health or ping endpoint.
        //           If your upstream has no health endpoint, do a simple HEAD / request.
        checks.push(check_upstream(&config.soma.api_url).await);
    }

    // ── 5. MCP server port ────────────────────────────────────────────────────
    //
    // CUSTOMIZE: config.mcp.port defaults to 3000 for Soma.
    //           Your service's port is set in config.toml [mcp] port.
    checks.push(check_port_available(&config.mcp.host, config.mcp.port));

    // ── 6. Auth configuration ─────────────────────────────────────────────────
    //
    // CUSTOMIZE: The auth check inspects the combination of host / auth settings
    //           and reports which auth mode is active, or warns if 0.0.0.0 has
    //           no auth configured.
    checks.push(check_auth_config(config));

    // ── Render output ─────────────────────────────────────────────────────────

    let issues = checks.iter().filter(|c| !c.ok).count();

    let format = soma_cli_core::output::OutputFormat::from_json_flag(json);
    if format.is_json() {
        println!("{}", soma_cli_core::json::to_pretty_string(&checks)?);
    } else {
        print_doctor_report(&checks);
    }

    // Exit code 1 when any check fails.
    if issues > 0 {
        bail!("doctor found {issues} issue(s)");
    }
    Ok(())
}

// ── DoctorCheck struct ────────────────────────────────────────────────────────

/// A single pre-flight check result.
///
/// `ok = true`  → the check passed; `value` shows what was found.
/// `ok = false` → the check failed; `hint` explains how to fix it.
///
/// # CUSTOMIZE
/// Serialises directly to the `--json` output. Add fields here if you need
/// additional metadata (e.g. `severity: "warning" | "error"`, `doc_url`).
#[derive(Debug, Serialize)]
pub struct DoctorCheck {
    /// Logical category for grouping in human output and JSON filtering.
    ///
    /// CUSTOMIZE: Defined by each `check_*` function. Categories in Soma:
    ///   "config" | "credentials" | "connectivity" | "server" | "auth"
    pub category: &'static str,

    /// Short human-readable name for the check (shown in the left column).
    pub name: String,

    /// `true` = passed (✓), `false` = failed (✗).
    pub ok: bool,

    /// What was found — shown in the right column when ok=true.
    /// For failed checks, the hint is more useful.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub value: Option<String>,

    /// How to fix the problem — only present when `ok = false`.
    ///
    /// CUSTOMIZE: Make hints actionable — tell the user exactly what to type.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub hint: Option<String>,

    /// Round-trip latency in milliseconds — only for connectivity checks.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub latency_ms: Option<u64>,
}

impl DoctorCheck {
    fn pass(category: &'static str, name: impl Into<String>, value: impl Into<String>) -> Self {
        Self {
            category,
            name: name.into(),
            ok: true,
            value: Some(value.into()),
            hint: None,
            latency_ms: None,
        }
    }

    fn fail(category: &'static str, name: impl Into<String>, hint: impl Into<String>) -> Self {
        Self {
            category,
            name: name.into(),
            ok: false,
            value: None,
            hint: Some(hint.into()),
            latency_ms: None,
        }
    }

    fn pass_with_latency(
        category: &'static str,
        name: impl Into<String>,
        value: impl Into<String>,
        latency_ms: u64,
    ) -> Self {
        Self {
            category,
            name: name.into(),
            ok: true,
            value: Some(value.into()),
            hint: None,
            latency_ms: Some(latency_ms),
        }
    }

    fn fail_with_latency(
        category: &'static str,
        name: impl Into<String>,
        hint: impl Into<String>,
        latency_ms: u64,
    ) -> Self {
        Self {
            category,
            name: name.into(),
            ok: false,
            value: None,
            hint: Some(hint.into()),
            latency_ms: Some(latency_ms),
        }
    }
}

// ── Human-readable report ─────────────────────────────────────────────────────

/// Print the doctor report in human-readable coloured format.
///
/// Output follows the §48 layout:
///
/// ```text
/// soma-mcp v0.1.0 — environment check
///
///   Config
///   ────────────────────────────────────────────
///   ✓ Config file:  ~/.soma/config.toml
///   ✗ Data dir:     not writable
///     → Fix: chmod u+w ~/.soma
///   ...
/// ```
///
/// # CUSTOMIZE
/// Section headings and the version string are the main things to customise.
/// Add new sections if you add new check categories beyond the five defaults.
fn print_doctor_report(checks: &[DoctorCheck]) {
    let color = soma_cli_core::terminal::stderr_supports_color();

    // ── ANSI helpers ──────────────────────────────────────────────────────────
    // Delegates to soma-cli-core's color policy (crates/shared/cli-core);
    // wrapped in local macros so call sites below stay unchanged.
    macro_rules! green {
        ($s:expr) => {
            soma_cli_core::color::green(&$s.to_string(), color)
        };
    }
    macro_rules! red {
        ($s:expr) => {
            soma_cli_core::color::red(&$s.to_string(), color)
        };
    }
    macro_rules! yellow {
        ($s:expr) => {
            soma_cli_core::color::yellow(&$s.to_string(), color)
        };
    }
    macro_rules! bold {
        ($s:expr) => {
            soma_cli_core::color::bold(&$s.to_string(), color)
        };
    }
    macro_rules! dim {
        ($s:expr) => {
            soma_cli_core::color::dim(&$s.to_string(), color)
        };
    }

    // CUSTOMIZE: Replace "soma-mcp" with your service name and binary name.
    println!();
    println!(
        "{}",
        bold!(format!(
            "soma-mcp v{} — environment check",
            env!("CARGO_PKG_VERSION")
        ))
    );
    println!();

    // Group checks by category and print in order.
    // CUSTOMIZE: Reorder categories or add new ones to match your service.
    let categories: &[(&str, &str)] = &[
        ("config", "Config"),
        ("credentials", "Service credentials"),
        ("connectivity", "Connectivity"),
        ("server", "MCP server"),
        ("auth", "Authentication"),
    ];

    for (cat_key, cat_label) in categories {
        let cat_checks: Vec<&DoctorCheck> =
            checks.iter().filter(|c| c.category == *cat_key).collect();
        if cat_checks.is_empty() {
            continue;
        }

        println!("  {}", bold!(cat_label));
        println!("  {}", dim!("─".repeat(44)));

        for check in &cat_checks {
            if check.ok {
                let value = check.value.as_deref().unwrap_or("");
                let latency = check
                    .latency_ms
                    .map(|ms| format!(" ({ms} ms)"))
                    .unwrap_or_default();
                println!(
                    "  {}  {:<28}  {}{}",
                    green!("✓"),
                    check.name,
                    value,
                    latency
                );
            } else {
                println!("  {}  {}", red!("✗"), check.name);
                if let Some(hint) = &check.hint {
                    for line in hint.lines() {
                        println!("    {}", yellow!(line));
                    }
                }
            }
        }

        println!();
    }

    // ── Summary line ──────────────────────────────────────────────────────────
    let issues = checks.iter().filter(|c| !c.ok).count();
    println!("  {}", dim!("━".repeat(44)));

    if issues == 0 {
        println!(
            "  {}  All checks passed. Run: {}",
            green!("✓"),
            bold!("soma serve")
        );
    } else {
        // CUSTOMIZE: Replace "soma serve" with your server command.
        let noun = if issues == 1 { "issue" } else { "issues" };
        println!(
            "  {}  {} {noun} found. Fix before running: {}",
            red!("✗"),
            red!(issues.to_string()),
            bold!("soma serve")
        );
    }
    println!();
}

#[cfg(test)]
#[path = "doctor_tests.rs"]
mod tests;