heroforge_core/fs/

fs_interface.rs

//! High-level filesystem interface for Heroforge repositories.
//!
//! `FsInterface` provides a filesystem-like API with staging directory support.
//! All writes go to staging first, with background commits to the database.
//!
//! # Architecture
//!
//! ```text
//! ┌─────────────────────────────────────────────────────────────────┐
//! │                      FsInterface (sync API)                     │
//! │  - RwLock<StagingState>                                         │
//! │  - Author name (set at initialization)                          │
//! │  - All read/write operations acquire appropriate locks          │
//! └─────────────────────────────────────────────────────────────────┘
//!                               │
//!           ┌───────────────────┴───────────────────┐
//!           │                                       │
//!           ▼                                       ▼
//! ┌─────────────────────┐                 ┌─────────────────────────┐
//! │   Staging Directory │                 │    Commit Thread        │
//! │                     │                 │    (background)         │
//! └─────────────────────┘                 └─────────────────────────┘
//! ```
//!
//! # Example
//!
//! ```no_run
//! use heroforge_core::Repository;
//! use heroforge_core::fs::FsInterface;
//! use std::sync::Arc;
//!
//! let repo = Arc::new(Repository::open_rw("project.forge")?);
//! let fs = FsInterface::new(repo, "developer@example.com")?;
//!
//! // Write goes to staging (fast)
//! fs.write_file("config.json", b"{}")?;
//!
//! // Read checks staging first, then database
//! let content = fs.read_file("config.json")?;
//!
//! // Partial update (read-modify-write pattern)
//! fs.write_at("data.bin", 100, b"updated")?;
//!
//! // Force immediate commit (normally auto-commits every 1 minute)
//! fs.commit()?;
//! # Ok::<(), heroforge_core::FossilError>(())
//! ```

use std::path::PathBuf;
use std::sync::Arc;

use crate::fs::commit_thread::{CommitConfig, CommitTimer, commit_now};
use crate::fs::errors::{FsError, FsResult};
use crate::fs::operations::{DirectoryEntry, FileKind, FileMetadata, FilePermissions, FindResults};
use crate::fs::staging::{MAX_FILE_SIZE, Staging};
use crate::repo::Repository;

/// Status of the FsInterface
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FsInterfaceStatus {
    /// Active and accepting operations
    Active,
    /// Commit in progress
    Committing,
    /// Closed/disposed
    Closed,
}

/// High-level filesystem interface with staging support.
///
/// This is the recommended way to interact with Heroforge repositories for
/// filesystem-like operations. It provides:
///
/// - Fast writes via staging directory
/// - Layered reads (staging → database)
/// - Automatic background commits
/// - Partial file updates (read-modify-write)
/// - Thread-safe operations via RwLock
pub struct FsInterface {
    /// Reference to the underlying repository
    repo: Arc<Repository>,

    /// Staging state
    staging: Staging,

    /// Background commit timer
    commit_timer: Option<CommitTimer>,

    /// Current status
    status: FsInterfaceStatus,

    /// Current branch name
    branch: String,
}

impl FsInterface {
    /// Create a new FsInterface for a repository.
    ///
    /// # Arguments
    ///
    /// * `repo` - The repository to operate on
    /// * `author` - Author name for all commits from this interface
    ///
    /// # Example
    ///
    /// ```no_run
    /// use heroforge_core::Repository;
    /// use heroforge_core::fs::FsInterface;
    /// use std::sync::Arc;
    ///
    /// let repo = Arc::new(Repository::open_rw("project.forge")?);
    /// let fs = FsInterface::new(repo, "developer@example.com")?;
    /// # Ok::<(), heroforge_core::FossilError>(())
    /// ```
    pub fn new(repo: Arc<Repository>, author: &str) -> FsResult<Self> {
        Self::with_config(repo, author, CommitConfig::default())
    }

