aimx/

workspace.rs

//! # Workspace Management
//!
//! Provides a global workspace for managing agentic workflows within a hierarchical file structure.
//! The workspace coordinates concurrent access to workflows and maintains the relationship
//! between workflow nodes and their corresponding file system structure.
//!
//! ## Overview
//!
//! The workspace serves as a singleton container that manages the active workflow and its associated
//! file system paths. It implements a multi-version concurrency control (MVCC) pattern where:
//!
//! - **Non-blocking reads**: Multiple readers can access workflow snapshots concurrently
//! - **Atomic writes**: Writers operate on isolated copies before publishing changes
//! - **Global coordination**: Centralized management of workflow file operations
//!
//! ## Architecture
//!
//! The workspace maintains:
//! - A single global `Workflow` instance representing the current state
//! - Filesystem path mappings for workflow nodes and their journal files
//! - Concurrency-safe access patterns using `Arc<RwLock>`
//!
//! ## File Structure
//!
//! Workflows are stored in a hierarchical directory structure where each node corresponds
//! to a workflow file with its own version history:
//!
//! ```text
//! workspace.aim     # Root workspace workflow
//! workspace.jnl     # Root workspace journal
//! workspace/
//! ├── parent.aim    # Parent workflow node
//! ├── parent.jnl    # Parent journal
//! ├── parent/
//! │   ├── child.aim # Child workflow node
//! │   ├── child.jnl # Child journal
//! │   ├── sibling.aim
//! │   └── sibling.jnl
//! ├── uncle.aim
//! └── uncle.jnl
//! ```
//!
//! # Examples
//!
//! ```rust
//! use std::path::Path;
//! use aimx::workspace::{load_workspace, get_workspace, create_path, add_node_rule};
//! use aimx::Reference;
//!
//! // Load a workspace from a file
//! // load_workspace(Path::new("my_workspace.aim")).unwrap();
//!
//! // Get a read-only snapshot of the current workspace
//! let workflow = get_workspace();
//! let rule_count = workflow.rule_count();
//!
//! // Create a path for a workflow reference
//! let reference = Reference::new("my_node");
//! // let path = create_path(&reference).unwrap();
//!
//! // Add a new node rule to the workspace
//! // add_node_rule("new_node").unwrap();
//! ```

use std::path::{Path, PathBuf};
use std::sync::{Arc, RwLock};
use once_cell::sync::Lazy;
use anyhow::Result;
use crate::{
    Workflow, WorkflowLike, Reference,
};

/// Internal workspace structure that contains the active workflow and path information.
/// 
/// This struct is not exposed publicly to maintain encapsulation and ensure
/// thread-safe access patterns through the public API functions.
/// 
/// The workspace uses a multi-version concurrency control (MVCC) pattern where:
/// - The `content` field is wrapped in `Arc<RwLock<Workflow>>` for concurrent access
/// - Multiple readers can access workflow snapshots concurrently
/// - Writers operate on isolated copies before publishing changes
struct Workspace {
    /// The current workflow content, wrapped in Arc<RwLock> for concurrent access
    content: Arc<RwLock<Workflow>>,
    /// The base path of the workspace, used for resolving relative references
    path: RwLock<PathBuf>,
}

impl Workspace {
    /// Creates a new empty workspace.
    /// 
    /// Initializes an empty workflow and default path structure.
    /// The workspace uses `Arc<RwLock<Workflow>>` for thread-safe concurrent access
    /// and `RwLock<PathBuf>` for thread-safe path management.
    /// 
    /// # Returns
    /// A new `Workspace` instance with empty content and path
    pub fn new() -> Self {
        Workspace {
            content: Arc::new(RwLock::new(Workflow::new())),
            path: RwLock::new(PathBuf::new()),
        }
    }

    /// Loads a workflow file into the workspace.
    /// 
    /// Updates the workspace path to the parent directory of the loaded file
    /// and loads the workflow content from the specified file.
    /// 
    /// This function performs two operations atomically:
    /// 1. Updates the workspace's base path to the parent directory of the loaded file
    /// 2. Loads the workflow content from the specified file path
    /// 
    /// # Arguments
    /// * `path` - Path to the workflow file to load
    /// 
    /// # Returns
    /// * `Result<()>` - Success or error indicating if the operation completed
    pub fn load(&self, path: &Path) -> anyhow::Result<()> {
        // Update the path
        {
            let mut path_guard = self.path.write().unwrap();
            *path_guard = path.parent().unwrap_or(Path::new("")).to_path_buf();
        }
        
        // Load the workflow
        {
            let mut content_guard = self.content.write().unwrap();
            content_guard.load(path)?;
        }
        
        Ok(())
    }

