trusty-memory 0.18.1

//! Handler for `trusty-memory doctor`.
//!
//! Why: GH #62 — when the launchd-managed daemon misbehaves (silent EROFS on
//! fastembed model download, stale plist without `FASTEMBED_CACHE_PATH`,
//! daemon not bound, etc.), operators currently have to grep through
//! `~/Library/LaunchAgents`, `~/.cache/fastembed`, and the lock file by hand
//! to figure out what's wrong. `doctor` runs the same checks in one shot and
//! prints a human-readable pass/fail report so the user can act immediately.
//! What: a one-shot CLI command that runs four checks:
//!   1. fastembed cache directory exists and is readable
//!   2. launchd plist exists at `~/Library/LaunchAgents/com.trusty.memory.plist`
//!      and contains the `FASTEMBED_CACHE_PATH` env var (macOS only)
//!   3. The HTTP daemon responds to `GET /health` on its configured port
//!   4. No obvious stale palace lock sidecar files (`*.lock`) under the data dir
//!
//! Each check prints a ✅ or ❌ line. The command exits 0 if all critical
//! checks pass, 1 otherwise.
//!
//! Test: `fastembed_cache_check_reports_missing_dir` and
//! `plist_check_detects_missing_env_var` cover the helpers; the full
//! orchestrator is exercised manually via
//! `cargo run -p trusty-memory -- doctor`.

mod audit;
mod checks;

use audit::audit_palaces;
pub use audit::{PalaceAuditEntry, PalaceAuditStatus};
#[cfg(target_os = "macos")]
use checks::check_launchd_plist;
use checks::{check_daemon_health, check_fastembed_cache, check_stale_palace_locks};

use anyhow::Result;
use colored::Colorize;

use crate::project_root::PERSONAL_PALACE;

/// Outcome of a single doctor check.
///
/// Why: keeps the orchestrator able to count failures without re-parsing
/// strings, while preserving the human-readable message for printing.
/// What: a tiny enum-with-message: `Pass` for green checks, `Warn` for
/// non-critical issues (don't flip exit code), `Fail` for actionable
/// failures (flip exit code to 1).
/// Test: not directly — exercised via the per-check unit tests.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(super) enum CheckStatus {
    Pass,
    Warn,
    Fail,
}

/// A single doctor check result.
///
/// Why: the orchestrator collects every result before printing so the
/// summary line ("N checks passed, M failed") is accurate.
/// What: bundles the status with a human-readable label and optional detail
/// (file path, error message, etc.).
/// Test: covered transitively by the helper tests.
#[derive(Debug, Clone)]
pub(super) struct CheckResult {
    pub(super) status: CheckStatus,
    label: String,
    detail: Option<String>,
}

impl CheckResult {
    pub(super) fn pass(label: impl Into<String>, detail: impl Into<String>) -> Self {
        Self {
            status: CheckStatus::Pass,
            label: label.into(),
            detail: Some(detail.into()),
        }
    }
    pub(super) fn warn(label: impl Into<String>, detail: impl Into<String>) -> Self {
        Self {
            status: CheckStatus::Warn,
            label: label.into(),
            detail: Some(detail.into()),
        }
    }
    pub(super) fn fail(label: impl Into<String>, detail: impl Into<String>) -> Self {
        Self {
            status: CheckStatus::Fail,
            label: label.into(),
            detail: Some(detail.into()),
        }
    }

    pub(super) fn print(&self) {
        let glyph = match self.status {
            CheckStatus::Pass => "✅".to_string(),
            CheckStatus::Warn => "⚠️ ".to_string(),
            CheckStatus::Fail => "❌".to_string(),
        };
        let label = match self.status {
            CheckStatus::Pass => self.label.green().to_string(),
            CheckStatus::Warn => self.label.yellow().to_string(),
            CheckStatus::Fail => self.label.red().to_string(),
        };
        match &self.detail {
            Some(d) => println!("{glyph} {label} — {}", d.dimmed()),
            None => println!("{glyph} {label}"),
        }
    }
}

