heroforge_core/fs/

interface.rs

//! Main filesystem interface for Heroforge repositories
//!
//! This module provides the primary API for interacting with a Heroforge repository
//! as if it were a filesystem. It handles all the complexity of the underlying
//! SQLite storage while providing a familiar, intuitive interface.
//!
//! # Overview
//!
//! The `FileSystem` type is the main entry point. It provides methods for:
//! - Reading files and directories (no commits needed)
//! - Writing, copying, moving, and deleting files (auto-commit by default)
//! - Finding files with glob patterns
//! - Checking file status and permissions
//! - Transaction support for batch operations

use crate::fs::errors::{FsError, FsResult};
use crate::fs::operations::{
    DirectoryEntry, FileMetadata, FilePermissions, FindResults, FsOperation,
};
use crate::fs::transaction::{Transaction, TransactionMode};
use crate::repo::Repository;
use std::sync::Arc;
use std::sync::Mutex;

/// Status of the filesystem interface
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FileSystemStatus {
    /// Opened in read-only mode
    ReadOnly,
    /// Opened in read-write mode
    ReadWrite,
    /// Transaction is active
    TransactionActive,
    /// Closed/disposed
    Closed,
}

/// Handle to a file in the repository
#[derive(Debug, Clone)]
pub struct FileHandle {
    /// Path to the file
    pub path: String,
    /// File metadata
    pub metadata: FileMetadata,
    /// Commit hash where file exists
    pub commit: String,
}

/// Main filesystem interface for Heroforge repositories
///
/// This provides a filesystem-like API over the Heroforge repository storage.
/// All operations are atomic and maintain version history.
///
/// # Thread Safety
///
/// `FileSystem` is thread-safe. Multiple threads can read simultaneously,
/// but writes are serialized through an internal mutex.
///
/// # Example
///
/// ```no_run
/// use heroforge_core::Repository;
/// use heroforge_core::fs::FileSystem;
/// use std::sync::Arc;
///
/// fn main() -> heroforge_core::Result<()> {
///     let repo = Arc::new(Repository::open_rw("project.forge")?);
///     let fs = FileSystem::new(repo);
///
///     // Read without commit
///     let exists = fs.exists("README.md")?;
///     if !exists {
///         // Write with auto-commit
///         fs.write_file("README.md", b"# My Project", "admin", "Initialize README")?;
///     }
///
///     Ok(())
/// }
/// ```
pub struct FileSystem {
    /// Reference to the underlying repository
    repo: Arc<Repository>,

    /// Current status
    status: Arc<Mutex<FileSystemStatus>>,

    /// Active transaction (if any)
    active_transaction: Arc<Mutex<Option<Transaction>>>,

    /// Write lock for serializing concurrent writes
    write_lock: Arc<Mutex<()>>,
}

impl FileSystem {
    /// Create a new filesystem interface for a repository
    pub fn new(repo: Arc<Repository>) -> Self {
        Self {
            repo,
            status: Arc::new(Mutex::new(FileSystemStatus::ReadWrite)),
            active_transaction: Arc::new(Mutex::new(None)),
            write_lock: Arc::new(Mutex::new(())),
        }
    }

    /// Get current status
    pub fn status(&self) -> FileSystemStatus {
        *self.status.lock().unwrap()
    }

    /// Check if a path exists
    ///
    /// # Arguments
    ///
    /// * `path` - Path to check (relative to repository root)
    ///
    /// # Returns
    ///
    /// `true` if path exists, `false` otherwise
    pub fn exists(&self, path: &str) -> FsResult<bool> {
        self.validate_path(path)?;
        // TODO: Implement by checking manifest at trunk
        Ok(true)
    }

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

    /// Check if path is a file
    pub fn is_file(&self, path: &str) -> FsResult<bool> {
        self.validate_path(path)?;
        let metadata = self.stat(path)?;
        Ok(!metadata.is_dir)
    }

    /// Get file metadata
    ///
    /// # Arguments
    ///
    /// * `path` - Path to file/directory
    ///
    /// # Returns
    ///
    /// File metadata including size, permissions, etc.
    pub fn stat(&self, path: &str) -> FsResult<FileMetadata> {
        self.validate_path(path)?;
        // TODO: Implement by querying manifest
        Ok(FileMetadata {
            path: path.to_string(),
            is_dir: false,
            size: 0,
            permissions: FilePermissions::file(),
            is_symlink: false,
            symlink_target: None,
            modified: 0,
            hash: None,
            kind: crate::fs::operations::FileKind::File,
        })
    }

    /// Read file content as bytes
    ///
    /// # Arguments
    ///
    /// * `path` - Path to file
    ///
    /// # Returns
    ///
    /// File content as `Vec<u8>`
    pub fn read_file(&self, path: &str) -> FsResult<Vec<u8>> {
        self.validate_path(path)?;
        self.validate_is_file(path)?;
        // TODO: Implement by reading from blob storage
        Ok(Vec::new())
    }

