bn/

index.rs

use std::collections::HashMap;
use std::fs;
use std::path::Path;
use std::time::{Duration, Instant};

use anyhow::{anyhow, Context, Result};
use chrono::{DateTime, Utc};
use fs2::FileExt;
use serde::{Deserialize, Serialize};

use crate::bean::{Bean, Status};
use crate::util::{atomic_write, natural_cmp};

// ---------------------------------------------------------------------------
// IndexEntry
// ---------------------------------------------------------------------------

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct IndexEntry {
    pub id: String,
    pub title: String,
    pub status: Status,
    pub priority: u8,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub parent: Option<String>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub dependencies: Vec<String>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub labels: Vec<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub assignee: Option<String>,
    pub updated_at: DateTime<Utc>,
    /// Artifacts this bean produces (for smart dependency inference)
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub produces: Vec<String>,
    /// Artifacts this bean requires (for smart dependency inference)
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub requires: Vec<String>,
    /// Whether this bean has a verify command (SPECs have verify, GOALs don't)
    #[serde(default)]
    pub has_verify: bool,
    /// Agent or user currently holding a claim on this bean (e.g., "spro:12345" for agent with PID)
    #[serde(skip_serializing_if = "Option::is_none")]
    pub claimed_by: Option<String>,
    /// Number of verify attempts so far
    #[serde(default)]
    pub attempts: u32,
    /// File paths this bean touches (for scope-based blocking)
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub paths: Vec<String>,
}

impl From<&Bean> for IndexEntry {
    fn from(bean: &Bean) -> Self {
        Self {
            id: bean.id.clone(),
            title: bean.title.clone(),
            status: bean.status,
            priority: bean.priority,
            parent: bean.parent.clone(),
            dependencies: bean.dependencies.clone(),
            labels: bean.labels.clone(),
            assignee: bean.assignee.clone(),
            updated_at: bean.updated_at,
            produces: bean.produces.clone(),
            requires: bean.requires.clone(),
            has_verify: bean.verify.is_some(),
            claimed_by: bean.claimed_by.clone(),
            attempts: bean.attempts,
            paths: bean.paths.clone(),
        }
    }
}

// ---------------------------------------------------------------------------
// Index
// ---------------------------------------------------------------------------

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Index {
    pub beans: Vec<IndexEntry>,
}

// Files to exclude when scanning for bean YAMLs.
const EXCLUDED_FILES: &[&str] = &["config.yaml", "index.yaml", "bean.yaml", "archive.yaml"];

/// Check if a filename represents a bean file (not a config/index/template file).
fn is_bean_filename(filename: &str) -> bool {
    if EXCLUDED_FILES.contains(&filename) {
        return false;
    }
    let ext = std::path::Path::new(filename)
        .extension()
        .and_then(|e| e.to_str());
    match ext {
        Some("md") => filename.contains('-'), // New format: {id}-{slug}.md
        Some("yaml") => true,                 // Legacy format: {id}.yaml
        _ => false,
    }
}

/// Count bean files by format in the beans directory.
/// Returns (md_count, yaml_count) tuple.
pub fn count_bean_formats(beans_dir: &Path) -> Result<(usize, usize)> {
    let mut md_count = 0;
    let mut yaml_count = 0;

    let dir_entries = fs::read_dir(beans_dir)
        .with_context(|| format!("Failed to read directory: {}", beans_dir.display()))?;

    for entry in dir_entries {
        let entry = entry?;
        let path = entry.path();

        let filename = path
            .file_name()
            .and_then(|n| n.to_str())
            .unwrap_or_default();

        if !is_bean_filename(filename) {
            continue;
        }

        let ext = path.extension().and_then(|e| e.to_str());
        match ext {
            Some("md") => md_count += 1,
            Some("yaml") => yaml_count += 1,
            _ => {}
        }
    }

    Ok((md_count, yaml_count))
}

impl Index {
    /// Build the index by reading all bean files from the beans directory.
    /// Supports both new format ({id}-{slug}.md) and legacy format ({id}.yaml).
    /// Excludes config.yaml, index.yaml, and bean.yaml.
    /// Sorts entries by ID using natural ordering.
    /// Returns an error if duplicate bean IDs are detected.
    pub fn build(beans_dir: &Path) -> Result<Self> {
        let mut entries = Vec::new();
        // Track which files define each ID to detect duplicates
        let mut id_to_files: HashMap<String, Vec<String>> = HashMap::new();

        let dir_entries = fs::read_dir(beans_dir)
            .with_context(|| format!("Failed to read directory: {}", beans_dir.display()))?;

        for entry in dir_entries {
            let entry = entry?;
            let path = entry.path();

            let filename = path
                .file_name()
                .and_then(|n| n.to_str())
                .unwrap_or_default();

            if !is_bean_filename(filename) {
                continue;
            }

            let bean = Bean::from_file(&path)
                .with_context(|| format!("Failed to parse bean: {}", path.display()))?;

            // Track this ID's file for duplicate detection
            id_to_files
                .entry(bean.id.clone())
                .or_default()
                .push(filename.to_string());

            entries.push(IndexEntry::from(&bean));
        }

        // Check for duplicate IDs
        let duplicates: Vec<_> = id_to_files
            .iter()
            .filter(|(_, files)| files.len() > 1)
            .collect();

        if !duplicates.is_empty() {
            let mut msg = String::from("Duplicate bean IDs detected:\n");
            for (id, files) in duplicates {
                msg.push_str(&format!("  ID '{}' defined in: {}\n", id, files.join(", ")));
            }
            return Err(anyhow!(msg));
        }

        entries.sort_by(|a, b| natural_cmp(&a.id, &b.id));

        Ok(Index { beans: entries })
    }

