lean_ctx/core/

paths.rs

// SPDX-License-Identifier: Apache-2.0

//! Typed XDG base-directory resolvers for lean-ctx (GH #408 / GL #602).
//!
//! Historically every lean-ctx file joined onto a single [`lean_ctx_data_dir`]
//! rooted at `$XDG_CONFIG_HOME/lean-ctx`, mixing `config.toml` with 30+ runtime
//! data files (sessions, vectors, graphs, events, logs, caches). That violates
//! the XDG Base Directory Spec and makes a read-only config sandbox impossible.
//!
//! This module introduces one typed resolver per XDG category so call-sites can
//! migrate to the correct base over the following phases (GL #603/#604/#606/#607).
//!
//! ## Backward compatibility (single-dir mode)
//!
//! Existing installs MUST NOT split silently. `single_dir_override` returns
//! `Some(dir)` when `LEAN_CTX_DATA_DIR` is set or a legacy/mixed install with
//! data exists; in that case every category resolves to that one directory —
//! byte-for-byte today's behavior. The real per-category split only applies to
//! fresh installs (and, later, on-demand via `lean-ctx doctor --fix`).
//!
//! ## `data_dir()` and the fresh-install flip
//!
//! [`data_dir`] delegates to [`lean_ctx_data_dir`]. Config (`config.toml` +
//! hooks) and the runtime STATE/CACHE files were migrated onto [`config_dir`],
//! [`state_dir`] and [`cache_dir`] (GL #603/#604) so that, since GL #606, the
//! data resolver defaults fresh installs to `$XDG_DATA_HOME/lean-ctx` without
//! scattering config or state into the data dir. Legacy and pre-split mixed
//! installs keep resolving every category to their existing single directory.
//!
//! Determinism (#498): every resolver is a pure function of environment + HOME;
//! no timestamps, counters or randomness.

use std::path::{Path, PathBuf};

use super::data_dir::{ensure_dir_permissions, has_data_files, lean_ctx_data_dir};

/// Reads a directory path from `name`, treating empty/whitespace as unset.
fn env_path(name: &str) -> Option<PathBuf> {
    std::env::var(name)
        .ok()
        .map(|v| v.trim().to_string())
        .filter(|v| !v.is_empty())
        .map(PathBuf::from)
}

/// The per-process directory overrides. Any of them makes this process run on
/// directories other than the install's default layout.
const DIR_OVERRIDES: [&str; 4] = [
    "LEAN_CTX_CONFIG_DIR",
    "LEAN_CTX_DATA_DIR",
    "LEAN_CTX_STATE_DIR",
    "LEAN_CTX_CACHE_DIR",
];

/// `true` when a directory override is set. Layout healing that moves files in
/// the *default* locations (`~/.lean-ctx`, the XDG config dir, the layout pin)
/// must then do nothing: the override applies to this process only, and the
/// default locations belong to the real install (GH #2007).
#[must_use]
pub(crate) fn dir_override_active() -> bool {
    DIR_OVERRIDES.iter().any(|name| env_path(name).is_some())
}

/// Resolves an XDG base directory (e.g. `~/.config`), honoring the `env_name`
/// override and falling back to `$HOME/<home_fallback>`. Returns the base only;
/// callers append `lean-ctx`.
pub(crate) fn xdg_base(env_name: &str, home_fallback: &str) -> Result<PathBuf, String> {
    if let Some(p) = env_path(env_name) {
        return Ok(p);
    }
    dirs::home_dir()
        .map(|h| h.join(home_fallback))
        .ok_or_else(|| "Cannot determine home directory".to_string())
}

/// Pure resolution order for a category: explicit override > single-dir
/// backward-compat > XDG split default (`<base>/lean-ctx`).
fn resolve(
    category_override: Option<PathBuf>,
    single: Option<PathBuf>,
    xdg_base_dir: &Path,
) -> PathBuf {
    category_override
        .or(single)
        .unwrap_or_else(|| xdg_base_dir.join("lean-ctx"))
}

