mind-cli 0.48.0

//! Advisory file-lock for all persisted mind state.
//!
//! A single lock file at `<mind root>/.lock` serializes mutations and protects
//! concurrent readers from observing partial writes. The lock is advisory:
//! it constrains only mind processes that call this module.
//!
//! # Usage
//!
//! In `run`, right after `Paths::resolve`:
//!
//! ```ignore
//! let mut lock = lock::open(&paths)?;
//! let _guard = lock.write()?;    // exclusive, or lock.read()? for shared
//! // ... rest of command ...
//! // _guard dropped here, lock released
//! ```

use std::fs::{File, OpenOptions};

use fd_lock::RwLock;

use crate::error::{MindError, Result};
use crate::paths::{Paths, mkdir_p};

/// An opened lock file, ready to be locked shared or exclusively.
///
/// Keep this value alive for the duration you want the lock held; acquire a
/// guard via [`MindLock::write`] or [`MindLock::read`] and drop the guard to
/// release the OS lock.
pub struct MindLock {
    /// One lock file per mind home, the default home first (HOME-9).
    files: Vec<OneLock>,
}

struct OneLock {
    inner: RwLock<File>,
    /// Remembered so error messages carry the path.
    path: std::path::PathBuf,
}

/// RAII exclusive guard. Holds the OS write locks until dropped.
pub struct WriteGuard<'a> {
    _guards: Vec<fd_lock::RwLockWriteGuard<'a, File>>,
}

/// RAII shared guard. Holds the OS read locks until dropped.
pub struct ReadGuard<'a> {
    _guards: Vec<fd_lock::RwLockReadGuard<'a, File>>,
}

/// Open (creating if necessary) the lock file of every mind home.
///
/// This does not acquire the lock yet; call [`MindLock::write`] or
/// [`MindLock::read`] on the returned value to block until the lock is held.
///
/// spec: HOME-9 -- every allowed home has its own `.lock`, taken in a fixed
/// order (the default home, then `extra_homes` order) so two commands cannot
/// deadlock. A home whose lock file cannot be opened for writing (a sandbox
/// that allows only reads there) is locked through a read-only handle, and one
/// with no lock file that cannot be created because writes are denied is
/// skipped: nothing will be written there. Any other failure to open the
/// default home's lock is an error, as before.
pub fn open(paths: &Paths) -> Result<MindLock> {
    let mut files = Vec::new();
    if let Some(lock) = open_one(&paths.mind_home, paths.lock_file(), true)? {
        files.push(lock);
    }
    for home in paths.extra_homes() {
        if let Some(lock) = open_one(&home, home.join(".lock"), false)? {
            files.push(lock);
        }
    }
    Ok(MindLock { files })
}

fn open_one(
    home: &std::path::Path,
    lock_path: std::path::PathBuf,
    required: bool,
) -> Result<Option<OneLock>> {
    // The mind home must exist before we can create the lock file.
    let made = mkdir_p(home);
    let rw = OpenOptions::new()
        .create(true)
        .truncate(false) // lock token only; preserve existing content
        .read(true)
        .write(true)
        .open(&lock_path);
    // Only a home we may not write gets the read-only fallback; any other
    // failure (e.g. the lock path is a directory) is reported as before.
    let denied = |e: &std::io::Error| {
        matches!(
            e.kind(),
            std::io::ErrorKind::PermissionDenied | std::io::ErrorKind::ReadOnlyFilesystem
        )
    };
    // A home that could not be created because writes are denied there is
    // read-only in the same sense as one whose lock file cannot be opened.
    let home_denied = matches!(&made, Err(MindError::Io { source, .. }) if denied(source));
    let file = match rw {
        Ok(f) => f,
        Err(e) if denied(&e) || home_denied => {
            match OpenOptions::new().read(true).open(&lock_path) {
                Ok(f) => f,
                // Nothing can be written in this home, so there is nothing
                // for its lock to guard.
                Err(_) => return Ok(None),
            }
        }
        Err(_) if !required => return Ok(None),
        Err(e) => {
            made?;
            return Err(MindError::io(&lock_path, e));
        }
    };
    Ok(Some(OneLock {
        inner: RwLock::new(file),
        path: lock_path,
    }))
}