    /// Check whether the cached index is stale.
    /// Returns true if the index file is missing or if any bean file (.md or .yaml)
    /// in the beans directory has been modified after the index was last written.
    pub fn is_stale(beans_dir: &Path) -> Result<bool> {
        let index_path = beans_dir.join("index.yaml");

        // If index doesn't exist, it's stale
        if !index_path.exists() {
            return Ok(true);
        }

        let index_mtime = fs::metadata(&index_path)
            .with_context(|| "Failed to read index.yaml metadata")?
            .modified()
            .with_context(|| "Failed to get index.yaml mtime")?;

        let dir_entries = fs::read_dir(beans_dir)
            .with_context(|| format!("Failed to read directory: {}", beans_dir.display()))?;

        for entry in dir_entries {
            let entry = entry?;
            let path = entry.path();

            let filename = path
                .file_name()
                .and_then(|n| n.to_str())
                .unwrap_or_default();

            if !is_bean_filename(filename) {
                continue;
            }

            let file_mtime = fs::metadata(&path)
                .with_context(|| format!("Failed to read metadata: {}", path.display()))?
                .modified()
                .with_context(|| format!("Failed to get mtime: {}", path.display()))?;

            if file_mtime > index_mtime {
                return Ok(true);
            }
        }

        Ok(false)
    }

    /// Load the cached index or rebuild it if stale.
    /// This is the main entry point for read-heavy commands.
    pub fn load_or_rebuild(beans_dir: &Path) -> Result<Self> {
        if Self::is_stale(beans_dir)? {
            let index = Self::build(beans_dir)?;
            index.save(beans_dir)?;
            Ok(index)
        } else {
            Self::load(beans_dir)
        }
    }

    /// Load the index from the cached index.yaml file.
    pub fn load(beans_dir: &Path) -> Result<Self> {
        let index_path = beans_dir.join("index.yaml");
        let contents = fs::read_to_string(&index_path)
            .with_context(|| format!("Failed to read {}", index_path.display()))?;
        let index: Index =
            serde_yml::from_str(&contents).with_context(|| "Failed to parse index.yaml")?;
        Ok(index)
    }

    /// Save the index to .beans/index.yaml.
    pub fn save(&self, beans_dir: &Path) -> Result<()> {
        let index_path = beans_dir.join("index.yaml");
        let yaml = serde_yml::to_string(self).with_context(|| "Failed to serialize index")?;
        atomic_write(&index_path, &yaml)
            .with_context(|| format!("Failed to write {}", index_path.display()))?;
        Ok(())
    }

    /// Collect all archived beans from .beans/archive/ directory.
    /// Walks through year/month subdirectories and loads all bean files.
    /// Returns IndexEntry items for archived beans.
    pub fn collect_archived(beans_dir: &Path) -> Result<Vec<IndexEntry>> {
        let mut entries = Vec::new();
        let archive_dir = beans_dir.join("archive");

        if !archive_dir.is_dir() {
            return Ok(entries);
        }

        // Walk through archive directory recursively
        Self::walk_archive_dir(&archive_dir, &mut entries)?;

        Ok(entries)
    }

    /// Recursively walk archive directory and collect bean entries.
    /// Uses catch_unwind to survive YAML parser panics from corrupt files.
    fn walk_archive_dir(dir: &Path, entries: &mut Vec<IndexEntry>) -> Result<()> {
        use crate::bean::Bean;

        if !dir.is_dir() {
            return Ok(());
        }

        for entry in fs::read_dir(dir)? {
            let entry = entry?;
            let path = entry.path();

            if path.is_dir() {
                Self::walk_archive_dir(&path, entries)?;
            } else if path.is_file() {
                if let Some(filename) = path.file_name().and_then(|n| n.to_str()) {
                    if is_bean_filename(filename) {
                        let path_clone = path.clone();
                        let result = std::panic::catch_unwind(|| Bean::from_file(&path_clone));
                        match result {
                            Ok(Ok(bean)) => entries.push(IndexEntry::from(&bean)),
                            Ok(Err(_)) => {} // normal parse error, skip silently
                            Err(_) => {
                                eprintln!(
                                    "warning: skipping corrupt archive file (parser panic): {}",
                                    path.display()
                                );
                            }
                        }
                    }
                }
            }
        }

        Ok(())
    }
}