/// Returns the single directory that ALL categories must collapse onto for
/// backward compatibility, or `None` for a fresh install that may split.
///
/// `Some` when an *explicit* `LEAN_CTX_DATA_DIR` points at a non-standard
/// location (a deliberate single-dir choice: a custom dir, or `~/.lean-ctx` via
/// env), or a legacy `~/.lean-ctx` / mixed `$XDG_CONFIG_HOME/lean-ctx` install
/// already holds data. An empty directory does NOT trigger single-dir mode
/// (matches [`lean_ctx_data_dir`] semantics).
///
/// A `LEAN_CTX_DATA_DIR` equal to the *standard* XDG data dir
/// (`$XDG_DATA_HOME/lean-ctx`) is a DATA pin only, NOT a single-dir directive:
/// editors used to bake that exact value into the MCP server's `env`, and
/// honoring it as single-dir collapsed config/state/cache onto the data dir for
/// the MCP process while the terminal CLI kept the XDG split — so the two read
/// different `config.toml` files (#594). Falling through keeps config in
/// `$XDG_CONFIG_HOME/lean-ctx` for both; data still resolves to the pin via
/// [`lean_ctx_data_dir`], which consumes the env var before reaching here.
pub(crate) fn single_dir_override() -> Option<PathBuf> {
    if let Some(p) = env_path("LEAN_CTX_DATA_DIR")
        && !is_standard_xdg_data_dir(&p)
    {
        return Some(p);
    }
    let home = dirs::home_dir()?;
    let xdg_config_base = xdg_base("XDG_CONFIG_HOME", ".config").ok()?;
    let xdg_data_base = xdg_base("XDG_DATA_HOME", ".local/share").ok();
    single_dir_override_fs(&home, &xdg_config_base, xdg_data_base.as_deref())
}

/// True when `p` is exactly the standard XDG data dir (`$XDG_DATA_HOME/lean-ctx`,
/// default `~/.local/share/lean-ctx`). Pure function of env + HOME (no filesystem
/// access) so category resolution stays deterministic (#498).
fn is_standard_xdg_data_dir(p: &Path) -> bool {
    xdg_base("XDG_DATA_HOME", ".local/share")
        .map(|base| base.join("lean-ctx"))
        .is_ok_and(|standard| standard.as_path() == p)
}

/// Whether an editor-baked `LEAN_CTX_DATA_DIR` value (`pin`) would make that
/// editor's MCP server resolve a *different* `config.toml` than the terminal
/// CLI. Only a **non-standard** pin collapses config/state/cache onto the data
/// dir (#594); a pin equal to the standard `$XDG_DATA_HOME/lean-ctx` is a
/// data-only pin and keeps config parity. Pure function of `pin` + the current
/// process' env/HOME (the terminal's view), so `doctor` can compare an editor's
/// baked pin against the CLI's own resolution without mutating env or spawning.
pub fn data_pin_diverges_config(pin: &Path) -> bool {
    !is_standard_xdg_data_dir(pin)
}

/// Filesystem half of [`single_dir_override`], parameterized for hermetic tests.
pub(crate) fn single_dir_override_fs(
    home: &Path,
    xdg_config_base: &Path,
    xdg_data_base: Option<&Path>,
) -> Option<PathBuf> {
    // A committed XDG install is the single source of truth: never re-collapse
    // it onto a stray legacy/mixed data marker (GL #623). The pin lives next to
    // the mixed probe below, so the two reads always agree on `xdg_config_base`.
    if crate::core::layout_pin::is_xdg_pinned_in(xdg_config_base) {
        return None;
    }
    let legacy = home.join(".lean-ctx");
    if legacy.exists() && has_data_files(&legacy) {
        return Some(legacy);
    }
    let mixed = xdg_config_base.join("lean-ctx");
    if mixed.exists() && has_data_files(&mixed) {
        // GL #623 follow-up: an already-split XDG install (real data under
        // `$XDG_DATA_HOME/lean-ctx`) must NOT re-collapse config/state/cache/data
        // onto the *config* dir just because a stray data marker leaked there
        // (e.g. during an upgrade, before the layout pin is written). That would
        // scatter stats/events/journal/sessions into `$XDG_CONFIG_HOME` and split
        // history across two trees.
        if let Some(data_base) = xdg_data_base
            && has_data_files(&data_base.join("lean-ctx"))
        {
            return None;
        }
        return Some(mixed);
    }
    None
}

/// Shared resolver for the config/state/cache categories.
fn category_dir(cat_env: &str, xdg_env: &str, home_fallback: &str) -> Result<PathBuf, String> {
    let dir = resolve_category_dir(cat_env, xdg_env, home_fallback)?;
    ensure_dir_permissions(&dir);
    Ok(dir)
}

/// The same category identity, without creating or changing the resolved directory.
// Under `#[cfg(test)]` the body always succeeds (returns the sandbox); the
// fallible XDG resolution only runs in real builds.
#[cfg_attr(test, allow(clippy::unnecessary_wraps))]
fn resolve_category_dir(
    cat_env: &str,
    xdg_env: &str,
    home_fallback: &str,
) -> Result<PathBuf, String> {
    let category_override = env_path(cat_env);

    // A category override always wins, even under #[cfg(test)] — this lets the
    // RO-config sandbox integration test point each category at a temp dir.
    if super::data_dir::sandboxed() {
        if let Some(p) = category_override {
            return Ok(p);
        }
        // Unit tests share one per-process sandbox so stray store writes can't
        // escape to a developer's real dirs. The branch logic itself is covered
        // by the pure `resolve` / `single_dir_override_fs` tests below.
        return Ok(super::data_dir::test_sandbox_dir());
    }
    let base = xdg_base(xdg_env, home_fallback)?;
    Ok(resolve(category_override, single_dir_override(), &base))
}

