mcp_sync/

plugin.rs

//! # Plugin System
//!
//! Extensible plugin architecture for transforming MCP configurations.
//!
//! Plugins can:
//! - Transform the canonical config before syncing
//! - Modify target-specific output
//! - Add custom server definitions
//!
//! # Built-in Plugins
//!
//! - `env-expander`: Expands environment variables in config values
//!
//! # Creating Custom Plugins
//!
//! Plugins are dynamic libraries (`.dylib`/`.so`/`.dll`) that export a `create_plugin` function:
//!
//! ```ignore
//! #[no_mangle]
//! pub extern "C" fn create_plugin() -> *mut dyn Plugin {
//!     Box::into_raw(Box::new(MyPlugin::new()))
//! }
//! ```

use crate::canon::Canon;
use anyhow::Result;
use serde_json::Value as JsonValue;
use std::path::Path;

/// Trait for MCP-Sync plugins.
///
/// Plugins can hook into various stages of the sync process to
/// transform configurations.
pub trait Plugin: Send + Sync {
    /// Returns the plugin name for logging and identification.
    fn name(&self) -> &str;

    /// Called when the plugin is loaded with its configuration.
    ///
    /// # Arguments
    /// * `config` - Plugin-specific configuration from `mcp.yaml`
    fn on_load(&mut self, config: &JsonValue) -> Result<()>;

    /// Transforms the canonical configuration before syncing to targets.
    ///
    /// This hook is called once per sync operation, before any target sync.
    ///
    /// # Arguments
    /// * `canon` - Mutable reference to the canonical configuration
    fn transform_canon(&self, canon: &mut Canon) -> Result<()>;

    /// Transforms the output for a specific target before writing.
    ///
    /// This hook is called for each target file that will be written.
    ///
    /// # Arguments
    /// * `target` - Name of the target (e.g., "Antigravity", "Claude")
    /// * `value` - Mutable reference to the JSON value being written
    fn transform_output(&self, target: &str, value: &mut JsonValue) -> Result<()>;
}

/// Manages plugin loading and execution.
pub struct PluginManager {
    plugins: Vec<Box<dyn Plugin>>,
    #[allow(dead_code)]
    libraries: Vec<libloading::Library>,
}

impl PluginManager {
    /// Creates a new empty plugin manager.
    pub fn new() -> Self {
        Self {
            plugins: Vec::new(),
            libraries: Vec::new(),
        }
    }

    /// Loads a built-in plugin by name.
    pub fn load_builtin(&mut self, name: &str, config: &JsonValue) -> Result<()> {
        let mut plugin: Box<dyn Plugin> = match name {
            "env-expander" => Box::new(EnvExpanderPlugin::new()),
            _ => anyhow::bail!("unknown built-in plugin: {}", name),
        };
        plugin.on_load(config)?;
        self.plugins.push(plugin);
        Ok(())
    }

    /// Loads a plugin from a dynamic library.
    ///
    /// # Safety
    /// The library must export a valid `create_plugin` function.
    pub unsafe fn load_dynamic(&mut self, path: &Path, config: &JsonValue) -> Result<()> {
        // SAFETY: Caller guarantees the library is valid
        let lib = unsafe { libloading::Library::new(path)? };
        let create: libloading::Symbol<unsafe extern "C" fn() -> *mut dyn Plugin> =
            unsafe { lib.get(b"create_plugin")? };
        // SAFETY: create_plugin returns a valid Box<dyn Plugin> pointer
        let raw = unsafe { create() };
        let mut plugin = unsafe { Box::from_raw(raw) };
        plugin.on_load(config)?;
        self.plugins.push(plugin);
        self.libraries.push(lib);
        Ok(())
    }

    /// Runs `transform_canon` on all loaded plugins.
    pub fn transform_canon(&self, canon: &mut Canon) -> Result<()> {
        for plugin in &self.plugins {
            plugin.transform_canon(canon)?;
        }
        Ok(())
    }

    /// Runs `transform_output` on all loaded plugins.
    pub fn transform_output(&self, target: &str, value: &mut JsonValue) -> Result<()> {
        for plugin in &self.plugins {
            plugin.transform_output(target, value)?;
        }
        Ok(())
    }

    /// Returns the number of loaded plugins.
    pub fn count(&self) -> usize {
        self.plugins.len()
    }
}

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