/// A progress step while another process holds the lock, so a blocked command
/// says what it waits on (PRG-4). The probe that set `busy` has already let
/// go, so a lock freed in between only shows the step briefly.
// spec: PRG-4
fn wait_step(busy: bool) -> Option<crate::progress::Step<'static>> {
    busy.then(|| crate::progress::step("waiting for another mind command to finish"))
}

/// Set to `1` on every hook `mind` runs (HOOK-144).
pub const IN_HOOK_ENV: &str = "MIND_IN_HOOK";

/// Refuse to wait on a busy lock from inside a hook (HOOK-144): the holder is
/// the `mind` that ran the hook, which waits for the hook in turn.
// spec: HOOK-144
fn refuse_nested(busy: bool) -> Result<()> {
    if busy && std::env::var_os(IN_HOOK_ENV).is_some_and(|v| v == "1") {
        return Err(MindError::NestedInHook);
    }
    Ok(())
}

impl MindLock {
    /// Acquire the lock exclusively (mutating commands). Blocks until available.
    // spec: STO-40 STO-41 STO-42
    pub fn write(&mut self) -> Result<WriteGuard<'_>> {
        let busy = self.files.iter_mut().any(|l| l.inner.try_write().is_err());
        refuse_nested(busy)?;
        let _step = wait_step(busy);
        let mut guards = Vec::new();
        for l in self.files.iter_mut() {
            let path = l.path.clone();
            guards.push(l.inner.write().map_err(|e| MindError::io(&path, e))?);
        }
        Ok(WriteGuard { _guards: guards })
    }

    /// Acquire the lock shared (read-only commands). Blocks until available.
    // spec: STO-40 STO-41 STO-42
    pub fn read(&self) -> Result<ReadGuard<'_>> {
        let busy = self.files.iter().any(|l| l.inner.try_read().is_err());
        refuse_nested(busy)?;
        let _step = wait_step(busy);
        let mut guards = Vec::new();
        for l in &self.files {
            guards.push(l.inner.read().map_err(|e| MindError::io(&l.path, e))?);
        }
        Ok(ReadGuard { _guards: guards })
    }

    /// Try to acquire a shared lock without blocking. Returns `None` if the
    /// lock is already held exclusively by another process (e.g. during a TUI
    /// poll tick while a mutation is in progress). The TUI uses this for its
    /// ~1s refresh poll so it never freezes behind a writer (TUI-15, TUI-25).
    // spec: TUI-25
    pub fn try_read(&self) -> Option<ReadGuard<'_>> {
        let mut guards = Vec::new();
        for l in &self.files {
            guards.push(l.inner.try_read().ok()?);
        }
        Some(ReadGuard { _guards: guards })
    }

    /// Try to acquire the lock exclusively without blocking. Returns `None`
    /// while any other process holds it, so an unattended auto-update run
    /// steps aside instead of queueing behind the user (AUP-18).
    // spec: AUP-18
    pub fn try_write(&mut self) -> Option<WriteGuard<'_>> {
        let mut guards = Vec::new();
        for l in self.files.iter_mut() {
            guards.push(l.inner.try_write().ok()?);
        }
        Some(WriteGuard { _guards: guards })
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::error::MindError;
    use std::sync::atomic::{AtomicU32, Ordering};

    static COUNTER: AtomicU32 = AtomicU32::new(0);

    fn temp_paths(label: &str) -> (Paths, std::path::PathBuf) {
        let n = COUNTER.fetch_add(1, Ordering::SeqCst);
        let base =
            std::env::temp_dir().join(format!("mind-lock-{}-{n}-{label}", std::process::id()));
        let paths = Paths {
            mind_home: base.join("mind"),
            claude_home: base.join("claude"),
        };
        (paths, base)
    }

    fn cleanup(base: &std::path::Path) {
        let _ = std::fs::remove_dir_all(base);
    }

    #[test]
    fn exclusive_lock_on_fresh_home_succeeds() {
        // spec: STO-42
        let (paths, base) = temp_paths("excl");
        let mut lock = open(&paths).expect("open lock on fresh mind home");
        let _guard = lock.write().expect("exclusive acquire should succeed");
        drop(_guard);
        cleanup(&base);
    }

    #[test]
    fn shared_lock_on_fresh_home_succeeds() {
        // spec: STO-42
        let (paths, base) = temp_paths("shared");
        let lock = open(&paths).expect("open lock on fresh mind home");
        let _guard = lock.read().expect("shared acquire should succeed");
        drop(_guard);
        cleanup(&base);
    }

    #[test]
    fn two_shared_locks_coexist() {
        // Two separate RwLock handles on the same file can both hold a read lock.
        // spec: STO-41 STO-42
        let (paths, base) = temp_paths("twoshared");
        // Ensure the mind home and lock file exist first.
        mkdir_p(&paths.mind_home).unwrap();
        let lock_path = paths.lock_file();

        let f1 = OpenOptions::new()
            .create(true)
            .truncate(false)
            .read(true)
            .write(true)
            .open(&lock_path)
            .unwrap();
        let f2 = OpenOptions::new()
            .read(true)
            .write(true)
            .open(&lock_path)
            .unwrap();

        let l1 = RwLock::new(f1);
        let l2 = RwLock::new(f2);

        // Both shared guards held at the same time.
        let _g1 = l1.read().expect("first shared lock");
        // A second shared lock must not block - use try_read to avoid blocking.
        let _g2 = l2
            .try_read()
            .expect("second shared lock should succeed while first is held");
        cleanup(&base);
    }

    #[test]
    fn exclusive_lock_excludes_a_second_exclusive_holder() {
        // Hold an exclusive lock on one handle; a second handle's try_write must
        // be refused while the first is held, then succeed once it is dropped.
        // This is the core mutual-exclusion guarantee; it would fail if write()
        // did not take a real OS-level exclusive lock.
        // spec: STO-41 STO-42
        let (paths, base) = temp_paths("exclexcl");
        mkdir_p(&paths.mind_home).unwrap();
        let lock_path = paths.lock_file();

        let f1 = OpenOptions::new()
            .create(true)
            .truncate(false)
            .read(true)
            .write(true)
            .open(&lock_path)
            .unwrap();
        let f2 = OpenOptions::new()
            .read(true)
            .write(true)
            .open(&lock_path)
            .unwrap();
        let mut l1 = RwLock::new(f1);
        let mut l2 = RwLock::new(f2);

        let g1 = l1.write().expect("first exclusive lock");
        assert!(
            l2.try_write().is_err(),
            "a second exclusive lock must be refused while the first is held"
        );
        drop(g1);
        // After release the second exclusive lock must now succeed.
        let _g2 = l2
            .try_write()
            .expect("second exclusive lock should succeed after the first is released");
        cleanup(&base);
    }

    #[test]
    fn exclusive_lock_excludes_a_shared_reader() {
        // A held exclusive lock must block shared readers too: a reader must not
        // observe a writer mid-update. try_read must be refused while the
        // exclusive lock is held.
        // spec: STO-41 STO-42
        let (paths, base) = temp_paths("exclshared");
        mkdir_p(&paths.mind_home).unwrap();
        let lock_path = paths.lock_file();

        let f1 = OpenOptions::new()
            .create(true)
            .truncate(false)
            .read(true)
            .write(true)
            .open(&lock_path)
            .unwrap();
        let f2 = OpenOptions::new()
            .read(true)
            .write(true)
            .open(&lock_path)
            .unwrap();
        let mut l1 = RwLock::new(f1);
        let l2 = RwLock::new(f2);

        let g1 = l1.write().expect("exclusive lock");
        assert!(
            l2.try_read().is_err(),
            "a shared reader must be refused while an exclusive lock is held"
        );
        drop(g1);
        let _g2 = l2
            .try_read()
            .expect("shared read should succeed after the exclusive lock is released");
        cleanup(&base);
    }

    #[test]
    fn shared_lock_excludes_an_exclusive_writer() {
        // A held shared lock must block a would-be exclusive writer: the writer
        // cannot begin a mutation while a reader holds the snapshot.
        // spec: STO-41 STO-42
        let (paths, base) = temp_paths("sharedexcl");
        mkdir_p(&paths.mind_home).unwrap();
        let lock_path = paths.lock_file();

        let f1 = OpenOptions::new()
            .create(true)
            .truncate(false)
            .read(true)
            .write(true)
            .open(&lock_path)
            .unwrap();
        let f2 = OpenOptions::new()
            .read(true)
            .write(true)
            .open(&lock_path)
            .unwrap();
        let l1 = RwLock::new(f1);
        let mut l2 = RwLock::new(f2);

        let g1 = l1.read().expect("shared lock");
        assert!(
            l2.try_write().is_err(),
            "an exclusive writer must be refused while a shared lock is held"
        );
        drop(g1);
        let _g2 = l2
            .try_write()
            .expect("exclusive write should succeed after the shared lock is released");
        cleanup(&base);
    }

    #[test]
    fn exclusive_write_blocks_until_holder_releases() {
        // End-to-end through the public API (open + write): a second exclusive
        // acquisition must BLOCK (not error, not proceed) until the first is
        // released. We prove blocking by ordering: thread B records the time it
        // acquires, and must acquire only after thread A has held the lock for a
        // measurable interval. A non-locking implementation would let B proceed
        // immediately and the ordering invariant would fail.
        // spec: STO-42
        use std::sync::Arc;
        use std::sync::atomic::AtomicBool;
        use std::time::{Duration, Instant};

        let (paths, base) = temp_paths("blockwait");
        mkdir_p(&paths.mind_home).unwrap();
        let paths = Arc::new(paths);
        let a_acquired = Arc::new(AtomicBool::new(false));
        let a_released = Arc::new(AtomicBool::new(false));

        let hold = Duration::from_millis(300);
        let p_a = Arc::clone(&paths);
        let acq_a = Arc::clone(&a_acquired);
        let rel_a = Arc::clone(&a_released);
        let a = std::thread::spawn(move || {
            let mut lock = open(&p_a).expect("open A");
            let guard = lock.write().expect("A exclusive");
            // Signal acquisition before the hold so B contends for real. A fixed
            // head-start sleep is unreliable on a loaded runner: it can oversleep
            // past the whole hold, so B starts after A already released.
            acq_a.store(true, Ordering::SeqCst);
            // Hold long enough that B must observe the release ordering.
            std::thread::sleep(hold);
            rel_a.store(true, Ordering::SeqCst);
            drop(guard);
        });

        // Wait until A actually holds the exclusive lock.
        while !a_acquired.load(Ordering::SeqCst) {
            std::thread::yield_now();
        }

        let p_b = Arc::clone(&paths);
        let rel_b = Arc::clone(&a_released);
        let start = Instant::now();
        let b = std::thread::spawn(move || {
            let mut lock = open(&p_b).expect("open B");
            let _guard = lock.write().expect("B exclusive");
            // When B finally acquires, A must already have released.
            assert!(
                rel_b.load(Ordering::SeqCst),
                "B acquired the exclusive lock before A released it (no mutual exclusion)"
            );
            start.elapsed()
        });

        a.join().unwrap();
        let waited = b.join().unwrap();
        assert!(
            waited >= Duration::from_millis(200),
            "B should have blocked roughly until A released; only waited {waited:?}"
        );
        cleanup(&base);
    }

    #[test]
    fn lock_failure_is_io_error_with_lock_path() {
        // When we cannot open the lock file (e.g. the path is a directory),
        // the error must be MindError::Io carrying the lock file path.
        // spec: STO-42
        let (paths, base) = temp_paths("err");
        // Create the mind home directory first.
        mkdir_p(&paths.mind_home).unwrap();
        let lock_path = paths.lock_file();
        // Make the lock path a directory so opening it as a file fails.
        std::fs::create_dir_all(&lock_path).unwrap();

        let result = open(&paths);
        cleanup(&base);
        match result {
            Err(MindError::Io { path, .. }) => {
                assert_eq!(path, lock_path, "Io error should carry the lock path");
            }
            Ok(_) => panic!("expected an error when lock path is a directory"),
            Err(e) => panic!("unexpected error variant: {e:?}"),
        }
    }
}