mur_core/plugin/

mod.rs

//! WASM plugin system — load, sandbox, and run .wasm plugins for Commander.
//!
//! Plugins extend Commander with custom step types, validators, and integrations.
//! Each plugin runs in a sandboxed WASM environment with limited host access.

#[cfg(feature = "wasm-plugins")]
pub mod host;
#[cfg(feature = "wasm-plugins")]
pub mod loader;
#[cfg(feature = "wasm-plugins")]
pub mod sandbox;

use serde::{Deserialize, Serialize};
use std::collections::HashMap;

/// Plugin manifest describing a WASM plugin's metadata and capabilities.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PluginManifest {
    /// Unique plugin identifier.
    pub id: String,
    /// Human-readable name.
    pub name: String,
    /// Plugin version (semver).
    pub version: String,
    /// Plugin description.
    pub description: String,
    /// Author or organization.
    pub author: String,
    /// Minimum Commander version required.
    pub min_commander_version: Option<String>,
    /// Capabilities this plugin requests.
    pub permissions: PluginPermissions,
    /// Custom configuration values.
    pub config: HashMap<String, String>,
}

/// Permissions a plugin may request from the host.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct PluginPermissions {
    /// Can read environment variables.
    pub read_vars: bool,
    /// Can set environment variables.
    pub set_vars: bool,
    /// Can make HTTP requests.
    pub http: bool,
    /// Can write to the log.
    pub log: bool,
}

/// Result of a plugin execution.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PluginResult {
    /// Whether the plugin execution succeeded.
    pub success: bool,
    /// Output produced by the plugin.
    pub output: String,
    /// Error message, if any.
    pub error: Option<String>,
}

/// Trait that all plugins must implement (host-side representation).
pub trait Plugin: Send + Sync {
    /// Return the plugin's manifest.
    fn manifest(&self) -> &PluginManifest;

    /// Initialize the plugin with the given configuration.
    fn initialize(&mut self, config: &HashMap<String, String>) -> anyhow::Result<()>;

    /// Execute the plugin's main function with the given input.
    fn execute(&mut self, input: &str) -> anyhow::Result<PluginResult>;

    /// Clean up resources held by the plugin.
    fn shutdown(&mut self) -> anyhow::Result<()>;
}

/// Registry of loaded plugins.
pub struct PluginRegistry {
    plugins: HashMap<String, Box<dyn Plugin>>,
}

impl PluginRegistry {
    /// Create an empty plugin registry.
    pub fn new() -> Self {
        Self {
            plugins: HashMap::new(),
        }
    }

    /// Register a plugin. Returns error if a plugin with the same ID already exists.
    pub fn register(&mut self, plugin: Box<dyn Plugin>) -> anyhow::Result<()> {
        let id = plugin.manifest().id.clone();
        if self.plugins.contains_key(&id) {
            anyhow::bail!("Plugin '{}' is already registered", id);
        }
        self.plugins.insert(id, plugin);
        Ok(())
    }

    /// Unregister and shut down a plugin by ID.
    pub fn unregister(&mut self, id: &str) -> anyhow::Result<()> {
        if let Some(mut plugin) = self.plugins.remove(id) {
            plugin.shutdown()?;
        }
        Ok(())
    }

    /// Get a reference to a registered plugin.
    pub fn get(&self, id: &str) -> Option<&dyn Plugin> {
        self.plugins.get(id).map(|p| p.as_ref())
    }

    /// Get a mutable reference to a registered plugin.
    pub fn get_mut(&mut self, id: &str) -> Option<&mut (dyn Plugin + 'static)> {
        self.plugins.get_mut(id).map(|p| &mut **p)
    }

    /// List all registered plugin manifests.
    pub fn list(&self) -> Vec<&PluginManifest> {
        self.plugins.values().map(|p| p.manifest()).collect()
    }

    /// Execute a plugin by ID with the given input.
    pub fn execute(&mut self, id: &str, input: &str) -> anyhow::Result<PluginResult> {
        let plugin = self
            .plugins
            .get_mut(id)
            .ok_or_else(|| anyhow::anyhow!("Plugin '{}' not found", id))?;
        plugin.execute(input)
    }
}

impl Default for PluginRegistry {
    fn default() -> Self {
        Self::new()
    }
}

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

    struct MockPlugin {
        manifest: PluginManifest,
        initialized: bool,
    }

    impl MockPlugin {
        fn new(id: &str) -> Self {
            Self {
                manifest: PluginManifest {
                    id: id.to_string(),
                    name: format!("Mock {}", id),
                    version: "1.0.0".to_string(),
                    description: "A mock plugin".to_string(),
                    author: "test".to_string(),
                    min_commander_version: None,
                    permissions: PluginPermissions::default(),
                    config: HashMap::new(),
                },
                initialized: false,
            }
        }
    }

    impl Plugin for MockPlugin {
        fn manifest(&self) -> &PluginManifest {
            &self.manifest
        }

        fn initialize(&mut self, _config: &HashMap<String, String>) -> anyhow::Result<()> {
            self.initialized = true;
            Ok(())
        }

        fn execute(&mut self, input: &str) -> anyhow::Result<PluginResult> {
            Ok(PluginResult {
                success: true,
                output: format!("Processed: {}", input),
                error: None,
            })
        }

        fn shutdown(&mut self) -> anyhow::Result<()> {
            self.initialized = false;
            Ok(())
        }
    }

    #[test]
    fn test_plugin_manifest_serialization() {
        let manifest = PluginManifest {
            id: "test-plugin".into(),
            name: "Test Plugin".into(),
            version: "1.0.0".into(),
            description: "A test".into(),
            author: "tester".into(),
            min_commander_version: Some("0.1.0".into()),
            permissions: PluginPermissions {
                read_vars: true,
                set_vars: false,
                http: true,
                log: true,
            },
            config: HashMap::new(),
        };
        let json = serde_json::to_string(&manifest).unwrap();
        let deserialized: PluginManifest = serde_json::from_str(&json).unwrap();
        assert_eq!(deserialized.id, "test-plugin");
        assert!(deserialized.permissions.read_vars);
        assert!(!deserialized.permissions.set_vars);
    }

    #[test]
    fn test_registry_register_and_list() {
        let mut registry = PluginRegistry::new();
        registry.register(Box::new(MockPlugin::new("p1"))).unwrap();
        registry.register(Box::new(MockPlugin::new("p2"))).unwrap();

        let list = registry.list();
        assert_eq!(list.len(), 2);
    }

    #[test]
    fn test_registry_duplicate_register() {
        let mut registry = PluginRegistry::new();
        registry.register(Box::new(MockPlugin::new("p1"))).unwrap();
        assert!(registry.register(Box::new(MockPlugin::new("p1"))).is_err());
    }

    #[test]
    fn test_registry_execute() {
        let mut registry = PluginRegistry::new();
        registry.register(Box::new(MockPlugin::new("p1"))).unwrap();

        let result = registry.execute("p1", "hello").unwrap();
        assert!(result.success);
        assert_eq!(result.output, "Processed: hello");
    }

    #[test]
    fn test_registry_execute_not_found() {
        let mut registry = PluginRegistry::new();
        assert!(registry.execute("nonexistent", "test").is_err());
    }

    #[test]
    fn test_registry_unregister() {
        let mut registry = PluginRegistry::new();
        registry.register(Box::new(MockPlugin::new("p1"))).unwrap();
        assert!(registry.get("p1").is_some());

        registry.unregister("p1").unwrap();
        assert!(registry.get("p1").is_none());
    }
}