    /// Create a new FsInterface with custom configuration.
    pub fn with_config(
        repo: Arc<Repository>,
        author: &str,
        config: CommitConfig,
    ) -> FsResult<Self> {
        // Create staging directory alongside the repository
        let staging_dir = Self::get_staging_dir(&repo)?;

        let staging = Staging::new(staging_dir, author.to_string())?;

        // Start background commit timer
        let commit_timer = Some(CommitTimer::start(config));

        Ok(Self {
            repo,
            staging,
            commit_timer,
            status: FsInterfaceStatus::Active,
            branch: "trunk".to_string(),
        })
    }

    /// Create a new FsInterface without background commit timer.
    /// Useful for testing or manual commit control.
    pub fn without_timer(repo: Arc<Repository>, author: &str) -> FsResult<Self> {
        let staging_dir = Self::get_staging_dir(&repo)?;
        let staging = Staging::new(staging_dir, author.to_string())?;

        Ok(Self {
            repo,
            staging,
            commit_timer: None,
            status: FsInterfaceStatus::Active,
            branch: "trunk".to_string(),
        })
    }

    /// Get the staging directory path for a repository
    fn get_staging_dir(repo: &Repository) -> FsResult<PathBuf> {
        // Use project code to create unique staging directory
        let project_code = repo
            .project_code()
            .map_err(|e| FsError::DatabaseError(format!("Failed to get project code: {}", e)))?;

        let staging_dir = std::env::temp_dir()
            .join("heroforge-staging")
            .join(&project_code[..8.min(project_code.len())]);

        Ok(staging_dir)
    }

    /// Get the current status
    pub fn status(&self) -> FsInterfaceStatus {
        self.status
    }

    /// Get the author name
    pub fn author(&self) -> String {
        self.staging.read().author().to_string()
    }

    /// Get the current branch
    pub fn branch(&self) -> &str {
        &self.branch
    }

    /// Check if there are uncommitted changes
    pub fn has_changes(&self) -> bool {
        self.staging.read().is_dirty()
    }

    // ========================================================================
    // Read Operations (check staging first, then database)
    // ========================================================================

    /// Check if a path exists (in staging or database).
    pub fn exists(&self, path: &str) -> FsResult<bool> {
        self.validate_path(path)?;

        let state = self.staging.read();

        // Check staging first
        if state.has_file(path) {
            return Ok(!state.is_deleted(path));
        }

        // Check database
        self.exists_in_db(path)
    }

    /// Check if a path is a directory.
    pub fn is_dir(&self, path: &str) -> FsResult<bool> {
        self.validate_path(path)?;

        // Check if any file in staging starts with this path
        let state = self.staging.read();
        let prefix = if path.ends_with('/') {
            path.to_string()
        } else {
            format!("{}/", path)
        };

        for key in state.files().keys() {
            if key.starts_with(&prefix) && !state.is_deleted(key) {
                return Ok(true);
            }
        }

        // Check database
        self.is_dir_in_db(path)
    }

    /// Check if a path is a file.
    pub fn is_file(&self, path: &str) -> FsResult<bool> {
        self.validate_path(path)?;

        let state = self.staging.read();

        if state.has_file(path) {
            let file = state.get_file(path).unwrap();
            return Ok(!file.is_deleted);
        }

        self.is_file_in_db(path)
    }

    /// Get file metadata.
    pub fn stat(&self, path: &str) -> FsResult<FileMetadata> {
        self.validate_path(path)?;

        let state = self.staging.read();

        // Check staging first
        if let Some(staged) = state.get_file(path) {
            if staged.is_deleted {
                return Err(FsError::NotFound(path.to_string()));
            }

            return Ok(FileMetadata {
                path: path.to_string(),
                is_dir: false,
                size: staged.size,
                permissions: FilePermissions::file(),
                is_symlink: false,
                symlink_target: None,
                modified: staged.staged_at.elapsed().as_secs() as i64,
                hash: staged.original_hash.clone(),
                kind: FileKind::File,
            });
        }

        // Check database
        self.stat_from_db(path)
    }

    /// Read file content as bytes.
    ///
    /// Checks staging directory first, then falls back to database.
    pub fn read_file(&self, path: &str) -> FsResult<Vec<u8>> {
        self.validate_path(path)?;

        let state = self.staging.read();

        // Check staging first
        if state.has_file(path) {
            if state.is_deleted(path) {
                return Err(FsError::NotFound(path.to_string()));
            }
            return state.read_file(path);
        }

        // Read from database
        self.read_file_from_db(path)
    }