    /// Read file content as string
    ///
    /// # Arguments
    ///
    /// * `path` - Path to file
    ///
    /// # Returns
    ///
    /// 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
    ///
    /// # Arguments
    ///
    /// * `path` - Directory path
    ///
    /// # Returns
    ///
    /// Vector of directory entries
    pub fn list_dir(&self, path: &str) -> FsResult<Vec<DirectoryEntry>> {
        self.validate_path(path)?;
        self.validate_is_directory(path)?;
        // TODO: Implement by traversing manifest
        Ok(Vec::new())
    }

    /// Write file content (creates or overwrites)
    ///
    /// # Arguments
    ///
    /// * `path` - Path to file
    /// * `content` - File content
    /// * `author` - Author name
    /// * `message` - Commit message
    ///
    /// # Returns
    ///
    /// Commit hash of the change
    pub fn write_file(
        &self,
        path: &str,
        content: &[u8],
        author: &str,
        message: &str,
    ) -> FsResult<String> {
        self.validate_path(path)?;
        let _lock = self.write_lock.lock();

        // Create operation
        let _op = FsOperation::WriteFile {
            path: path.to_string(),
            content: content.to_vec(),
        };

        // TODO: Execute operation and create commit
        // For now, return a dummy hash
        let _ = (author, message); // Use parameters
        Ok("commit_abc123def".to_string())
    }

    /// Copy a file
    pub fn copy_file(&self, src: &str, dst: &str, author: &str, message: &str) -> FsResult<String> {
        self.validate_path(src)?;
        self.validate_path(dst)?;
        self.validate_is_file(src)?;
        let _lock = self.write_lock.lock();

        let _op = FsOperation::CopyFile {
            src: src.to_string(),
            dst: dst.to_string(),
        };

        // TODO: Execute operation and create commit
        let _ = (author, message); // Use parameters
        Ok("commit_abc123def".to_string())
    }

    /// Copy a directory recursively
    pub fn copy_dir(&self, src: &str, dst: &str, author: &str, message: &str) -> FsResult<String> {
        self.validate_path(src)?;
        self.validate_path(dst)?;
        self.validate_is_directory(src)?;
        let _lock = self.write_lock.lock();

        let _op = FsOperation::CopyDir {
            src: src.to_string(),
            dst: dst.to_string(),
        };

        // TODO: Execute operation and create commit
        let _ = (author, message); // Use parameters
        Ok("commit_abc123def".to_string())
    }

    /// Move/rename a file
    pub fn move_file(&self, src: &str, dst: &str, author: &str, message: &str) -> FsResult<String> {
        self.validate_path(src)?;
        self.validate_path(dst)?;
        self.validate_is_file(src)?;
        let _lock = self.write_lock.lock();

        let _op = FsOperation::MoveFile {
            src: src.to_string(),
            dst: dst.to_string(),
        };

        // TODO: Execute operation and create commit
        let _ = (author, message); // Use parameters
        Ok("commit_abc123def".to_string())
    }

    /// Move/rename a directory
    pub fn move_dir(&self, src: &str, dst: &str, author: &str, message: &str) -> FsResult<String> {
        self.validate_path(src)?;
        self.validate_path(dst)?;
        self.validate_is_directory(src)?;
        let _lock = self.write_lock.lock();

        let _op = FsOperation::MoveDir {
            src: src.to_string(),
            dst: dst.to_string(),
        };

        // TODO: Execute operation and create commit
        let _ = (author, message); // Use parameters
        Ok("commit_abc123def".to_string())
    }

    /// Delete a file
    pub fn delete_file(&self, path: &str, author: &str, message: &str) -> FsResult<String> {
        self.validate_path(path)?;
        self.validate_is_file(path)?;
        let _lock = self.write_lock.lock();

        let _op = FsOperation::DeleteFile {
            path: path.to_string(),
        };

        // TODO: Execute operation and create commit
        let _ = (author, message); // Use parameters
        Ok("commit_abc123def".to_string())
    }

    /// Delete a directory recursively
    pub fn delete_dir(&self, path: &str, author: &str, message: &str) -> FsResult<String> {
        self.validate_path(path)?;
        self.validate_is_directory(path)?;
        let _lock = self.write_lock.lock();

        let _op = FsOperation::DeleteDir {
            path: path.to_string(),
        };

        // TODO: Execute operation and create commit
        let _ = (author, message); // Use parameters
        Ok("commit_abc123def".to_string())
    }

    /// Change file permissions
    pub fn chmod(
        &self,
        path: &str,
        permissions: FilePermissions,
        author: &str,
        message: &str,
    ) -> FsResult<String> {
        self.validate_path(path)?;
        let _lock = self.write_lock.lock();

        let _op = FsOperation::Chmod {
            path: path.to_string(),
            permissions,
            recursive: false,
        };

        // TODO: Execute operation and create commit
        let _ = (author, message); // Use parameters
        Ok("commit_abc123def".to_string())
    }