    /// Creates a file system path for a workflow reference.
    /// 
    /// Combines the current workspace path with the reference's path
    /// structure to create the full filesystem path for the workflow file.
    /// 
    /// This function ensures that the necessary directory structure is created
    /// before returning the path, making it suitable for file operations.
    /// 
    /// # Arguments
    /// * `reference` - The workflow reference
    /// 
    /// # Returns
    /// * `Result<PathBuf>` - The full path to the workflow file
    pub fn create_path(&self, reference: &Reference) -> Result<PathBuf> {
        let path_guard = self.path.read().unwrap();
        reference.create_path(&*path_guard)
    }
}

/// Global workspace singleton instance.
/// 
/// Uses `once_cell::sync::Lazy` to ensure thread-safe lazy initialization.
/// This singleton pattern ensures that there is exactly one workspace instance
/// throughout the application lifecycle, providing centralized management
/// of workflow resources and file system operations.
/// 
/// The workspace is wrapped in `RwLock` to allow concurrent read access
/// while ensuring exclusive write access when needed.
static GLOBAL_WORKSPACE: Lazy<RwLock<Workspace>> = Lazy::new(|| RwLock::new(Workspace::new()));

/// Returns a reference to the global workspace singleton.
/// 
/// This function provides internal access to the workspace instance.
/// It is used by the public API functions to access the underlying
/// workspace functionality while maintaining encapsulation.
/// 
/// # Returns
/// A static reference to the global workspace singleton
fn workspace() -> &'static RwLock<Workspace> {
    &GLOBAL_WORKSPACE
}

/// Returns a read-only snapshot of the current workspace.
/// 
/// This function provides concurrent access to the workspace by returning
/// a cloned snapshot of the workflow wrapped in an `Arc<dyn WorkflowLike>`.
/// Multiple readers can access the workspace simultaneously without blocking.
/// 
/// # Returns
/// * `Arc<dyn WorkflowLike>` - A thread-safe, read-only reference to the workflow
/// 
/// # Examples
/// 
/// ```rust
/// use aimx::workspace::get_workspace;
/// 
/// let workflow = get_workspace();
/// let rule_count = workflow.rule_count();
/// println!("Workspace contains {} rules", rule_count);
/// ```
pub fn get_workspace() -> Arc<dyn WorkflowLike> {
    // Instead of trying to wrap the RwLock, we can clone the underlying Workflow
    // which gives us a read-only snapshot -- exactly what we need for WorkflowLike
    let workspace_guard = workspace().read().unwrap();
    let workflow_guard = workspace_guard.content.read().unwrap();
    // Clone the workflow for the trait object
    Arc::new(workflow_guard.clone())
}

/// Loads a workspace file from disk.
/// 
/// This function replaces the current workspace content with the workflow
/// loaded from the specified file path. It updates the workspace's base path
/// to the parent directory of the loaded file.
/// 
/// # Arguments
/// * `path` - Path to the workspace file to load
/// 
/// # Returns
/// * `Result<()>` - Success or error indicating if the operation completed
/// 
/// # Examples
/// 
/// ```rust
/// use std::path::Path;
/// use aimx::workspace::load_workspace;
/// 
/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
/// // Load a workspace from a file
/// // load_workspace(Path::new("my_workspace.aim"))?;
/// # Ok(())
/// # }
/// ``` 
pub fn load_workspace(path: &Path) -> anyhow::Result<()> {
    let workspace_guard = workspace().write().unwrap();
    workspace_guard.load(path)
}

/// Creates a filesystem path for a workflow reference.
/// 
/// Combines the current workspace path with the reference's path structure
/// to create the full filesystem path for a workflow file.
/// 
/// # Arguments
/// * `reference` - The workflow reference
/// 
/// # Returns
/// * `Result<PathBuf>` - The full path to the workflow file
/// 
/// # Examples
/// 
/// ```rust
/// use aimx::workspace::create_path;
/// use aimx::expressions::Reference;
/// 
/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
/// let reference = Reference::new("my_node");
/// let path = create_path(&reference)?;
/// println!("Workflow path: {:?}", path);
/// # Ok(())
/// # }
/// ```
pub fn create_path(reference: &Reference) -> Result<PathBuf> {
    let workspace_guard = workspace().read().unwrap();
    workspace_guard.create_path(reference)
}