    /// Read file content as string.
    pub fn read_file_string(&self, path: &str) -> FsResult<String> {
        let bytes = self.read_file(path)?;
        String::from_utf8(bytes).map_err(|e| FsError::Encoding(e.to_string()))
    }

    /// List directory contents.
    pub fn list_dir(&self, path: &str) -> FsResult<Vec<DirectoryEntry>> {
        self.validate_path(path)?;

        let mut entries: std::collections::HashMap<String, DirectoryEntry> =
            std::collections::HashMap::new();

        // Get entries from staging
        let state = self.staging.read();
        for name in state.list_dir(path) {
            if let Some(staged) = state.get_file(&name) {
                if !staged.is_deleted {
                    let entry_name = name.rsplit('/').next().unwrap_or(&name).to_string();
                    entries.insert(
                        entry_name.clone(),
                        DirectoryEntry {
                            name: entry_name,
                            is_dir: false,
                            size: staged.size,
                            permissions: FilePermissions::file(),
                            modified: staged.staged_at.elapsed().as_secs() as i64,
                        },
                    );
                }
            }
        }

        // Get entries from database (if not overridden by staging)
        if let Ok(db_entries) = self.list_dir_from_db(path) {
            for entry in db_entries {
                if !entries.contains_key(&entry.name) {
                    // Check if deleted in staging
                    let full_path = if path.is_empty() || path == "/" {
                        entry.name.clone()
                    } else {
                        format!("{}/{}", path.trim_end_matches('/'), entry.name)
                    };
                    if !state.is_deleted(&full_path) {
                        entries.insert(entry.name.clone(), entry);
                    }
                }
            }
        }

        let mut result: Vec<_> = entries.into_values().collect();
        result.sort_by(|a, b| a.name.cmp(&b.name));
        Ok(result)
    }

    /// Find files matching a glob pattern.
    pub fn find(&self, pattern: &str) -> FsResult<FindResults> {
        if pattern.is_empty() {
            return Err(FsError::PatternError("Pattern cannot be empty".to_string()));
        }

        let glob = glob::Pattern::new(pattern).map_err(|e| FsError::PatternError(e.to_string()))?;

        let mut files: Vec<String> = Vec::new();
        let state = self.staging.read();

        // Find in staging
        for (path, staged) in state.files() {
            if !staged.is_deleted && glob.matches(path) {
                files.push(path.clone());
            }
        }

        // Find in database
        if let Ok(db_files) = self.find_in_db(pattern) {
            for path in db_files {
                if !files.contains(&path) && !state.is_deleted(&path) {
                    files.push(path);
                }
            }
        }

        files.sort();

        Ok(FindResults {
            count: files.len(),
            files,
            dirs_traversed: 0,
        })
    }

    /// Calculate disk usage of a path.
    pub fn disk_usage(&self, path: &str) -> FsResult<u64> {
        self.validate_path(path)?;

        let mut total: u64 = 0;
        let state = self.staging.read();

        // Sum staging files
        let prefix = if path.is_empty() || path == "/" {
            String::new()
        } else {
            format!("{}/", path.trim_end_matches('/'))
        };

        for (file_path, staged) in state.files() {
            if (prefix.is_empty() || file_path.starts_with(&prefix)) && !staged.is_deleted {
                total += staged.size;
            }
        }

        // Add database files (if not in staging)
        if let Ok(db_usage) = self.disk_usage_from_db(path) {
            total += db_usage;
        }

        Ok(total)
    }

    /// Count files matching a pattern.
    pub fn count_files(&self, pattern: &str) -> FsResult<usize> {
        let results = self.find(pattern)?;
        Ok(results.count)
    }

    // ========================================================================
    // Write Operations (all go to staging first)
    // ========================================================================