    /// Change permissions recursively
    pub fn chmod_recursive(
        &self,
        path: &str,
        permissions: FilePermissions,
        author: &str,
        message: &str,
    ) -> FsResult<String> {
        self.validate_path(path)?;
        let _lock = self.write_lock.lock();

        let _op = FsOperation::Chmod {
            path: path.to_string(),
            permissions,
            recursive: true,
        };

        // TODO: Execute operation and create commit
        let _ = (author, message); // Use parameters
        Ok("commit_abc123def".to_string())
    }

    /// Make file executable
    pub fn make_executable(&self, path: &str, author: &str, message: &str) -> FsResult<String> {
        self.validate_path(path)?;
        self.validate_is_file(path)?;
        let _lock = self.write_lock.lock();

        let _op = FsOperation::MakeExecutable {
            path: path.to_string(),
        };

        // TODO: Execute operation and create commit
        let _ = (author, message); // Use parameters
        Ok("commit_abc123def".to_string())
    }

    /// Create a symbolic link
    pub fn symlink(
        &self,
        link_path: &str,
        target_path: &str,
        author: &str,
        message: &str,
    ) -> FsResult<String> {
        self.validate_path(link_path)?;
        let _lock = self.write_lock.lock();

        let _op = FsOperation::Symlink {
            link_path: link_path.to_string(),
            target_path: target_path.to_string(),
        };

        // TODO: Execute operation and create commit
        let _ = (author, message); // Use parameters
        Ok("commit_abc123def".to_string())
    }

    /// Find files matching a glob pattern
    ///
    /// # Arguments
    ///
    /// * `pattern` - Glob pattern (e.g., "**/*.rs")
    ///
    /// # Returns
    ///
    /// List of matching file paths
    pub fn find(&self, pattern: &str) -> FsResult<FindResults> {
        // Validate pattern
        if pattern.is_empty() {
            return Err(FsError::PatternError("Pattern cannot be empty".to_string()));
        }

        // TODO: Implement glob matching
        Ok(FindResults::new())
    }

    /// Calculate disk usage of a path
    ///
    /// # Arguments
    ///
    /// * `path` - Path to directory or file
    ///
    /// # Returns
    ///
    /// Total size in bytes
    pub fn disk_usage(&self, path: &str) -> FsResult<u64> {
        self.validate_path(path)?;
        // TODO: Implement by traversing manifests
        Ok(0)
    }

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

    /// Begin a transaction for batch operations
    ///
    /// # Returns
    ///
    /// A transaction that can be used to group multiple operations
    pub fn begin_transaction(&self) -> FsResult<Transaction> {
        let tx = Transaction::new(TransactionMode::ReadWrite);

        let mut active = self.active_transaction.lock().unwrap();
        if active.is_some() {
            return Err(FsError::TransactionError(
                "Transaction already active".to_string(),
            ));
        }

        *active = Some(tx.clone());
        Ok(tx)
    }

    /// End the active transaction
    pub fn end_transaction(&self) -> FsResult<()> {
        let mut active = self.active_transaction.lock().unwrap();
        *active = None;
        Ok(())
    }

    /// Check if a transaction is active
    pub fn has_active_transaction(&self) -> bool {
        self.active_transaction.lock().unwrap().is_some()
    }

    /// Get the active transaction (if any)
    pub fn active_transaction(&self) -> Option<Transaction> {
        self.active_transaction.lock().unwrap().clone()
    }

    // 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(),
            ));
        }

        // Normalize path - remove double slashes, etc.
        Ok(())
    }

    /// Validate that path points to a file
    fn validate_is_file(&self, path: &str) -> FsResult<()> {
        let metadata = self.stat(path)?;
        if metadata.is_dir {
            return Err(FsError::NotAFile(path.to_string()));
        }
        Ok(())
    }

    /// Validate that path points to a directory
    fn validate_is_directory(&self, path: &str) -> FsResult<()> {
        let metadata = self.stat(path)?;
        if !metadata.is_dir {
            return Err(FsError::NotADirectory(path.to_string()));
        }
        Ok(())
    }
}

impl Clone for FileSystem {
    fn clone(&self) -> Self {
        Self {
            repo: Arc::clone(&self.repo),
            status: Arc::clone(&self.status),
            active_transaction: Arc::clone(&self.active_transaction),
            write_lock: Arc::clone(&self.write_lock),
        }
    }
}

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

    #[test]
    fn test_filesystem_creation() {
        // This would need a real repo to test
        // let fs = FileSystem::new(Arc::new(repo));
        // assert_eq!(fs.status(), FileSystemStatus::ReadWrite);
    }

    #[test]
    fn test_path_validation() {
        // Test with a mock setup
    }
}