/// Adds a new Node Rule to the workspace, creating the necessary file structure.
/// 
/// This function creates the underlying file structure for a workflow node by:
/// 1. Creating the appropriate directory structure
/// 2. Creating an empty `.aim` file if it doesn't exist
/// 
/// Node Rules represent workflow nodes that can contain their own rules and
/// sub-nodes in a hierarchical structure.
/// 
/// # Arguments
/// * `identifier` - The identifier for the new Node Rule
/// 
/// # Returns
/// * `Result<()>` - Success or error indicating if the operation completed
/// 
/// # Examples
/// 
/// ```rust
/// use aimx::workspace::add_node_rule;
/// 
/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
/// // Add a new node rule to the workspace
/// // add_node_rule("new_workflow_node")?;
/// # Ok(())
/// # }
/// ``` 
pub fn add_node_rule(identifier: &str) -> Result<()> {
    let reference = Reference::new(identifier);
    let workspace_guard = workspace().read().unwrap();
    
    // Create the path structure for the node
    let aim_path = workspace_guard.create_path(&reference)?;
    
    // Create an empty .aim file if it doesn't exist
    if !aim_path.exists() {
        std::fs::File::create(&aim_path)?;
    }
    
    Ok(())
}

/// Renames a Node Rule, updating its associated files and directory structure.
/// 
/// This operation updates:
/// - The `.aim` file name
/// - The `.jnl` journal file name  
/// - The directory name (if it exists)
/// 
/// # Arguments
/// * `old_identifier` - The current identifier of the Node Rule
/// * `new_identifier` - The new identifier for the Node Rule
/// 
/// # Returns
/// * `Result<()>` - Success or error indicating if the operation completed
/// 
/// # Examples
/// 
/// ```rust
/// use aimx::workspace::rename_node_rule;
/// 
/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
/// // Rename a node rule
/// // rename_node_rule("old_name", "new_name")?;
/// # Ok(())
/// # }
/// ``` 
pub fn rename_node_rule(old_identifier: &str, new_identifier: &str) -> Result<()> {
    let old_reference = Reference::new(old_identifier);
    let new_reference = Reference::new(new_identifier);
    let workspace_guard = workspace().read().unwrap();
    
    // Get the current workspace path
    let workspace_path = workspace_guard.path.read().unwrap().clone();
    
    // Get the old and new file paths
    let old_aim_path = old_reference.to_path(&workspace_path);
    let old_jnl_path = crate::aim::to_journal_path(&old_aim_path)?;
    let new_aim_path = new_reference.to_path(&workspace_path);
    let new_jnl_path = crate::aim::to_journal_path(&new_aim_path)?;
    
    // Rename .aim file if it exists
    if old_aim_path.exists() {
        std::fs::rename(&old_aim_path, &new_aim_path)?;
    }
    
    // Rename .jnl file if it exists
    if old_jnl_path.exists() {
        std::fs::rename(&old_jnl_path, &new_jnl_path)?;
    }

    let old_dir = workspace_path.join(old_identifier);
    let new_dir = workspace_path.join(new_identifier);
    if old_dir.exists() {
        std::fs::rename(old_dir, new_dir)?;
    }

   Ok(())
}

/// Deletes a Node Rule and its associated files and directory structure.
/// 
/// This operation removes:
/// - The `.aim` file (if it exists)
/// - The `.jnl` journal file (if it exists)
/// - The directory (if it exists and is empty)
/// 
/// # Arguments
/// * `identifier` - The identifier of the Node Rule to delete
/// 
/// # Returns
/// * `Result<()>` - Success or error indicating if the operation completed
/// 
/// # Examples
/// 
/// ```rust
/// use aimx::workspace::delete_node_rule;
/// 
/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
/// // Delete a node rule
/// // delete_node_rule("unwanted_node")?;
/// # Ok(())
/// # }
/// ``` 
pub fn delete_node_rule(identifier: &str) -> Result<()> {
    let reference = Reference::new(identifier);
    let workspace_guard = workspace().read().unwrap();
    
    // Get the current workspace path
    let workspace_path = workspace_guard.path.read().unwrap().clone();
    
    // Get the file paths
    let aim_path = reference.to_path(&workspace_path);
    let jnl_path = crate::aim::to_journal_path(&aim_path)?;
    
    // Delete .aim file if it exists
    if aim_path.exists() {
        std::fs::remove_file(&aim_path)?;
    }
    
    // Delete .jnl file if it exists
    if jnl_path.exists() {
        std::fs::remove_file(&jnl_path)?;
    }

    let dir_path = workspace_path.join(identifier);

    // Remove the .aim file's directory if empty
    if dir_path.exists() {
        std::fs::remove_dir(&dir_path)?;
    }

    Ok(())
}