    /// Write file content.
    ///
    /// The file is written to the staging directory immediately.
    /// It will be committed to the database during the next auto-commit
    /// or when `commit()` is called.
    pub fn write_file(&self, path: &str, content: &[u8]) -> FsResult<()> {
        self.validate_path(path)?;
        self.validate_size(path, content.len() as u64)?;

        let mut state = self.staging.write();
        state.stage_file(path, content)
    }

    /// Write file content from a string.
    pub fn write_file_string(&self, path: &str, content: &str) -> FsResult<()> {
        self.write_file(path, content.as_bytes())
    }

    /// Write at a specific offset in a file (partial update).
    ///
    /// If the file exists only in the database, it will be promoted to staging first.
    /// This implements the read-modify-write pattern described in the spec.
    pub fn write_at(&self, path: &str, offset: u64, data: &[u8]) -> FsResult<()> {
        self.validate_path(path)?;

        let mut state = self.staging.write();

        // Check if file is already in staging
        if state.has_file(path) {
            if state.is_deleted(path) {
                return Err(FsError::NotFound(path.to_string()));
            }
            // File is in staging, write directly
            state.write_at(path, offset, data)?;
            state.mark_modified(path);
            return Ok(());
        }

        // File not in staging - need to promote from database
        drop(state); // Release lock before database read

        let content = self.read_file_from_db(path)?;
        let hash = self.get_file_hash_from_db(path)?;

        let mut state = self.staging.write();

        // Promote to staging
        state.stage_promoted(path, &content, hash)?;

        // Now write at offset
        state.write_at(path, offset, data)?;
        state.mark_modified(path);

        Ok(())
    }

    /// Delete a file.
    pub fn delete_file(&self, path: &str) -> FsResult<()> {
        self.validate_path(path)?;

        let mut state = self.staging.write();
        state.delete_file(path)
    }

    /// Delete a directory recursively.
    pub fn delete_dir(&self, path: &str) -> FsResult<()> {
        self.validate_path(path)?;

        let mut state = self.staging.write();
        state.delete_dir(path)
    }

    /// Copy a file.
    pub fn copy_file(&self, src: &str, dst: &str) -> FsResult<()> {
        self.validate_path(src)?;
        self.validate_path(dst)?;

        // Read from wherever the file exists
        let content = self.read_file(src)?;

        let mut state = self.staging.write();
        state.stage_file(dst, &content)
    }

    /// Move a file.
    pub fn move_file(&self, src: &str, dst: &str) -> FsResult<()> {
        self.copy_file(src, dst)?;
        self.delete_file(src)
    }

    /// Copy a directory recursively.
    pub fn copy_dir(&self, src: &str, dst: &str) -> FsResult<()> {
        self.validate_path(src)?;
        self.validate_path(dst)?;

        // Find all files in source directory
        let pattern = format!("{}/**/*", src.trim_end_matches('/'));
        let files = self.find(&pattern)?;

        for file_path in files.files {
            let rel_path = file_path
                .strip_prefix(src.trim_end_matches('/'))
                .unwrap_or(&file_path)
                .trim_start_matches('/');
            let dst_path = format!("{}/{}", dst.trim_end_matches('/'), rel_path);

            let content = self.read_file(&file_path)?;
            let mut state = self.staging.write();
            state.stage_file(&dst_path, &content)?;
        }

        Ok(())
    }

    /// Move a directory recursively.
    pub fn move_dir(&self, src: &str, dst: &str) -> FsResult<()> {
        self.copy_dir(src, dst)?;
        self.delete_dir(src)
    }

    // ========================================================================
    // Commit Operations
    // ========================================================================

    /// Force an immediate commit of all staged changes.
    ///
    /// Returns the commit hash, or "no-changes" if nothing was staged.
    pub fn commit(&self) -> FsResult<String> {
        commit_now(&self.staging, &self.repo)
    }