/// Config directory — `config.toml`, shell hooks, `env.sh`. RO-safe.
/// Override: `LEAN_CTX_CONFIG_DIR`; default `$XDG_CONFIG_HOME/lean-ctx`.
pub fn config_dir() -> Result<PathBuf, String> {
    category_dir("LEAN_CTX_CONFIG_DIR", "XDG_CONFIG_HOME", ".config")
}

/// Resolve CONFIG without creating directories or repairing permissions.
pub fn config_dir_read_only() -> Result<PathBuf, String> {
    resolve_category_dir("LEAN_CTX_CONFIG_DIR", "XDG_CONFIG_HOME", ".config")
}

/// Resolve a member (a file or sub-directory) of the config dir, adopting a copy
/// that older builds wrote under the OS-native `dirs::config_dir()` location.
///
/// Before #594 (A3), providers/personas/plugins/multi-repo config resolved via
/// `dirs::config_dir()` — on macOS `~/Library/Application Support`, a *different*
/// base than the `$XDG_CONFIG_HOME/lean-ctx` dir used for `config.toml`, so those
/// features silently diverged from the main config. Routing them through
/// [`config_dir`] unifies the base; this helper performs a one-time,
/// non-destructive adoption so a user who already had config at the old path
/// keeps it. The canonical location always wins — an existing canonical entry is
/// never overwritten — and the legacy entry is copied, never moved, so the
/// user's default config dir always keeps its own copy.
///
/// Adoption is skipped entirely in tests and whenever a `LEAN_CTX_*_DIR`
/// override is active: an override (a sandbox, a temp dir, a test harness) must
/// never pull files out of the real install's default config dir.
pub fn config_dir_member(sub: &str) -> Result<PathBuf, String> {
    let canonical = config_dir()?.join(sub);
    if legacy_adoption_allowed(super::data_dir::sandboxed(), dir_override_active())
        && let Some(legacy_base) = dirs::config_dir()
    {
        adopt_legacy_config_member(&legacy_base.join("lean-ctx").join(sub), &canonical);
    }
    Ok(canonical)
}

/// Legacy config adoption only runs for the real install: never in a test
/// sandbox and never while a directory override points this process elsewhere.
fn legacy_adoption_allowed(sandboxed: bool, override_active: bool) -> bool {
    !sandboxed && !override_active
}

/// Decide whether a legacy config member should be adopted: only when the
/// canonical entry is still absent, the legacy entry actually exists, and the two
/// paths genuinely differ (on Linux the two bases coincide, making this a no-op).
fn legacy_adoption_source(legacy: &Path, canonical: &Path) -> Option<PathBuf> {
    if canonical.exists() || legacy == canonical || !legacy.exists() {
        return None;
    }
    Some(legacy.to_path_buf())
}

/// Recursively copy `src` (file or directory) onto `dst`. The source is never
/// modified; nested directory symlinks are not followed. The caller guarantees
/// `dst`'s parent exists.
fn copy_tree(src: &Path, dst: &Path) -> std::io::Result<()> {
    if src.is_dir() {
        std::fs::create_dir_all(dst)?;
        for entry in std::fs::read_dir(src)? {
            let entry = entry?;
            let child = entry.path();
            if entry.file_type()?.is_dir() {
                copy_tree(&child, &dst.join(entry.file_name()))?;
            } else {
                std::fs::copy(&child, dst.join(entry.file_name()))?;
            }
        }
    } else {
        std::fs::copy(src, dst)?;
    }
    Ok(())
}

fn remove_entry(path: &Path) -> std::io::Result<()> {
    if path.is_dir() {
        std::fs::remove_dir_all(path)
    } else {
        std::fs::remove_file(path)
    }
}

/// Copy `src` onto `dst` without ever touching `src`. The copy is staged in a
/// sibling and renamed into place, so a failed or partial copy never leaves a
/// half-written canonical entry that would then win over the intact legacy one.
fn adopt_copy(src: &Path, dst: &Path) -> std::io::Result<()> {
    let name = dst
        .file_name()
        .map(|n| n.to_string_lossy().into_owned())
        .unwrap_or_default();
    let staging = dst.with_file_name(format!(".{name}.adopt-{}", std::process::id()));
    if staging.exists() {
        remove_entry(&staging)?;
    }
    let result = copy_tree(src, &staging).and_then(|()| std::fs::rename(&staging, dst));
    if result.is_err() && staging.exists() {
        let _ = remove_entry(&staging);
    }
    result
}