/// Entry point for `trusty-memory doctor --fix-palaces [--fix]`.
///
/// Why: issue #88 — users with many accumulated palaces (e.g. 89 from
/// account-recovery) need a way to see which ones are orphaned without
/// destructive auto-cleanup. This command provides the read-only audit view
/// (default) and prints rename suggestions when `--fix` is also given.
/// Actual renaming is deliberately deferred to a future PR to avoid data
/// loss during this first conservative implementation.
/// What: resolves the palace registry directory (same logic as daemon startup),
/// calls `audit_palaces`, prints a table, and exits 0. The `--fix` flag
/// adds "rename suggested: X → personal" lines for every `Orphaned` entry
/// but does NOT mutate the filesystem.
/// Test: `doctor_fix_palaces_lists_orphaned_dry_run`.
pub async fn handle_doctor_fix_palaces(suggest_fix: bool) -> Result<()> {
    let data_dir = match trusty_common::resolve_data_dir("trusty-memory") {
        Ok(d) => d,
        Err(e) => {
            eprintln!("{} could not resolve data directory: {e:#}", "✗".red());
            return Ok(());
        }
    };
    let registry_dir = crate::resolve_palace_registry_dir(data_dir);

    println!(
        "{} Auditing palaces under {}\n",
        "·".dimmed(),
        registry_dir.display()
    );

    let entries = audit_palaces(&registry_dir);
    if entries.is_empty() {
        println!("{} No palace directories found.", "·".dimmed());
        return Ok(());
    }

    let mut ok_count = 0usize;
    let mut orphaned_count = 0usize;
    let mut empty_count = 0usize;

    for entry in &entries {
        match entry.status {
            PalaceAuditStatus::Ok => {
                ok_count += 1;
                println!(
                    "✅  {} — {}",
                    entry.id.green(),
                    "project palace ok".dimmed()
                );
            }
            PalaceAuditStatus::Orphaned => {
                orphaned_count += 1;
                println!(
                    "⚠️   {} — {}",
                    entry.id.yellow(),
                    "orphaned (no matching project directory found on disk)".dimmed()
                );
                if suggest_fix {
                    println!(
                        "   {} rename suggested: {} → {}",
                        "→".dimmed(),
                        entry.id.yellow(),
                        PERSONAL_PALACE.cyan()
                    );
                }
            }
            PalaceAuditStatus::Empty => {
                empty_count += 1;
                println!(
                    "❌  {} — {}",
                    entry.id.red(),
                    "empty (no palace.json; directory may be a leftover)".dimmed()
                );
            }
        }
    }

    println!();
    println!(
        "{} palace audit: {} ok, {} orphaned, {} empty.",
        "·".dimmed(),
        ok_count,
        orphaned_count,
        empty_count
    );

    if orphaned_count > 0 && !suggest_fix {
        println!(
            "{} Run with {} to see rename suggestions (no filesystem changes made).",
            "·".dimmed(),
            "--fix-palaces --fix".cyan()
        );
    }
    if suggest_fix && orphaned_count > 0 {
        println!(
            "{} Rename suggestions printed above (dry-run — no filesystem changes made).",
            "·".dimmed()
        );
    }

    Ok(())
}