// ---------------------------------------------------------------------------
// ArchiveIndex — cached index of archived beans
// ---------------------------------------------------------------------------

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ArchiveIndex {
    pub beans: Vec<IndexEntry>,
}

impl ArchiveIndex {
    /// Build the archive index by walking `.beans/archive/` recursively.
    /// Reuses `Index::collect_archived` to find all archived bean files,
    /// then sorts entries by ID using natural ordering.
    pub fn build(beans_dir: &Path) -> Result<Self> {
        let mut entries = Index::collect_archived(beans_dir)?;
        entries.sort_by(|a, b| natural_cmp(&a.id, &b.id));
        Ok(ArchiveIndex { beans: entries })
    }

    /// Load the archive index from `.beans/archive.yaml`.
    pub fn load(beans_dir: &Path) -> Result<Self> {
        let path = beans_dir.join("archive.yaml");
        let contents = fs::read_to_string(&path)
            .with_context(|| format!("Failed to read {}", path.display()))?;
        let index: ArchiveIndex =
            serde_yml::from_str(&contents).with_context(|| "Failed to parse archive.yaml")?;
        Ok(index)
    }

    /// Save the archive index to `.beans/archive.yaml`.
    pub fn save(&self, beans_dir: &Path) -> Result<()> {
        let path = beans_dir.join("archive.yaml");
        let yaml =
            serde_yml::to_string(self).with_context(|| "Failed to serialize archive index")?;
        atomic_write(&path, &yaml)
            .with_context(|| format!("Failed to write {}", path.display()))?;
        Ok(())
    }

    /// Load cached archive index or rebuild if stale.
    pub fn load_or_rebuild(beans_dir: &Path) -> Result<Self> {
        let archive_yaml = beans_dir.join("archive.yaml");
        if Self::is_stale(beans_dir)? {
            let index = Self::build(beans_dir)?;
            // Only save if there are entries or the file already exists
            // (avoids creating archive.yaml when there's no archive dir)
            if !index.beans.is_empty() || archive_yaml.exists() {
                index.save(beans_dir)?;
            }
            Ok(index)
        } else if archive_yaml.exists() {
            Self::load(beans_dir)
        } else {
            // No archive dir and no archive.yaml — return empty
            Ok(ArchiveIndex { beans: Vec::new() })
        }
    }

    /// Check whether the cached archive index is stale.
    /// Returns true if archive.yaml is missing (and archive dir exists),
    /// or if any file in the archive tree has been modified after archive.yaml.
    pub fn is_stale(beans_dir: &Path) -> Result<bool> {
        let archive_yaml = beans_dir.join("archive.yaml");
        let archive_dir = beans_dir.join("archive");

        if !archive_yaml.exists() {
            // If the archive dir doesn't exist either, nothing to index
            return Ok(archive_dir.is_dir());
        }

        if !archive_dir.is_dir() {
            return Ok(false);
        }

        let index_mtime = fs::metadata(&archive_yaml)
            .with_context(|| "Failed to read archive.yaml metadata")?
            .modified()
            .with_context(|| "Failed to get archive.yaml mtime")?;

        Self::any_file_newer(&archive_dir, index_mtime)
    }

    /// Check if any file in the given directory tree is newer than the reference time.
    fn any_file_newer(dir: &Path, reference: std::time::SystemTime) -> Result<bool> {
        for entry in fs::read_dir(dir)? {
            let entry = entry?;
            let path = entry.path();
            if path.is_dir() {
                if Self::any_file_newer(&path, reference)? {
                    return Ok(true);
                }
            } else if path.is_file() {
                let mtime = fs::metadata(&path)?.modified()?;
                if mtime > reference {
                    return Ok(true);
                }
            }
        }
        Ok(false)
    }

    /// Append an entry, deduplicating by ID (replaces any existing entry with the same ID).
    pub fn append(&mut self, entry: IndexEntry) {
        self.beans.retain(|e| e.id != entry.id);
        self.beans.push(entry);
        self.beans.sort_by(|a, b| natural_cmp(&a.id, &b.id));
    }

    /// Remove an entry by ID.
    pub fn remove(&mut self, id: &str) {
        self.beans.retain(|e| e.id != id);
    }
}

// ---------------------------------------------------------------------------
// LockedIndex — exclusive access during read-modify-write
// ---------------------------------------------------------------------------

/// Default timeout for acquiring the index lock.
const LOCK_TIMEOUT: Duration = Duration::from_secs(5);

/// Exclusive handle to the index, backed by an advisory flock on `.beans/index.lock`.
///
/// Prevents concurrent read-modify-write races when multiple agents run in parallel.
/// The lock is held from acquisition until `save_and_release` is called or the
/// `LockedIndex` is dropped.
///
/// ```no_run
/// # use anyhow::Result;
/// # use std::path::Path;
/// # fn example(beans_dir: &Path) -> Result<()> {
/// use bn::index::LockedIndex;
/// let mut locked = LockedIndex::acquire(beans_dir)?;
/// locked.index.beans[0].title = "Updated".to_string();
/// locked.save_and_release()?;
/// # Ok(())
/// # }
/// ```
#[derive(Debug)]
pub struct LockedIndex {
    pub index: Index,
    lock_file: fs::File,
    beans_dir: std::path::PathBuf,
}