/// A free sibling name for a retired legacy entry: `<name>.adopted`, or
/// `<name>.adopted-<n>` when an earlier adoption already left one behind.
fn adopted_name(legacy: &Path) -> Option<PathBuf> {
    let name = legacy.file_name()?.to_string_lossy().into_owned();
    (1..=100)
        .map(|n| {
            let suffix = if n == 1 {
                ".adopted".to_string()
            } else {
                format!(".adopted-{n}")
            };
            legacy.with_file_name(format!("{name}{suffix}"))
        })
        .find(|candidate| !candidate.exists() && candidate.symlink_metadata().is_err())
}

/// One-time adoption of a legacy `dirs::config_dir()/lean-ctx/<sub>` member into
/// the canonical config dir. Best-effort and lossless: the legacy entry is
/// copied, and only after the copy is in place is the original retired to
/// `<name>.adopted` (kept, never deleted), so no live stale duplicate can win
/// over the adopted copy later (e.g. after a `doctor --fix` split). Any IO
/// failure leaves the legacy entry untouched.
fn adopt_legacy_config_member(legacy: &Path, canonical: &Path) {
    let Some(src) = legacy_adoption_source(legacy, canonical) else {
        return;
    };
    if let Some(parent) = canonical.parent()
        && std::fs::create_dir_all(parent).is_err()
    {
        return;
    }
    if adopt_copy(&src, canonical).is_err() {
        return;
    }
    if let Some(retired) = adopted_name(&src) {
        let _ = std::fs::rename(&src, retired);
    }
}

/// Data directory — sessions, vectors, graphs, knowledge, archives, memory.
///
/// Delegates to [`lean_ctx_data_dir`], which since GL #606 defaults fresh
/// installs to `$XDG_DATA_HOME/lean-ctx`. Legacy `~/.lean-ctx` and pre-split
/// mixed `$XDG_CONFIG_HOME/lean-ctx` installs (and an explicit
/// `LEAN_CTX_DATA_DIR`) continue to resolve in place for backward compatibility.
pub fn data_dir() -> Result<PathBuf, String> {
    lean_ctx_data_dir()
}

/// State directory — events, stats, logs, journals, ledgers, captured keys.
/// Override: `LEAN_CTX_STATE_DIR`; default `$XDG_STATE_HOME/lean-ctx`.
pub fn state_dir() -> Result<PathBuf, String> {
    category_dir("LEAN_CTX_STATE_DIR", "XDG_STATE_HOME", ".local/state")
}

/// Resolve STATE without creating directories or repairing permissions.
pub fn state_dir_read_only() -> Result<PathBuf, String> {
    resolve_category_dir("LEAN_CTX_STATE_DIR", "XDG_STATE_HOME", ".local/state")
}

/// Cache directory — semantic cache, models, learned patterns. tmpfs-safe.
/// Override: `LEAN_CTX_CACHE_DIR`; default `$XDG_CACHE_HOME/lean-ctx`.
pub fn cache_dir() -> Result<PathBuf, String> {
    category_dir("LEAN_CTX_CACHE_DIR", "XDG_CACHE_HOME", ".cache")
}

/// Resolve CACHE without creating directories or repairing permissions.
pub(crate) fn cache_dir_read_only() -> Result<PathBuf, String> {
    resolve_category_dir("LEAN_CTX_CACHE_DIR", "XDG_CACHE_HOME", ".cache")
}

/// Runtime directory — `daemon.pid`, `daemon.sock`. `$XDG_RUNTIME_DIR/lean-ctx`.
///
/// When `XDG_RUNTIME_DIR` is unset (common on macOS), falls back to
/// [`state_dir`] so runtime files stay in a private, writable, non-config path
/// rather than a world-readable temp location.
pub fn runtime_dir() -> Result<PathBuf, String> {
    if let Some(base) = env_path("XDG_RUNTIME_DIR") {
        return Ok(base.join("lean-ctx"));
    }
    state_dir()
}

/// Raw per-category target dir for the four XDG categories, **bypassing**
/// single-dir back-compat and the test sandbox. Honors an explicit
/// `LEAN_CTX_<CAT>_DIR` override, otherwise `<XDG base>/lean-ctx`.
///
/// `category_dir`/[`data_dir`] deliberately collapse onto one directory for a
/// legacy/mixed install; the `doctor --fix` migration (GH #408) needs to know
/// where each category SHOULD live *after* a split, which is what this returns.
fn raw_category_dir(cat_env: &str, xdg_env: &str, home_fallback: &str) -> Result<PathBuf, String> {
    if let Some(p) = env_path(cat_env) {
        return Ok(p);
    }
    Ok(xdg_base(xdg_env, home_fallback)?.join("lean-ctx"))
}