/// Entry point for `trusty-memory doctor`.
///
/// Why: a single command for operators to triage daemon health without
/// having to remember four separate diagnostic incantations.
/// What: runs each check, prints the ✅/❌ line, and exits 0 (all pass) or
/// 1 (any `Fail`). `Warn` results print but do not flip the exit code.
/// Test: orchestrator is process-level; per-check helpers are unit-tested.
pub async fn handle_doctor() -> Result<()> {
    println!("{} Running trusty-memory diagnostics…\n", "·".dimmed());

    let mut results: Vec<CheckResult> = Vec::new();

    // Check 1: fastembed cache.
    results.push(check_fastembed_cache());

    // Check 2: launchd plist (macOS only).
    #[cfg(target_os = "macos")]
    {
        results.push(check_launchd_plist());
    }
    #[cfg(not(target_os = "macos"))]
    {
        results.push(CheckResult::warn(
            "launchd plist".to_string(),
            "skipped (not macOS)".to_string(),
        ));
    }

    // Check 3: HTTP daemon health.
    results.push(check_daemon_health().await);

    // Check 4: stale palace locks.
    results.push(check_stale_palace_locks());

    for r in &results {
        r.print();
    }

    let failed = results
        .iter()
        .filter(|r| r.status == CheckStatus::Fail)
        .count();
    let passed = results
        .iter()
        .filter(|r| r.status == CheckStatus::Pass)
        .count();
    let warned = results
        .iter()
        .filter(|r| r.status == CheckStatus::Warn)
        .count();

    println!();
    if failed == 0 {
        println!(
            "{} {} passed, {} warnings, {} failed.",
            "✓".green(),
            passed,
            warned,
            failed
        );
        Ok(())
    } else {
        eprintln!(
            "{} {} passed, {} warnings, {} failed.",
            "✗".red(),
            passed,
            warned,
            failed
        );
        std::process::exit(1);
    }
}

#[cfg(test)]
mod tests {
    use super::audit::scan_project_dirs_for_pin;
    #[cfg(target_os = "macos")]
    use super::checks::plist_contains_fastembed_cache_path;
    use super::checks::{fastembed_cache_has_models, find_lock_files};
    use super::*;

    /// Why: when the cache directory genuinely doesn't exist, doctor must
    /// flag it as a `Fail` so the user knows to run `setup` — silently
    /// passing here is the whole bug GH #62 protects against.
    /// What: builds a path under a tempdir that we deliberately do not
    /// create, calls the helper with a fake `FASTEMBED_CACHE_PATH`, and
    /// asserts the result is `Fail`.
    /// Test: pure, no network.
    #[test]
    fn fastembed_cache_check_reports_missing_dir() {
        let tmp = tempfile::tempdir().expect("tempdir");
        let missing = tmp.path().join("does_not_exist");
        // SAFETY: serial test — no other thread is reading the env var.
        // We don't set FASTEMBED_CACHE_DIR (which would take precedence)
        // and instead exercise FASTEMBED_CACHE_PATH so the resolver
        // returns our specific missing path.
        unsafe {
            std::env::remove_var("FASTEMBED_CACHE_DIR");
            std::env::set_var("FASTEMBED_CACHE_PATH", &missing);
        }
        let result = check_fastembed_cache();
        unsafe {
            std::env::remove_var("FASTEMBED_CACHE_PATH");
        }
        assert_eq!(result.status, CheckStatus::Fail, "got: {:?}", result);
    }

    /// Why: detecting model files (vs an empty cache) is what distinguishes
    /// "pre-warmed" from "first request will pay the download cost". The
    /// helper has to differentiate the two.
    /// What: creates an empty dir, asserts `Ok(false)`; writes a file,
    /// asserts `Ok(true)`.
    /// Test: pure filesystem.
    #[test]
    fn fastembed_cache_has_models_detects_entries() {
        let tmp = tempfile::tempdir().expect("tempdir");
        assert!(!fastembed_cache_has_models(tmp.path()).unwrap());
        std::fs::write(tmp.path().join("model.onnx"), b"x").unwrap();
        assert!(fastembed_cache_has_models(tmp.path()).unwrap());
    }