impl LockedIndex {
    /// Acquire an exclusive lock on the index, then load or rebuild it.
    /// Uses the default 5-second timeout.
    pub fn acquire(beans_dir: &Path) -> Result<Self> {
        Self::acquire_with_timeout(beans_dir, LOCK_TIMEOUT)
    }

    /// Acquire an exclusive lock with a custom timeout.
    pub fn acquire_with_timeout(beans_dir: &Path, timeout: Duration) -> Result<Self> {
        let lock_path = beans_dir.join("index.lock");
        let lock_file = fs::File::create(&lock_path)
            .with_context(|| format!("Failed to create lock file: {}", lock_path.display()))?;

        Self::flock_with_timeout(&lock_file, timeout)?;

        let index = Index::load_or_rebuild(beans_dir)?;

        Ok(Self {
            index,
            lock_file,
            beans_dir: beans_dir.to_path_buf(),
        })
    }

    /// Save the modified index and release the lock.
    pub fn save_and_release(self) -> Result<()> {
        self.index.save(&self.beans_dir)?;
        // self drops here, releasing the flock via Drop
        Ok(())
    }

    /// Poll for an exclusive flock with timeout.
    fn flock_with_timeout(file: &fs::File, timeout: Duration) -> Result<()> {
        let start = Instant::now();
        loop {
            match file.try_lock_exclusive() {
                Ok(()) => return Ok(()),
                Err(ref e) if e.kind() == std::io::ErrorKind::WouldBlock => {
                    if start.elapsed() >= timeout {
                        return Err(anyhow!(
                            "Timed out after {}s waiting for .beans/index.lock — \
                             another bn process may be running. \
                             If no other process is active, delete .beans/index.lock and retry.",
                            timeout.as_secs()
                        ));
                    }
                    std::thread::sleep(Duration::from_millis(50));
                }
                Err(e) => {
                    return Err(anyhow!("Failed to acquire index lock: {}", e));
                }
            }
        }
    }
}

impl Drop for LockedIndex {
    fn drop(&mut self) {
        // Use fs2's unlock explicitly (std's File::unlock stabilized in 1.89, above our MSRV)
        let _ = fs2::FileExt::unlock(&self.lock_file);
    }
}

// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------

#[cfg(test)]
mod tests {
    use super::*;
    use std::cmp::Ordering;
    use std::fs;
    use std::thread;
    use std::time::Duration;
    use tempfile::TempDir;

    /// Helper: create a .beans directory with some bean YAML files.
    fn setup_beans_dir() -> (TempDir, std::path::PathBuf) {
        let dir = TempDir::new().unwrap();
        let beans_dir = dir.path().join(".beans");
        fs::create_dir(&beans_dir).unwrap();

        // Create a few beans
        let bean1 = Bean::new("1", "First task");
        let bean2 = Bean::new("2", "Second task");
        let bean10 = Bean::new("10", "Tenth task");
        let mut bean3_1 = Bean::new("3.1", "Subtask");
        bean3_1.parent = Some("3".to_string());
        bean3_1.labels = vec!["backend".to_string()];
        bean3_1.dependencies = vec!["1".to_string()];

        bean1.to_file(beans_dir.join("1.yaml")).unwrap();
        bean2.to_file(beans_dir.join("2.yaml")).unwrap();
        bean10.to_file(beans_dir.join("10.yaml")).unwrap();
        bean3_1.to_file(beans_dir.join("3.1.yaml")).unwrap();

        // Create files that should be excluded
        fs::write(
            beans_dir.join("config.yaml"),
            "project: test\nnext_id: 11\n",
        )
        .unwrap();

        (dir, beans_dir)
    }

    // -- natural_cmp tests --

    #[test]
    fn natural_sort_basic() {
        assert_eq!(natural_cmp("1", "2"), Ordering::Less);
        assert_eq!(natural_cmp("2", "1"), Ordering::Greater);
        assert_eq!(natural_cmp("1", "1"), Ordering::Equal);
    }

    #[test]
    fn natural_sort_numeric_not_lexicographic() {
        // Lexicographic: "10" < "2", but natural: "10" > "2"
        assert_eq!(natural_cmp("2", "10"), Ordering::Less);
        assert_eq!(natural_cmp("10", "2"), Ordering::Greater);
    }

    #[test]
    fn natural_sort_dotted_ids() {
        assert_eq!(natural_cmp("3", "3.1"), Ordering::Less);
        assert_eq!(natural_cmp("3.1", "3.2"), Ordering::Less);
        assert_eq!(natural_cmp("3.2", "10"), Ordering::Less);
    }

    #[test]
    fn natural_sort_full_sequence() {
        let mut ids = vec!["10", "3.2", "1", "3", "3.1", "2"];
        ids.sort_by(|a, b| natural_cmp(a, b));
        assert_eq!(ids, vec!["1", "2", "3", "3.1", "3.2", "10"]);
    }