/// Split target for the config category (`$XDG_CONFIG_HOME/lean-ctx`).
pub(crate) fn config_split_target() -> Result<PathBuf, String> {
    raw_category_dir("LEAN_CTX_CONFIG_DIR", "XDG_CONFIG_HOME", ".config")
}

/// `$XDG_CONFIG_HOME/lean-ctx` (or `~/.config/lean-ctx`) — where `config.toml`
/// and the layout pin (`layout.toml`) live. Resolved through the XDG config base
/// only, bypassing single-dir collapse, so the pin that governs that collapse
/// never depends on it (GL #623). `None` only when HOME cannot be determined.
pub(crate) fn xdg_config_lean_ctx_dir() -> Option<PathBuf> {
    xdg_base("XDG_CONFIG_HOME", ".config")
        .ok()
        .map(|b| b.join("lean-ctx"))
}

/// Split target for the data category (`$XDG_DATA_HOME/lean-ctx`).
pub(crate) fn data_split_target() -> Result<PathBuf, String> {
    raw_category_dir("LEAN_CTX_DATA_DIR", "XDG_DATA_HOME", ".local/share")
}

/// Resolve DATA without creating directories or repairing permissions.
pub fn data_dir_read_only() -> Result<PathBuf, String> {
    raw_category_dir("LEAN_CTX_DATA_DIR", "XDG_DATA_HOME", ".local/share")
}

/// Split target for the state category (`$XDG_STATE_HOME/lean-ctx`).
pub(crate) fn state_split_target() -> Result<PathBuf, String> {
    raw_category_dir("LEAN_CTX_STATE_DIR", "XDG_STATE_HOME", ".local/state")
}