    /// Why: the plist check is the most operationally important diagnostic
    /// — it's the difference between "the daemon will work" and "the
    /// daemon will EROFS on first embed". Both branches must be covered.
    /// What: writes a plist *without* the key and asserts `Ok(false)`;
    /// writes a plist *with* the key and asserts `Ok(true)`.
    /// Test: pure filesystem.
    #[cfg(target_os = "macos")]
    #[test]
    fn plist_check_detects_missing_env_var() {
        let tmp = tempfile::tempdir().expect("tempdir");
        let no_key = tmp.path().join("no_key.plist");
        std::fs::write(&no_key, "<plist><dict></dict></plist>").unwrap();
        assert!(
            !plist_contains_fastembed_cache_path(&no_key).unwrap(),
            "plist without env var must report false"
        );

        let with_key = tmp.path().join("with_key.plist");
        std::fs::write(
            &with_key,
            "<plist><dict><key>FASTEMBED_CACHE_PATH</key><string>/x</string></dict></plist>",
        )
        .unwrap();
        assert!(
            plist_contains_fastembed_cache_path(&with_key).unwrap(),
            "plist with env var must report true"
        );
    }

    /// Why: `audit_palaces` is the core of the `--fix-palaces` audit; it must
    /// correctly classify palaces as `Ok`, `Orphaned`, and `Empty` so the
    /// presenter can display actionable information.
    /// What: build a mock registry under a tempdir with three palace
    /// directories: one matching the `personal` sentinel (Ok), one with a
    /// `palace.json` and no matching project directory (Orphaned), and one
    /// with no `palace.json` at all (Empty). Assert the audit returns three
    /// entries with the correct statuses.
    /// Test: pure filesystem.
    #[test]
    fn find_orphaned_palaces_lists_non_matching_and_empty() {
        let tmp = tempfile::tempdir().expect("tempdir");
        let registry = tmp.path();

        // `personal` → always Ok.
        let personal = registry.join("personal");
        std::fs::create_dir_all(&personal).unwrap();
        std::fs::write(personal.join("palace.json"), b"{}").unwrap();

        // `orphaned-proj` → has palace.json but no matching project on disk.
        let orphaned = registry.join("orphaned-proj-xyzzy");
        std::fs::create_dir_all(&orphaned).unwrap();
        std::fs::write(orphaned.join("palace.json"), b"{}").unwrap();

        // `empty-palace` → no palace.json.
        let empty = registry.join("empty-palace");
        std::fs::create_dir_all(&empty).unwrap();

        let entries = audit_palaces(registry);

        let personal_entry = entries.iter().find(|e| e.id == "personal");
        assert!(personal_entry.is_some(), "personal must appear in audit");
        assert_eq!(
            personal_entry.unwrap().status,
            PalaceAuditStatus::Ok,
            "personal must be Ok"
        );

        let orphaned_entry = entries.iter().find(|e| e.id == "orphaned-proj-xyzzy");
        assert!(orphaned_entry.is_some(), "orphaned entry must appear");
        assert_eq!(
            orphaned_entry.unwrap().status,
            PalaceAuditStatus::Orphaned,
            "orphaned-proj-xyzzy must be Orphaned"
        );

        let empty_entry = entries.iter().find(|e| e.id == "empty-palace");
        assert!(empty_entry.is_some(), "empty entry must appear");
        assert_eq!(
            empty_entry.unwrap().status,
            PalaceAuditStatus::Empty,
            "empty-palace must be Empty"
        );
    }