// ─────────────────────────── Built-in Plugins ───────────────────────────

/// Plugin that expands environment variables in configuration values.
///
/// # Configuration
/// ```yaml
/// plugins:
///   - name: env-expander
///     config:
///       prefix: "${"
///       suffix: "}"
/// ```
pub struct EnvExpanderPlugin {
    prefix: String,
    suffix: String,
}

impl EnvExpanderPlugin {
    /// Creates a new plugin with default delimiters (`${` and `}`).
    pub fn new() -> Self {
        Self {
            prefix: "${".to_string(),
            suffix: "}".to_string(),
        }
    }

    fn expand_string(&self, s: &str) -> String {
        let mut result = s.to_string();
        let mut start = 0;
        
        while let Some(prefix_pos) = result[start..].find(&self.prefix) {
            let abs_prefix = start + prefix_pos;
            let search_start = abs_prefix + self.prefix.len();
            
            if let Some(suffix_pos) = result[search_start..].find(&self.suffix) {
                let var_name = &result[search_start..search_start + suffix_pos];
                if let Ok(value) = std::env::var(var_name) {
                    let full_pattern = format!("{}{}{}", self.prefix, var_name, self.suffix);
                    result = result.replace(&full_pattern, &value);
                    // Don't advance start since we replaced content
                } else {
                    start = search_start + suffix_pos + self.suffix.len();
                }
            } else {
                break;
            }
        }
        
        result
    }

    fn expand_value(&self, value: &mut JsonValue) {
        match value {
            JsonValue::String(s) => {
                *s = self.expand_string(s);
            }
            JsonValue::Array(arr) => {
                for item in arr {
                    self.expand_value(item);
                }
            }
            JsonValue::Object(obj) => {
                for (_, v) in obj.iter_mut() {
                    self.expand_value(v);
                }
            }
            _ => {}
        }
    }
}

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

impl Plugin for EnvExpanderPlugin {
    fn name(&self) -> &str {
        "env-expander"
    }

    fn on_load(&mut self, config: &JsonValue) -> Result<()> {
        if let Some(prefix) = config.get("prefix").and_then(|v| v.as_str()) {
            self.prefix = prefix.to_string();
        }
        if let Some(suffix) = config.get("suffix").and_then(|v| v.as_str()) {
            self.suffix = suffix.to_string();
        }
        Ok(())
    }

    fn transform_canon(&self, canon: &mut Canon) -> Result<()> {
        for server in canon.servers.values_mut() {
            if let Some(cmd) = &mut server.command {
                *cmd = self.expand_string(cmd);
            }
            if let Some(args) = &mut server.args {
                for arg in args.iter_mut() {
                    *arg = self.expand_string(arg);
                }
            }
            if let Some(url) = &mut server.url {
                *url = self.expand_string(url);
            }
            if let Some(env) = &mut server.env {
                for value in env.values_mut() {
                    *value = self.expand_string(value);
                }
            }
        }
        Ok(())
    }