/// Split target for the cache category (`$XDG_CACHE_HOME/lean-ctx`).
pub(crate) fn cache_split_target() -> Result<PathBuf, String> {
    raw_category_dir("LEAN_CTX_CACHE_DIR", "XDG_CACHE_HOME", ".cache")
}

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

    #[test]
    fn resolve_prefers_override_then_single_then_xdg() {
        let over = PathBuf::from("/over/ride");
        let single = PathBuf::from("/single/dir");
        let base = PathBuf::from("/xdg/base");

        assert_eq!(
            resolve(Some(over.clone()), Some(single.clone()), &base),
            over
        );
        assert_eq!(resolve(None, Some(single.clone()), &base), single);
        assert_eq!(
            resolve(None, None, &base),
            PathBuf::from("/xdg/base/lean-ctx")
        );
    }

    #[test]
    fn single_dir_fs_detects_legacy_with_data() {
        let home = tempfile::tempdir().unwrap();
        let xdg = tempfile::tempdir().unwrap();
        let legacy = home.path().join(".lean-ctx");
        std::fs::create_dir_all(&legacy).unwrap();
        std::fs::write(legacy.join("stats.json"), "{}").unwrap();

        assert_eq!(
            single_dir_override_fs(home.path(), xdg.path(), None),
            Some(legacy)
        );
    }

    #[test]
    fn single_dir_fs_detects_mixed_with_data() {
        let home = tempfile::tempdir().unwrap();
        let xdg = tempfile::tempdir().unwrap();
        let mixed = xdg.path().join("lean-ctx");
        std::fs::create_dir_all(&mixed).unwrap();
        // A real data marker (stats.json) — NOT config.toml, which post-split
        // lives alone in the config dir and must not trigger single-dir mode.
        std::fs::write(mixed.join("stats.json"), "{}").unwrap();

        assert_eq!(
            single_dir_override_fs(home.path(), xdg.path(), None),
            Some(mixed)
        );
    }

    #[test]
    fn single_dir_fs_ignores_config_only_dir() {
        // GH #408: a clean post-split config dir (only config.toml + hooks) must
        // NOT collapse the four-dir layout.
        let home = tempfile::tempdir().unwrap();
        let xdg = tempfile::tempdir().unwrap();
        let mixed = xdg.path().join("lean-ctx");
        std::fs::create_dir_all(&mixed).unwrap();
        std::fs::write(mixed.join("config.toml"), "").unwrap();
        std::fs::write(mixed.join("shell-hook.zsh"), "").unwrap();

        assert_eq!(single_dir_override_fs(home.path(), xdg.path(), None), None);
    }

    #[test]
    fn single_dir_fs_prefers_legacy_over_mixed() {
        let home = tempfile::tempdir().unwrap();
        let xdg = tempfile::tempdir().unwrap();
        let legacy = home.path().join(".lean-ctx");
        std::fs::create_dir_all(&legacy).unwrap();
        std::fs::write(legacy.join("sessions"), "x").unwrap();
        let mixed = xdg.path().join("lean-ctx");
        std::fs::create_dir_all(&mixed).unwrap();
        std::fs::write(mixed.join("stats.json"), "{}").unwrap();

        assert_eq!(
            single_dir_override_fs(home.path(), xdg.path(), None),
            Some(legacy)
        );
    }

    #[test]
    fn xdg_pinned_install_ignores_stray_legacy_marker() {
        // GL #623: once committed to XDG (pin in the config dir), a stray
        // `~/.lean-ctx/stats.json` (legacy residue, restored backup, concurrent
        // old binary) must NOT re-collapse the layout onto the legacy dir.
        let home = tempfile::tempdir().unwrap();
        let xdg = tempfile::tempdir().unwrap();
        crate::core::layout_pin::write_xdg_pin_in(xdg.path()).unwrap();

        let legacy = home.path().join(".lean-ctx");
        std::fs::create_dir_all(&legacy).unwrap();
        std::fs::write(legacy.join("stats.json"), "{}").unwrap();

        assert_eq!(single_dir_override_fs(home.path(), xdg.path(), None), None);
    }

    #[test]
    fn xdg_pinned_install_ignores_stray_mixed_marker() {
        // GL #623: same protection for a stray data marker that lands in the
        // mixed `$XDG_CONFIG_HOME/lean-ctx` dir after the install committed.
        let home = tempfile::tempdir().unwrap();
        let xdg = tempfile::tempdir().unwrap();
        crate::core::layout_pin::write_xdg_pin_in(xdg.path()).unwrap();

        let mixed = xdg.path().join("lean-ctx");
        std::fs::write(mixed.join("stats.json"), "{}").unwrap();

        assert_eq!(single_dir_override_fs(home.path(), xdg.path(), None), None);
    }

    #[test]
    fn split_install_ignores_stray_mixed_marker_when_xdg_data_present() {
        // Regression: an XDG-split install with real data under
        // `$XDG_DATA_HOME/lean-ctx` must not re-collapse onto the config dir just
        // because a stray marker leaked into `$XDG_CONFIG_HOME/lean-ctx` before
        // the layout pin was written (the upgrade window). Without the guard this
        // scattered stats/events/journal/sessions into the config dir and split
        // history across two trees.
        let home = tempfile::tempdir().unwrap();
        let xdg_config = tempfile::tempdir().unwrap();
        let xdg_data = tempfile::tempdir().unwrap();

        let mixed = xdg_config.path().join("lean-ctx");
        std::fs::create_dir_all(&mixed).unwrap();
        std::fs::write(mixed.join("stats.json"), "{}").unwrap();

        let data = xdg_data.path().join("lean-ctx");
        std::fs::create_dir_all(&data).unwrap();
        std::fs::write(data.join("stats.json"), "{}").unwrap();

        assert_eq!(
            single_dir_override_fs(home.path(), xdg_config.path(), Some(xdg_data.path())),
            None,
            "a populated XDG data dir must keep the config dir from collapsing"
        );

        // With no real data dir the stray marker still collapses (legacy
        // single-dir semantics preserved).
        let empty_data = tempfile::tempdir().unwrap();
        assert_eq!(
            single_dir_override_fs(home.path(), xdg_config.path(), Some(empty_data.path())),
            Some(mixed)
        );
    }

    #[test]
    fn single_dir_fs_ignores_empty_dirs() {
        let home = tempfile::tempdir().unwrap();
        let xdg = tempfile::tempdir().unwrap();
        std::fs::create_dir_all(home.path().join(".lean-ctx")).unwrap();
        std::fs::create_dir_all(xdg.path().join("lean-ctx")).unwrap();

        assert_eq!(single_dir_override_fs(home.path(), xdg.path(), None), None);
    }

    #[test]
    fn single_dir_fs_ignores_non_marker_files() {
        let home = tempfile::tempdir().unwrap();
        let xdg = tempfile::tempdir().unwrap();
        let mixed = xdg.path().join("lean-ctx");
        std::fs::create_dir_all(&mixed).unwrap();
        std::fs::write(mixed.join("random.txt"), "x").unwrap();

        assert_eq!(single_dir_override_fs(home.path(), xdg.path(), None), None);
    }

    #[test]
    fn xdg_base_honors_env_then_home_fallback() {
        let _lock = crate::core::data_dir::test_env_lock();
        let tmp = tempfile::tempdir().unwrap();
        crate::test_env::set_var("XDG_CONFIG_HOME", tmp.path());
        let from_env = xdg_base("XDG_CONFIG_HOME", ".config").unwrap();
        crate::test_env::remove_var("XDG_CONFIG_HOME");
        assert_eq!(from_env, tmp.path());

        // Unset var → falls back to $HOME/<home_fallback>.
        let fallback = xdg_base("LEAN_CTX_NONEXISTENT_XDG_VAR", ".cache").unwrap();
        assert!(fallback.ends_with(".cache"), "got: {}", fallback.display());
    }

    #[test]
    fn legacy_adoption_source_only_when_canonical_absent() {
        let tmp = tempfile::tempdir().unwrap();
        let legacy = tmp.path().join("legacy");
        let canonical = tmp.path().join("canonical");

        // Legacy missing → nothing to adopt.
        assert_eq!(legacy_adoption_source(&legacy, &canonical), None);

        // Legacy present, canonical absent → adopt the legacy copy.
        std::fs::create_dir_all(&legacy).unwrap();
        assert_eq!(
            legacy_adoption_source(&legacy, &canonical),
            Some(legacy.clone())
        );

        // Canonical present → the newer location wins, never overwrite it.
        std::fs::create_dir_all(&canonical).unwrap();
        assert_eq!(legacy_adoption_source(&legacy, &canonical), None);
    }

    #[test]
    fn legacy_adoption_never_runs_under_an_override_or_sandbox() {
        assert!(legacy_adoption_allowed(false, false));
        assert!(!legacy_adoption_allowed(false, true), "dir override");
        assert!(!legacy_adoption_allowed(true, false), "test sandbox");
        assert!(!legacy_adoption_allowed(true, true));
    }

    #[test]
    fn adoption_copies_then_retires_the_original_as_adopted() {
        let tmp = tempfile::tempdir().unwrap();

        // File: adoption creates the canonical parent itself.
        let src_file = tmp.path().join("legacy/providers.toml");
        std::fs::create_dir_all(src_file.parent().unwrap()).unwrap();
        std::fs::write(&src_file, "id = \"x\"\n").unwrap();
        let dst_file = tmp.path().join("config/lean-ctx/providers.toml");
        adopt_legacy_config_member(&src_file, &dst_file);
        assert!(!src_file.exists(), "no live stale duplicate stays behind");
        assert_eq!(
            std::fs::read_to_string(tmp.path().join("legacy/providers.toml.adopted")).unwrap(),
            "id = \"x\"\n",
            "the original is kept as <name>.adopted"
        );
        assert_eq!(std::fs::read_to_string(&dst_file).unwrap(), "id = \"x\"\n");

        // Directory with nested content.
        let src_dir = tmp.path().join("legacy/personas");
        std::fs::create_dir_all(src_dir.join("nested")).unwrap();
        std::fs::write(src_dir.join("a.toml"), "a").unwrap();
        std::fs::write(src_dir.join("nested/b.toml"), "b").unwrap();
        let dst_dir = tmp.path().join("config/lean-ctx/personas");
        adopt_legacy_config_member(&src_dir, &dst_dir);
        let retired_dir = tmp.path().join("legacy/personas.adopted");
        assert!(!src_dir.exists());
        for (rel, body) in [("a.toml", "a"), ("nested/b.toml", "b")] {
            assert_eq!(
                std::fs::read_to_string(retired_dir.join(rel)).unwrap(),
                body
            );
            assert_eq!(std::fs::read_to_string(dst_dir.join(rel)).unwrap(), body);
        }

        // A second legacy copy never overwrites an earlier retired one.
        std::fs::remove_file(&dst_file).unwrap();
        std::fs::write(&src_file, "id = \"y\"\n").unwrap();
        adopt_legacy_config_member(&src_file, &dst_file);
        assert_eq!(std::fs::read_to_string(&dst_file).unwrap(), "id = \"y\"\n");
        assert_eq!(
            std::fs::read_to_string(tmp.path().join("legacy/providers.toml.adopted")).unwrap(),
            "id = \"x\"\n"
        );
        assert_eq!(
            std::fs::read_to_string(tmp.path().join("legacy/providers.toml.adopted-2")).unwrap(),
            "id = \"y\"\n"
        );
        std::fs::remove_file(&dst_file).unwrap();
        std::fs::write(&dst_file, "id = \"x\"\n").unwrap();

        // No staging leftovers next to the canonical entries.
        let names: Vec<String> = std::fs::read_dir(tmp.path().join("config/lean-ctx"))
            .unwrap()
            .map(|e| e.unwrap().file_name().to_string_lossy().into_owned())
            .collect();
        assert!(
            names.iter().all(|n| !n.contains(".adopt-")),
            "staging left behind: {names:?}"
        );

        // An existing canonical entry wins and is never overwritten.
        std::fs::write(&src_file, "id = \"changed\"\n").unwrap();
        adopt_legacy_config_member(&src_file, &dst_file);
        assert_eq!(std::fs::read_to_string(&dst_file).unwrap(), "id = \"x\"\n");
    }

    #[test]
    fn single_dir_override_honors_data_dir_env() {
        let _lock = crate::core::data_dir::test_env_lock();
        let tmp = tempfile::tempdir().unwrap();
        crate::test_env::set_var("LEAN_CTX_DATA_DIR", tmp.path());
        let got = single_dir_override();
        crate::test_env::remove_var("LEAN_CTX_DATA_DIR");
        // A custom (non-standard) data dir is a deliberate single-dir choice.
        assert_eq!(got, Some(tmp.path().to_path_buf()));
    }

    #[test]
    fn is_standard_xdg_data_dir_matches_xdg_data_home() {
        let _lock = crate::core::data_dir::test_env_lock();
        let data_home = tempfile::tempdir().unwrap();
        crate::test_env::set_var("XDG_DATA_HOME", data_home.path());
        let is_std = is_standard_xdg_data_dir(&data_home.path().join("lean-ctx"));
        let is_custom = is_standard_xdg_data_dir(Path::new("/some/custom/lean-ctx"));
        crate::test_env::remove_var("XDG_DATA_HOME");
        assert!(is_std, "$XDG_DATA_HOME/lean-ctx is the standard data dir");
        assert!(!is_custom, "a custom path is not the standard data dir");
    }

    #[test]
    fn standard_data_pin_does_not_collapse_categories() {
        // #594: an editor (MCP env) that pins LEAN_CTX_DATA_DIR to the *standard*
        // XDG data dir must NOT drag config/state/cache along — single_dir_override
        // must return None so they keep their own XDG bases, matching the CLI.
        let _lock = crate::core::data_dir::test_env_lock();
        let home = tempfile::tempdir().unwrap();
        let xdg_config = tempfile::tempdir().unwrap();
        let xdg_data = tempfile::tempdir().unwrap();
        let data_pin = xdg_data.path().join("lean-ctx");
        crate::test_env::set_var("HOME", home.path());
        crate::test_env::set_var("XDG_CONFIG_HOME", xdg_config.path());
        crate::test_env::set_var("XDG_DATA_HOME", xdg_data.path());
        crate::test_env::set_var("LEAN_CTX_DATA_DIR", &data_pin);

        let got = single_dir_override();

        crate::test_env::remove_var("LEAN_CTX_DATA_DIR");
        crate::test_env::remove_var("XDG_DATA_HOME");
        crate::test_env::remove_var("XDG_CONFIG_HOME");
        crate::test_env::remove_var("HOME");

        assert_eq!(got, None);
    }

    #[test]
    fn config_dir_honors_explicit_override() {
        let _lock = crate::core::data_dir::test_env_lock();
        let tmp = tempfile::tempdir().unwrap();
        crate::test_env::set_var("LEAN_CTX_CONFIG_DIR", tmp.path());
        let got = config_dir().unwrap();
        crate::test_env::remove_var("LEAN_CTX_CONFIG_DIR");
        assert_eq!(got, tmp.path());
    }

    #[test]
    fn state_and_cache_dirs_honor_explicit_overrides() {
        let _lock = crate::core::data_dir::test_env_lock();
        let state = tempfile::tempdir().unwrap();
        let cache = tempfile::tempdir().unwrap();
        crate::test_env::set_var("LEAN_CTX_STATE_DIR", state.path());
        crate::test_env::set_var("LEAN_CTX_CACHE_DIR", cache.path());
        let got_state = state_dir().unwrap();
        let got_cache = cache_dir().unwrap();
        crate::test_env::remove_var("LEAN_CTX_STATE_DIR");
        crate::test_env::remove_var("LEAN_CTX_CACHE_DIR");
        assert_eq!(got_state, state.path());
        assert_eq!(got_cache, cache.path());
    }

    #[test]
    fn data_dir_matches_lean_ctx_data_dir() {
        let _guard = crate::core::data_dir::isolated_data_dir();
        assert_eq!(
            data_dir().unwrap(),
            crate::core::data_dir::lean_ctx_data_dir().unwrap()
        );
    }

    #[test]
    fn runtime_dir_honors_xdg_runtime_dir() {
        let _lock = crate::core::data_dir::test_env_lock();
        let tmp = tempfile::tempdir().unwrap();
        crate::test_env::set_var("XDG_RUNTIME_DIR", tmp.path());
        let got = runtime_dir().unwrap();
        crate::test_env::remove_var("XDG_RUNTIME_DIR");
        assert_eq!(got, tmp.path().join("lean-ctx"));
    }
}