    /// Why: Change 3 — a palace whose name is claimed by a pin file in a
    /// scanned project directory must be classified `Ok`, not `Orphaned`, even
    /// when the directory name no longer matches the palace id (e.g. after a
    /// drive reorg / rename).
    /// What: create a mock registry with a palace named `my-old-name`; create
    /// a fake "Projects" search dir with a project that has a pin file claiming
    /// `palace: my-old-name`; pass that search dir to `scan_project_dirs_for_pin`
    /// and assert it returns `true`. Also assert that `audit_palaces` with the
    /// scanned search dirs classifies the palace as `Ok`.
    /// Test: pure filesystem.
    #[test]
    fn audit_palaces_ok_when_pin_file_claims_it() {
        use crate::project_root::{write_project_pin, ProjectPin, PIN_SCHEMA_VERSION};
        let tmp = tempfile::tempdir().expect("tempdir");

        // Set up a fake "Projects" directory with a project that has a pin.
        let projects_dir = tmp.path().join("Projects");
        let project_dir = projects_dir.join("moved-project");
        std::fs::create_dir_all(&project_dir).unwrap();
        let pin = ProjectPin {
            schema_version: PIN_SCHEMA_VERSION,
            palace: "my-old-name".to_string(),
            note: None,
        };
        write_project_pin(&project_dir, &pin).expect("write pin");

        // scan_project_dirs_for_pin must return true for the pinned id.
        assert!(
            scan_project_dirs_for_pin(std::slice::from_ref(&projects_dir), "my-old-name"),
            "scan must find the pin file that claims my-old-name"
        );
        // Must return false for an unrelated id.
        assert!(
            !scan_project_dirs_for_pin(std::slice::from_ref(&projects_dir), "some-other-palace"),
            "scan must not match a palace id not claimed by any pin"
        );
    }

    /// Why: `scan_project_dirs_for_pin` must not falsely claim a match when
    /// the pin file's `palace` field differs from the audit id.
    /// What: create a project with a pin for `alpha`; assert scan for `beta`
    /// returns false.
    /// Test: pure filesystem.
    #[test]
    fn scan_project_dirs_returns_false_for_mismatch() {
        use crate::project_root::{write_project_pin, ProjectPin, PIN_SCHEMA_VERSION};
        let tmp = tempfile::tempdir().expect("tempdir");
        let projects_dir = tmp.path().join("Projects");
        let project_dir = projects_dir.join("some-project");
        std::fs::create_dir_all(&project_dir).unwrap();
        let pin = ProjectPin {
            schema_version: PIN_SCHEMA_VERSION,
            palace: "alpha".to_string(),
            note: None,
        };
        write_project_pin(&project_dir, &pin).expect("write pin");
        assert!(
            !scan_project_dirs_for_pin(&[projects_dir], "beta"),
            "mismatch must return false"
        );
    }

    /// Why: stale `.lock` files are the canonical "palace won't open"
    /// symptom; the scanner must report them so `doctor` can hint at the
    /// remediation.
    /// What: lays out a tiny `palace/kg.redb.lock` tree under a tempdir
    /// and asserts the scanner picks it up.
    /// Test: pure filesystem.
    #[test]
    fn find_lock_files_returns_paths() {
        let tmp = tempfile::tempdir().expect("tempdir");
        let palace = tmp.path().join("palace_a");
        std::fs::create_dir_all(&palace).unwrap();
        let lock = palace.join("kg.redb.lock");
        std::fs::write(&lock, b"").unwrap();
        // Also drop a non-lock file to ensure it is ignored.
        std::fs::write(palace.join("kg.redb"), b"").unwrap();

        let found = find_lock_files(tmp.path());
        assert!(
            found.iter().any(|p| p == &lock),
            "expected to find {} in {:?}",
            lock.display(),
            found
        );
        assert_eq!(
            found.len(),
            1,
            "non-lock files must be ignored: {:?}",
            found
        );
    }

    // -----------------------------------------------------------------------
    // Tests for check_daemon_health addr-fallback robustness (#475)
    // -----------------------------------------------------------------------