    // -- build tests --

    #[test]
    fn build_reads_all_beans_and_excludes_config() {
        let (_dir, beans_dir) = setup_beans_dir();
        let index = Index::build(&beans_dir).unwrap();

        // Should have 4 beans: 1, 2, 3.1, 10
        assert_eq!(index.beans.len(), 4);

        // Should be naturally sorted
        let ids: Vec<&str> = index.beans.iter().map(|e| e.id.as_str()).collect();
        assert_eq!(ids, vec!["1", "2", "3.1", "10"]);
    }

    #[test]
    fn build_extracts_fields_correctly() {
        let (_dir, beans_dir) = setup_beans_dir();
        let index = Index::build(&beans_dir).unwrap();

        let entry = index.beans.iter().find(|e| e.id == "3.1").unwrap();
        assert_eq!(entry.title, "Subtask");
        assert_eq!(entry.status, Status::Open);
        assert_eq!(entry.priority, 2);
        assert_eq!(entry.parent, Some("3".to_string()));
        assert_eq!(entry.dependencies, vec!["1".to_string()]);
        assert_eq!(entry.labels, vec!["backend".to_string()]);
    }

    #[test]
    fn build_excludes_index_and_bean_yaml() {
        let (_dir, beans_dir) = setup_beans_dir();

        // Create index.yaml and bean.yaml — these should be excluded
        fs::write(beans_dir.join("index.yaml"), "beans: []\n").unwrap();
        fs::write(
            beans_dir.join("bean.yaml"),
            "id: template\ntitle: Template\n",
        )
        .unwrap();

        let index = Index::build(&beans_dir).unwrap();
        assert_eq!(index.beans.len(), 4);
        assert!(!index.beans.iter().any(|e| e.id == "template"));
    }

    #[test]
    fn build_detects_duplicate_ids() {
        let dir = TempDir::new().unwrap();
        let beans_dir = dir.path().join(".beans");
        fs::create_dir(&beans_dir).unwrap();

        // Create two beans with the same ID in different files
        let bean_a = Bean::new("99", "Bean A");
        let bean_b = Bean::new("99", "Bean B");

        bean_a.to_file(beans_dir.join("99-a.md")).unwrap();
        bean_b.to_file(beans_dir.join("99-b.md")).unwrap();

        let result = Index::build(&beans_dir);
        assert!(result.is_err());

        let err = result.unwrap_err().to_string();
        assert!(err.contains("Duplicate bean IDs detected"));
        assert!(err.contains("99"));
        assert!(err.contains("99-a.md"));
        assert!(err.contains("99-b.md"));
    }

    #[test]
    fn build_detects_multiple_duplicate_ids() {
        let dir = TempDir::new().unwrap();
        let beans_dir = dir.path().join(".beans");
        fs::create_dir(&beans_dir).unwrap();

        // Create duplicates for two different IDs
        Bean::new("1", "First A")
            .to_file(beans_dir.join("1-a.md"))
            .unwrap();
        Bean::new("1", "First B")
            .to_file(beans_dir.join("1-b.md"))
            .unwrap();
        Bean::new("2", "Second A")
            .to_file(beans_dir.join("2-a.md"))
            .unwrap();
        Bean::new("2", "Second B")
            .to_file(beans_dir.join("2-b.md"))
            .unwrap();

        let result = Index::build(&beans_dir);
        assert!(result.is_err());

        let err = result.unwrap_err().to_string();
        assert!(err.contains("ID '1'"));
        assert!(err.contains("ID '2'"));
    }

    // -- is_stale tests --

    #[test]
    fn is_stale_when_index_missing() {
        let (_dir, beans_dir) = setup_beans_dir();
        assert!(Index::is_stale(&beans_dir).unwrap());
    }

    #[test]
    fn is_stale_when_yaml_newer_than_index() {
        let (_dir, beans_dir) = setup_beans_dir();

        // Build and save the index first
        let index = Index::build(&beans_dir).unwrap();
        index.save(&beans_dir).unwrap();

        // Wait a moment to ensure distinct mtimes
        thread::sleep(Duration::from_millis(50));

        // Modify a bean file — this makes it newer than the index
        let bean = Bean::new("1", "Modified first task");
        bean.to_file(beans_dir.join("1.yaml")).unwrap();

        assert!(Index::is_stale(&beans_dir).unwrap());
    }

    #[test]
    fn not_stale_when_index_is_fresh() {
        let (_dir, beans_dir) = setup_beans_dir();

        // Build and save
        let index = Index::build(&beans_dir).unwrap();
        index.save(&beans_dir).unwrap();

        // The index was just written, so it should not be stale
        // (index.yaml mtime >= all other yaml mtimes)
        assert!(!Index::is_stale(&beans_dir).unwrap());
    }

    // -- load_or_rebuild tests --