    /// Force a commit with a custom message.
    pub fn commit_with_message(&self, message: &str) -> FsResult<String> {
        let mut state = self.staging.write();

        if !state.is_dirty() {
            return Ok("no-changes".to_string());
        }

        let author = state.author().to_string();
        let branch = state.branch().to_string();

        // Collect staged changes (new/modified files and deletions)
        let mut staged_files: Vec<(String, Vec<u8>)> = Vec::new();
        let mut deletions: std::collections::HashSet<String> = std::collections::HashSet::new();

        for (path, staged_file) in state.files() {
            if staged_file.is_deleted {
                deletions.insert(path.clone());
            } else if staged_file.modified {
                let content = state.read_file(path)?;
                staged_files.push((path.clone(), content));
            }
        }

        if staged_files.is_empty() && deletions.is_empty() {
            state.mark_clean();
            return Ok("no-changes".to_string());
        }

        // Get parent commit hash
        let parent_hash = self
            .repo
            .branches()
            .get(&branch)
            .ok()
            .and_then(|b| b.tip().ok())
            .map(|c| c.hash);

        // Build complete file list: parent files + staged changes - deletions
        let mut files_to_commit: Vec<(String, Vec<u8>)> = Vec::new();
        let staged_paths: std::collections::HashSet<String> =
            staged_files.iter().map(|(p, _)| p.clone()).collect();

        // First, add files from parent that aren't being modified or deleted
        if let Some(ref parent) = parent_hash {
            if let Ok(parent_files) = self.repo.list_files_internal(parent) {
                for file_info in parent_files {
                    // Skip if this file is being deleted
                    if deletions.contains(&file_info.name) {
                        continue;
                    }
                    // Skip if this file is being replaced with staged content
                    if staged_paths.contains(&file_info.name) {
                        continue;
                    }
                    // Read the file content from parent and include it
                    if let Ok(content) = self.repo.read_file_internal(parent, &file_info.name) {
                        files_to_commit.push((file_info.name, content));
                    }
                }
            }
        }

        // Add all staged files (new and modified)
        files_to_commit.extend(staged_files);

        let files_refs: Vec<(&str, &[u8])> = files_to_commit
            .iter()
            .map(|(p, c)| (p.as_str(), c.as_slice()))
            .collect();

        let commit_hash = self
            .repo
            .commit_internal(
                &files_refs,
                message,
                &author,
                parent_hash.as_deref(),
                Some(&branch),
            )
            .map_err(|e| FsError::DatabaseError(format!("Commit failed: {}", e)))?;

        state.clear()?;

        Ok(commit_hash)
    }

    // ========================================================================
    // Branch Operations (force commit before switching)
    // ========================================================================

    /// Switch to a different branch.
    ///
    /// Forces a commit of any staged changes before switching.
    pub fn switch_branch(&mut self, branch: &str) -> FsResult<()> {
        // Force commit before branch switch
        self.commit()?;

        self.branch = branch.to_string();
        self.staging.write().set_branch(branch.to_string());

        Ok(())
    }

    // ========================================================================
    // Helper Methods
    // ========================================================================

    /// Validate path format
    fn validate_path(&self, path: &str) -> FsResult<()> {
        if path.is_empty() {
            return Err(FsError::InvalidPath("Path cannot be empty".to_string()));
        }
        if path.contains('\0') {
            return Err(FsError::InvalidPath(
                "Path cannot contain null bytes".to_string(),
            ));
        }
        Ok(())
    }

    /// Validate file size
    fn validate_size(&self, path: &str, size: u64) -> FsResult<()> {
        if size > MAX_FILE_SIZE {
            return Err(FsError::FileTooLarge {
                path: path.to_string(),
                size,
                max: MAX_FILE_SIZE,
            });
        }
        Ok(())
    }

    // Database access helpers

    fn exists_in_db(&self, path: &str) -> FsResult<bool> {
        let checkin = self.get_branch_tip()?;
        match self.repo.read_file_internal(&checkin, path) {
            Ok(_) => Ok(true),
            Err(_) => Ok(false),
        }
    }

    fn is_dir_in_db(&self, path: &str) -> FsResult<bool> {
        let checkin = self.get_branch_tip()?;
        match self.repo.list_directory_internal(&checkin, path) {
            Ok(files) => Ok(!files.is_empty()),
            Err(_) => Ok(false),
        }
    }