    fn transform_output(&self, _target: &str, value: &mut JsonValue) -> Result<()> {
        self.expand_value(value);
        Ok(())
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::canon::{Canon, CanonServer};
    use std::collections::BTreeMap;

    // Helper functions for Rust 2024 unsafe env var operations
    fn set_env(key: &str, value: &str) {
        // SAFETY: Test environment only, single-threaded test execution
        unsafe { std::env::set_var(key, value) };
    }
    
    fn remove_env(key: &str) {
        // SAFETY: Test environment only, single-threaded test execution
        unsafe { std::env::remove_var(key) };
    }

    // ─────────────────────────── EnvExpanderPlugin tests ───────────────────────────

    #[test]
    fn test_env_expander_new_default_delimiters() {
        let plugin = EnvExpanderPlugin::new();
        assert_eq!(plugin.prefix, "${");
        assert_eq!(plugin.suffix, "}");
    }

    #[test]
    fn test_env_expander_expand_string_simple() {
        set_env("TEST_VAR_123", "hello");
        let plugin = EnvExpanderPlugin::new();
        
        let result = plugin.expand_string("prefix ${TEST_VAR_123} suffix");
        
        assert_eq!(result, "prefix hello suffix");
        remove_env("TEST_VAR_123");
    }

    #[test]
    fn test_env_expander_expand_string_multiple() {
        set_env("VAR_A", "first");
        set_env("VAR_B", "second");
        let plugin = EnvExpanderPlugin::new();
        
        let result = plugin.expand_string("${VAR_A} and ${VAR_B}");
        
        assert_eq!(result, "first and second");
        remove_env("VAR_A");
        remove_env("VAR_B");
    }

    #[test]
    fn test_env_expander_expand_string_undefined_var() {
        let plugin = EnvExpanderPlugin::new();
        remove_env("UNDEFINED_VAR_XYZ");
        
        let result = plugin.expand_string("value: ${UNDEFINED_VAR_XYZ}");
        
        // Undefined vars are left as-is
        assert_eq!(result, "value: ${UNDEFINED_VAR_XYZ}");
    }

    #[test]
    fn test_env_expander_expand_string_no_vars() {
        let plugin = EnvExpanderPlugin::new();
        
        let result = plugin.expand_string("no variables here");
        
        assert_eq!(result, "no variables here");
    }

    #[test]
    fn test_env_expander_expand_string_custom_delimiters() {
        set_env("CUSTOM_VAR", "custom_value");
        let mut plugin = EnvExpanderPlugin::new();
        plugin.prefix = "{{".to_string();
        plugin.suffix = "}}".to_string();
        
        let result = plugin.expand_string("value: {{CUSTOM_VAR}}");
        
        assert_eq!(result, "value: custom_value");
        remove_env("CUSTOM_VAR");
    }

    #[test]
    fn test_env_expander_on_load_custom_config() {
        let mut plugin = EnvExpanderPlugin::new();
        let config = serde_json::json!({
            "prefix": "[[",
            "suffix": "]]"
        });
        
        plugin.on_load(&config).unwrap();
        
        assert_eq!(plugin.prefix, "[[");
        assert_eq!(plugin.suffix, "]]");
    }

    #[test]
    fn test_env_expander_on_load_partial_config() {
        let mut plugin = EnvExpanderPlugin::new();
        let config = serde_json::json!({
            "prefix": "%%"
        });
        
        plugin.on_load(&config).unwrap();
        
        assert_eq!(plugin.prefix, "%%");
        assert_eq!(plugin.suffix, "}"); // unchanged
    }

    #[test]
    fn test_env_expander_on_load_empty_config() {
        let mut plugin = EnvExpanderPlugin::new();
        let config = serde_json::json!({});
        
        plugin.on_load(&config).unwrap();
        
        assert_eq!(plugin.prefix, "${");
        assert_eq!(plugin.suffix, "}");
    }

    #[test]
    fn test_env_expander_transform_canon_command() {
        set_env("CMD_PATH", "/usr/bin/custom");
        let plugin = EnvExpanderPlugin::new();
        
        let mut servers = BTreeMap::new();
        servers.insert("test".to_string(), CanonServer {
            kind: None,
            command: Some("${CMD_PATH}".to_string()),
            args: None,
            env: None,
            cwd: None,
            url: None,
            headers: None,
            bearer_token_env_var: None,
            enabled: None,
        });
        let mut canon = Canon { version: Some(1), servers, plugins: vec![] };
        
        plugin.transform_canon(&mut canon).unwrap();
        
        assert_eq!(canon.servers["test"].command, Some("/usr/bin/custom".to_string()));
        remove_env("CMD_PATH");
    }

    #[test]
    fn test_env_expander_transform_canon_args() {
        set_env("ARG_VAL", "expanded_arg");
        let plugin = EnvExpanderPlugin::new();
        
        let mut servers = BTreeMap::new();
        servers.insert("test".to_string(), CanonServer {
            kind: None,
            command: Some("cmd".to_string()),
            args: Some(vec!["--value".to_string(), "${ARG_VAL}".to_string()]),
            env: None,
            cwd: None,
            url: None,
            headers: None,
            bearer_token_env_var: None,
            enabled: None,
        });
        let mut canon = Canon { version: Some(1), servers, plugins: vec![] };
        
        plugin.transform_canon(&mut canon).unwrap();
        
        let args = canon.servers["test"].args.as_ref().unwrap();
        assert_eq!(args[1], "expanded_arg");
        remove_env("ARG_VAL");
    }

    #[test]
    fn test_env_expander_transform_canon_url() {
        set_env("API_HOST", "api.example.com");
        let plugin = EnvExpanderPlugin::new();
        
        let mut servers = BTreeMap::new();
        servers.insert("api".to_string(), CanonServer {
            kind: Some("http".to_string()),
            command: None,
            args: None,
            env: None,
            cwd: None,
            url: Some("https://${API_HOST}/v1".to_string()),
            headers: None,
            bearer_token_env_var: None,
            enabled: None,
        });
        let mut canon = Canon { version: Some(1), servers, plugins: vec![] };
        
        plugin.transform_canon(&mut canon).unwrap();
        
        assert_eq!(canon.servers["api"].url, Some("https://api.example.com/v1".to_string()));
        remove_env("API_HOST");
    }

    #[test]
    fn test_env_expander_transform_output() {
        set_env("OUT_VAL", "output_value");
        let plugin = EnvExpanderPlugin::new();
        let mut value = serde_json::json!({
            "key": "${OUT_VAL}",
            "nested": {
                "inner": "${OUT_VAL}"
            }
        });
        
        plugin.transform_output("test", &mut value).unwrap();
        
        assert_eq!(value["key"], "output_value");
        assert_eq!(value["nested"]["inner"], "output_value");
        remove_env("OUT_VAL");
    }

    #[test]
    fn test_env_expander_expand_value_array() {
        set_env("ARR_VAL", "array_item");
        let plugin = EnvExpanderPlugin::new();
        let mut value = serde_json::json!(["static", "${ARR_VAL}", "other"]);
        
        plugin.expand_value(&mut value);
        
        assert_eq!(value[1], "array_item");
        remove_env("ARR_VAL");
    }

    #[test]
    fn test_env_expander_name() {
        let plugin = EnvExpanderPlugin::new();
        assert_eq!(plugin.name(), "env-expander");
    }

    // ─────────────────────────── PluginManager tests ───────────────────────────

    #[test]
    fn test_plugin_manager_new() {
        let manager = PluginManager::new();
        assert_eq!(manager.count(), 0);
    }

    #[test]
    fn test_plugin_manager_default() {
        let manager = PluginManager::default();
        assert_eq!(manager.count(), 0);
    }

    #[test]
    fn test_plugin_manager_load_builtin_env_expander() {
        let mut manager = PluginManager::new();
        
        manager.load_builtin("env-expander", &serde_json::json!({})).unwrap();
        
        assert_eq!(manager.count(), 1);
    }

    #[test]
    fn test_plugin_manager_load_builtin_unknown_error() {
        let mut manager = PluginManager::new();
        
        let result = manager.load_builtin("unknown-plugin", &serde_json::json!({}));
        
        assert!(result.is_err());
    }

    #[test]
    fn test_plugin_manager_transform_canon() {
        set_env("MGR_TEST", "manager_value");
        let mut manager = PluginManager::new();
        manager.load_builtin("env-expander", &serde_json::json!({})).unwrap();
        
        let mut servers = BTreeMap::new();
        servers.insert("test".to_string(), CanonServer {
            kind: None,
            command: Some("${MGR_TEST}".to_string()),
            args: None,
            env: None,
            cwd: None,
            url: None,
            headers: None,
            bearer_token_env_var: None,
            enabled: None,
        });
        let mut canon = Canon { version: Some(1), servers, plugins: vec![] };
        
        manager.transform_canon(&mut canon).unwrap();
        
        assert_eq!(canon.servers["test"].command, Some("manager_value".to_string()));
        remove_env("MGR_TEST");
    }

    #[test]
    fn test_plugin_manager_transform_output() {
        set_env("OUT_MGR", "output_mgr");
        let mut manager = PluginManager::new();
        manager.load_builtin("env-expander", &serde_json::json!({})).unwrap();
        let mut value = serde_json::json!({"key": "${OUT_MGR}"});
        
        manager.transform_output("test", &mut value).unwrap();
        
        assert_eq!(value["key"], "output_mgr");
        remove_env("OUT_MGR");
    }

    #[test]
    fn test_plugin_manager_multiple_plugins() {
        let mut manager = PluginManager::new();
        manager.load_builtin("env-expander", &serde_json::json!({})).unwrap();
        // Note: Currently only one built-in, but count should work
        
        assert_eq!(manager.count(), 1);
    }
}