    #[test]
    fn load_or_rebuild_builds_when_no_index() {
        let (_dir, beans_dir) = setup_beans_dir();

        let index = Index::load_or_rebuild(&beans_dir).unwrap();
        assert_eq!(index.beans.len(), 4);

        // Should have created index.yaml
        assert!(beans_dir.join("index.yaml").exists());
    }

    #[test]
    fn load_or_rebuild_loads_when_fresh() {
        let (_dir, beans_dir) = setup_beans_dir();

        // Build + save
        let original = Index::build(&beans_dir).unwrap();
        original.save(&beans_dir).unwrap();

        // load_or_rebuild should load without rebuilding
        let loaded = Index::load_or_rebuild(&beans_dir).unwrap();
        assert_eq!(original, loaded);
    }

    // -- save / load round-trip --

    #[test]
    fn save_and_load_round_trip() {
        let (_dir, beans_dir) = setup_beans_dir();

        let index = Index::build(&beans_dir).unwrap();
        index.save(&beans_dir).unwrap();

        let loaded = Index::load(&beans_dir).unwrap();
        assert_eq!(index, loaded);
    }

    // -- empty directory --

    #[test]
    fn build_empty_directory() {
        let dir = TempDir::new().unwrap();
        let beans_dir = dir.path().join(".beans");
        fs::create_dir(&beans_dir).unwrap();

        let index = Index::build(&beans_dir).unwrap();
        assert!(index.beans.is_empty());
    }

    // -- LockedIndex tests --

    #[test]
    fn locked_index_acquire_and_save() {
        let (_dir, beans_dir) = setup_beans_dir();

        let mut locked = LockedIndex::acquire(&beans_dir).unwrap();
        assert_eq!(locked.index.beans.len(), 4);

        // Modify a title
        locked.index.beans[0].title = "Modified".to_string();
        locked.save_and_release().unwrap();

        // Verify the change persisted
        let index = Index::load(&beans_dir).unwrap();
        assert_eq!(index.beans[0].title, "Modified");
    }

    #[test]
    fn locked_index_blocks_concurrent_access() {
        let (_dir, beans_dir) = setup_beans_dir();

        // First lock
        let _locked = LockedIndex::acquire(&beans_dir).unwrap();

        // Second lock should fail with timeout
        let result = LockedIndex::acquire_with_timeout(&beans_dir, Duration::from_millis(200));
        assert!(result.is_err());
        let err = result.unwrap_err().to_string();
        assert!(
            err.contains("Timed out"),
            "Expected timeout error, got: {}",
            err
        );
    }

    #[test]
    fn locked_index_released_on_drop() {
        let (_dir, beans_dir) = setup_beans_dir();

        {
            let _locked = LockedIndex::acquire(&beans_dir).unwrap();
            // lock held in this scope
        }
        // lock released on drop

        // Should be able to acquire again
        let _locked = LockedIndex::acquire(&beans_dir).unwrap();
    }

    #[test]
    fn locked_index_creates_lock_file() {
        let (_dir, beans_dir) = setup_beans_dir();

        let _locked = LockedIndex::acquire(&beans_dir).unwrap();
        assert!(beans_dir.join("index.lock").exists());
    }

    // -- is_stale ignores non-yaml files --

    #[test]
    fn is_stale_ignores_non_yaml() {
        let (_dir, beans_dir) = setup_beans_dir();

        let index = Index::build(&beans_dir).unwrap();
        index.save(&beans_dir).unwrap();

        // Create a non-yaml file after the index
        thread::sleep(Duration::from_millis(50));
        fs::write(beans_dir.join("notes.txt"), "some notes").unwrap();

        // Should NOT be stale — non-yaml files don't count
        assert!(!Index::is_stale(&beans_dir).unwrap());
    }
}

#[cfg(test)]
mod archive_tests {
    use super::*;
    use tempfile::TempDir;

    #[test]
    fn collect_archived_finds_beans() {
        let dir = TempDir::new().unwrap();
        let beans_dir = dir.path().join(".beans");
        fs::create_dir(&beans_dir).unwrap();

        // Create archive structure
        let archive_dir = beans_dir.join("archive").join("2026").join("02");
        fs::create_dir_all(&archive_dir).unwrap();

        // Create an archived bean
        let mut bean = crate::bean::Bean::new("1", "Archived task");
        bean.status = crate::bean::Status::Closed;
        bean.to_file(archive_dir.join("1-archived-task.md"))
            .unwrap();

        let archived = Index::collect_archived(&beans_dir).unwrap();
        assert_eq!(archived.len(), 1);
        assert_eq!(archived[0].id, "1");
        assert_eq!(archived[0].status, crate::bean::Status::Closed);
    }

    #[test]
    fn collect_archived_empty_when_no_archive() {
        let dir = TempDir::new().unwrap();
        let beans_dir = dir.path().join(".beans");
        fs::create_dir(&beans_dir).unwrap();

        let archived = Index::collect_archived(&beans_dir).unwrap();
        assert!(archived.is_empty());
    }
}

#[cfg(test)]
mod format_count_tests {
    use super::*;
    use tempfile::TempDir;