    fn is_file_in_db(&self, path: &str) -> FsResult<bool> {
        let checkin = self.get_branch_tip()?;
        match self.repo.read_file_internal(&checkin, path) {
            Ok(_) => Ok(true),
            Err(_) => Ok(false),
        }
    }

    fn stat_from_db(&self, path: &str) -> FsResult<FileMetadata> {
        let checkin = self.get_branch_tip()?;
        let files = self
            .repo
            .list_files_internal(&checkin)
            .map_err(|e| FsError::DatabaseError(e.to_string()))?;

        for file in files {
            if file.name == path {
                return Ok(FileMetadata {
                    path: path.to_string(),
                    is_dir: false,
                    size: file.size.unwrap_or(0) as u64,
                    permissions: FilePermissions::file(),
                    is_symlink: false,
                    symlink_target: None,
                    modified: 0,
                    hash: Some(file.hash),
                    kind: FileKind::File,
                });
            }
        }

        Err(FsError::NotFound(path.to_string()))
    }

    fn read_file_from_db(&self, path: &str) -> FsResult<Vec<u8>> {
        let checkin = self.get_branch_tip()?;
        self.repo
            .read_file_internal(&checkin, path)
            .map_err(|e| FsError::NotFound(format!("{}: {}", path, e)))
    }

    fn get_file_hash_from_db(&self, path: &str) -> FsResult<String> {
        let checkin = self.get_branch_tip()?;
        let files = self
            .repo
            .list_files_internal(&checkin)
            .map_err(|e| FsError::DatabaseError(e.to_string()))?;

        for file in files {
            if file.name == path {
                return Ok(file.hash);
            }
        }

        Err(FsError::NotFound(path.to_string()))
    }

    fn list_dir_from_db(&self, path: &str) -> FsResult<Vec<DirectoryEntry>> {
        let checkin = self.get_branch_tip()?;
        let files = self
            .repo
            .list_directory_internal(&checkin, path)
            .map_err(|e| FsError::DatabaseError(e.to_string()))?;

        Ok(files
            .into_iter()
            .map(|f| DirectoryEntry {
                name: f.name.rsplit('/').next().unwrap_or(&f.name).to_string(),
                is_dir: false,
                size: f.size.unwrap_or(0) as u64,
                permissions: FilePermissions::file(),
                modified: 0,
            })
            .collect())
    }

    fn find_in_db(&self, pattern: &str) -> FsResult<Vec<String>> {
        let checkin = self.get_branch_tip()?;
        let files = self
            .repo
            .find_files_internal(&checkin, pattern)
            .map_err(|e| FsError::DatabaseError(e.to_string()))?;

        Ok(files.into_iter().map(|f| f.name).collect())
    }

    fn disk_usage_from_db(&self, path: &str) -> FsResult<u64> {
        let checkin = self.get_branch_tip()?;
        let files = self
            .repo
            .list_files_internal(&checkin)
            .map_err(|e| FsError::DatabaseError(e.to_string()))?;

        let prefix = if path.is_empty() || path == "/" {
            String::new()
        } else {
            format!("{}/", path.trim_end_matches('/'))
        };

        let total: u64 = files
            .into_iter()
            .filter(|f| prefix.is_empty() || f.name.starts_with(&prefix))
            .map(|f| f.size.unwrap_or(0) as u64)
            .sum();

        Ok(total)
    }

    fn get_branch_tip(&self) -> FsResult<String> {
        let branch_ref = self
            .repo
            .branches()
            .get(&self.branch)
            .map_err(|e| FsError::DatabaseError(format!("Failed to get branch: {}", e)))?;

        let tip = branch_ref
            .tip()
            .map_err(|e| FsError::DatabaseError(format!("Failed to get branch tip: {}", e)))?;

        Ok(tip.hash)
    }
}

impl Drop for FsInterface {
    fn drop(&mut self) {
        // Perform final commit and stop timer
        let _ = self.commit();
        if let Some(mut timer) = self.commit_timer.take() {
            timer.stop();
        }
    }
}

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

    // Note: Full integration tests require a real repository
    // These tests focus on unit-level behavior

    #[test]
    fn test_validate_path() {
        // Create a minimal test - actual repo tests would go in integration tests
    }
}