    /// Why: issue #475 — `check_daemon_health` must not report "daemon not
    /// running" when the `http_addr` file is stale (contains an ephemeral or
    /// dead port) while the daemon IS live on the default port 7070. This test
    /// verifies the fallback path by writing a stale addr file pointing at a
    /// dead port (far outside the 7070-7079 fallback range) and asserting
    /// that the result is either:
    ///   - `Fail` (stale addr + no listener found on 7070-7079): expected when
    ///     no live daemon is running on those ports.
    ///   - `Pass` (fallback found live daemon on 7070): valid if the live daemon
    ///     happens to be on a fallback port during testing.
    ///
    /// The test also asserts that on `Fail` the detail message is informative
    /// (contains "unreachable" or "no daemon"). The real end-to-end fallback
    /// (stale addr → fallback succeeds → Pass) is validated by the throwaway
    /// daemon run documented in the session notes.
    /// Test: itself.
    #[tokio::test]
    async fn check_daemon_health_fails_cleanly_with_stale_addr_and_no_listener() {
        // Serialise on the process-wide env-var lock so concurrent tests
        // that also mutate TRUSTY_DATA_DIR_OVERRIDE do not interleave.
        let _guard = super::super::env_test_lock().lock().await;

        // TRUSTY_DATA_DIR_OVERRIDE sets the BASE dir; resolve_data_dir then
        // appends "trusty-memory" to form the actual data dir. We create the
        // full "trusty-memory" subdirectory so the http_addr file lands in the
        // right place.
        let tmp = tempfile::tempdir().expect("tempdir");
        let data_dir = tmp.path().join("trusty-memory");
        std::fs::create_dir_all(&data_dir).expect("create data dir");
        // Write a stale addr file pointing at a dead port (far outside 7070-7079).
        std::fs::write(data_dir.join("http_addr"), "127.0.0.1:19876\n").expect("write stale addr");

        unsafe {
            std::env::set_var("TRUSTY_DATA_DIR_OVERRIDE", tmp.path());
        }

        let result = check_daemon_health().await;

        unsafe {
            std::env::remove_var("TRUSTY_DATA_DIR_OVERRIDE");
        }
        drop(_guard);

        // With a stale addr AND no daemon on 7070-7079 (except possibly the
        // live daemon under test), result must be Fail or Pass.
        assert!(
            result.status == CheckStatus::Fail || result.status == CheckStatus::Pass,
            "unexpected status {:?}; expected Fail (stale addr, no listener) \
             or Pass (fallback found live daemon)",
            result.status,
        );
        if result.status == CheckStatus::Fail {
            let detail = result.detail.as_deref().unwrap_or("");
            assert!(
                detail.contains("unreachable") || detail.contains("no daemon"),
                "Fail detail must mention unreachable/no daemon: {detail:?}"
            );
        }
    }

    /// Why: issue #475 — when the addr file is completely absent AND no daemon
    /// is on 7070-7079, `check_daemon_health` must return `Fail` with a
    /// message that does not panic or suggest an incorrect start command.
    /// What: uses TRUSTY_DATA_DIR_OVERRIDE pointing at a fresh temp base dir
    /// (no http_addr file) and asserts the result is Fail or Pass.
    /// Test: itself.
    #[tokio::test]
    async fn check_daemon_health_fails_when_no_addr_file_and_no_listener() {
        // Serialise on the process-wide env-var lock.
        let _guard = super::super::env_test_lock().lock().await;

        let tmp = tempfile::tempdir().expect("tempdir");
        // Create the trusty-memory subdirectory but leave it empty (no http_addr).
        let data_dir = tmp.path().join("trusty-memory");
        std::fs::create_dir_all(&data_dir).expect("create data dir");

        unsafe {
            std::env::set_var("TRUSTY_DATA_DIR_OVERRIDE", tmp.path());
        }

        let result = check_daemon_health().await;

        unsafe {
            std::env::remove_var("TRUSTY_DATA_DIR_OVERRIDE");
        }
        drop(_guard);

        // Either Fail (no daemon found anywhere) or Pass (live daemon on 7070).
        assert!(
            result.status == CheckStatus::Fail || result.status == CheckStatus::Pass,
            "unexpected status: {:?}",
            result.status
        );
        if result.status == CheckStatus::Fail {
            let detail = result.detail.as_deref().unwrap_or("");
            assert!(
                detail.contains("no daemon") || detail.contains("no addr"),
                "detail must hint at the absence: {detail:?}"
            );
        }
    }
}