    #[test]
    fn count_bean_formats_only_yaml() {
        let dir = TempDir::new().unwrap();
        let beans_dir = dir.path().join(".beans");
        fs::create_dir(&beans_dir).unwrap();

        // Create only yaml files
        let bean1 = crate::bean::Bean::new("1", "Task 1");
        let bean2 = crate::bean::Bean::new("2", "Task 2");
        bean1.to_file(beans_dir.join("1.yaml")).unwrap();
        bean2.to_file(beans_dir.join("2.yaml")).unwrap();

        let (md_count, yaml_count) = count_bean_formats(&beans_dir).unwrap();
        assert_eq!(md_count, 0);
        assert_eq!(yaml_count, 2);
    }

    #[test]
    fn count_bean_formats_only_md() {
        let dir = TempDir::new().unwrap();
        let beans_dir = dir.path().join(".beans");
        fs::create_dir(&beans_dir).unwrap();

        // Create only md files
        let bean1 = crate::bean::Bean::new("1", "Task 1");
        let bean2 = crate::bean::Bean::new("2", "Task 2");
        bean1.to_file(beans_dir.join("1-task-1.md")).unwrap();
        bean2.to_file(beans_dir.join("2-task-2.md")).unwrap();

        let (md_count, yaml_count) = count_bean_formats(&beans_dir).unwrap();
        assert_eq!(md_count, 2);
        assert_eq!(yaml_count, 0);
    }

    #[test]
    fn count_bean_formats_mixed() {
        let dir = TempDir::new().unwrap();
        let beans_dir = dir.path().join(".beans");
        fs::create_dir(&beans_dir).unwrap();

        // Create mixed formats
        let bean1 = crate::bean::Bean::new("1", "Task 1");
        let bean2 = crate::bean::Bean::new("2", "Task 2");
        let bean3 = crate::bean::Bean::new("3", "Task 3");
        bean1.to_file(beans_dir.join("1.yaml")).unwrap();
        bean2.to_file(beans_dir.join("2-task-2.md")).unwrap();
        bean3.to_file(beans_dir.join("3-task-3.md")).unwrap();

        let (md_count, yaml_count) = count_bean_formats(&beans_dir).unwrap();
        assert_eq!(md_count, 2);
        assert_eq!(yaml_count, 1);
    }

    #[test]
    fn count_bean_formats_excludes_config_files() {
        let dir = TempDir::new().unwrap();
        let beans_dir = dir.path().join(".beans");
        fs::create_dir(&beans_dir).unwrap();

        // Create excluded yaml files (config.yaml, index.yaml)
        fs::write(beans_dir.join("config.yaml"), "project: test").unwrap();
        fs::write(beans_dir.join("index.yaml"), "beans: []").unwrap();

        // Create one actual bean
        let bean1 = crate::bean::Bean::new("1", "Task 1");
        bean1.to_file(beans_dir.join("1-task-1.md")).unwrap();

        let (md_count, yaml_count) = count_bean_formats(&beans_dir).unwrap();
        assert_eq!(md_count, 1);
        assert_eq!(yaml_count, 0); // config.yaml and index.yaml are excluded
    }

    #[test]
    fn count_bean_formats_empty_dir() {
        let dir = TempDir::new().unwrap();
        let beans_dir = dir.path().join(".beans");
        fs::create_dir(&beans_dir).unwrap();

        let (md_count, yaml_count) = count_bean_formats(&beans_dir).unwrap();
        assert_eq!(md_count, 0);
        assert_eq!(yaml_count, 0);
    }
}

#[cfg(test)]
mod archive_index_tests {
    use super::*;
    use tempfile::TempDir;

    fn setup_beans_dir_with_archive() -> (TempDir, std::path::PathBuf) {
        let dir = TempDir::new().unwrap();
        let beans_dir = dir.path().join(".beans");
        fs::create_dir(&beans_dir).unwrap();

        let archive_dir = beans_dir.join("archive").join("2026").join("03");
        fs::create_dir_all(&archive_dir).unwrap();

        let mut bean1 = crate::bean::Bean::new("5", "Archived task five");
        bean1.status = crate::bean::Status::Closed;
        bean1.is_archived = true;
        bean1
            .to_file(archive_dir.join("5-archived-task-five.md"))
            .unwrap();

        let mut bean2 = crate::bean::Bean::new("3", "Archived task three");
        bean2.status = crate::bean::Status::Closed;
        bean2.is_archived = true;
        bean2
            .to_file(archive_dir.join("3-archived-task-three.md"))
            .unwrap();

        (dir, beans_dir)
    }

    #[test]
    fn archive_index_build_from_archive_dir() {
        let (_dir, beans_dir) = setup_beans_dir_with_archive();
        let archive = ArchiveIndex::build(&beans_dir).unwrap();

        assert_eq!(archive.beans.len(), 2);
        // Should be sorted by natural ordering: "3" before "5"
        assert_eq!(archive.beans[0].id, "3");
        assert_eq!(archive.beans[1].id, "5");
        assert_eq!(archive.beans[0].status, crate::bean::Status::Closed);
        assert_eq!(archive.beans[1].status, crate::bean::Status::Closed);
    }

    #[test]
    fn archive_index_build_empty_when_no_archive_dir() {
        let dir = TempDir::new().unwrap();
        let beans_dir = dir.path().join(".beans");
        fs::create_dir(&beans_dir).unwrap();

        let archive = ArchiveIndex::build(&beans_dir).unwrap();
        assert!(archive.beans.is_empty());
    }

    #[test]
    fn archive_index_save_load_roundtrip() {
        let (_dir, beans_dir) = setup_beans_dir_with_archive();
        let original = ArchiveIndex::build(&beans_dir).unwrap();
        original.save(&beans_dir).unwrap();

        let loaded = ArchiveIndex::load(&beans_dir).unwrap();
        assert_eq!(original, loaded);
    }

    #[test]
    fn archive_index_append_deduplicates() {
        let (_dir, beans_dir) = setup_beans_dir_with_archive();
        let mut archive = ArchiveIndex::build(&beans_dir).unwrap();
        assert_eq!(archive.beans.len(), 2);

        // Append a new entry
        let mut new_bean = crate::bean::Bean::new("7", "New archived");
        new_bean.status = crate::bean::Status::Closed;
        archive.append(IndexEntry::from(&new_bean));
        assert_eq!(archive.beans.len(), 3);

        // Append again with same ID — should replace, not duplicate
        let mut updated_bean = crate::bean::Bean::new("7", "Updated title");
        updated_bean.status = crate::bean::Status::Closed;
        archive.append(IndexEntry::from(&updated_bean));
        assert_eq!(archive.beans.len(), 3);

        let entry = archive.beans.iter().find(|e| e.id == "7").unwrap();
        assert_eq!(entry.title, "Updated title");
    }

    #[test]
    fn archive_index_remove() {
        let (_dir, beans_dir) = setup_beans_dir_with_archive();
        let mut archive = ArchiveIndex::build(&beans_dir).unwrap();
        assert_eq!(archive.beans.len(), 2);

        archive.remove("3");
        assert_eq!(archive.beans.len(), 1);
        assert_eq!(archive.beans[0].id, "5");

        // Removing non-existent ID is a no-op
        archive.remove("999");
        assert_eq!(archive.beans.len(), 1);
    }

    #[test]
    fn archive_index_is_stale_when_no_archive_yaml() {
        let (_dir, beans_dir) = setup_beans_dir_with_archive();
        // Archive dir exists but archive.yaml doesn't
        assert!(ArchiveIndex::is_stale(&beans_dir).unwrap());
    }

    #[test]
    fn archive_index_not_stale_when_no_archive_dir() {
        let dir = TempDir::new().unwrap();
        let beans_dir = dir.path().join(".beans");
        fs::create_dir(&beans_dir).unwrap();
        // Neither archive dir nor archive.yaml exist
        assert!(!ArchiveIndex::is_stale(&beans_dir).unwrap());
    }

    #[test]
    fn archive_index_not_stale_after_build_and_save() {
        let (_dir, beans_dir) = setup_beans_dir_with_archive();
        let archive = ArchiveIndex::build(&beans_dir).unwrap();
        archive.save(&beans_dir).unwrap();
        assert!(!ArchiveIndex::is_stale(&beans_dir).unwrap());
    }

    #[test]
    fn archive_index_stale_when_file_newer() {
        let (_dir, beans_dir) = setup_beans_dir_with_archive();
        let archive = ArchiveIndex::build(&beans_dir).unwrap();
        archive.save(&beans_dir).unwrap();

        // Wait and add a new file to the archive
        std::thread::sleep(std::time::Duration::from_millis(50));
        let archive_dir = beans_dir.join("archive").join("2026").join("03");
        let mut new_bean = crate::bean::Bean::new("9", "Newer");
        new_bean.status = crate::bean::Status::Closed;
        new_bean.is_archived = true;
        new_bean.to_file(archive_dir.join("9-newer.md")).unwrap();

        assert!(ArchiveIndex::is_stale(&beans_dir).unwrap());
    }

    #[test]
    fn archive_index_load_or_rebuild_builds_when_stale() {
        let (_dir, beans_dir) = setup_beans_dir_with_archive();
        let archive = ArchiveIndex::load_or_rebuild(&beans_dir).unwrap();
        assert_eq!(archive.beans.len(), 2);
        // Should have created archive.yaml
        assert!(beans_dir.join("archive.yaml").exists());
    }

    #[test]
    fn archive_index_load_or_rebuild_returns_empty_when_no_archive() {
        let dir = TempDir::new().unwrap();
        let beans_dir = dir.path().join(".beans");
        fs::create_dir(&beans_dir).unwrap();

        let archive = ArchiveIndex::load_or_rebuild(&beans_dir).unwrap();
        assert!(archive.beans.is_empty());
        // Should NOT create archive.yaml when there's nothing to index
        assert!(!beans_dir.join("archive.yaml").exists());
    }
}