vtcode_core/skills/

cli_bridge.rs

//! CLI Tool Bridge for External Tool Integration
//!
//! Bridges external CLI tools to VT Code's skill system, enabling integration
//! of any command-line tool with proper documentation into the agent harness.
//!
//! ## Features
//!
//! - **Progressive Disclosure**: Load tool documentation only when needed
//! - **JSON I/O**: Structured input/output via JSON when available
//! - **Fallback Support**: Graceful degradation to text output
//! - **Validation**: Schema-based validation for tool arguments
//! - **Streaming**: Support for long-running operations
//!
//! ## Tool Discovery
//!
//! Tools are discovered by scanning for:
//! - Executable files with accompanying README.md
//! - tool.json metadata files
//! - Standard installation paths (/usr/local/bin, ~/.local/bin, etc.)

use crate::skills::types::{Skill, SkillManifest, SkillResource};
use crate::tool_policy::ToolPolicy;
use crate::tools::traits::Tool;
use crate::utils::async_utils;
use crate::utils::file_utils::{read_file_with_context_sync, read_json_file_sync};
use anyhow::{Result, anyhow};
use async_trait::async_trait;
use serde::{Deserialize, Serialize};
use serde_json::Value;
use std::path::{Path, PathBuf};
use std::process::Stdio;
use std::time::Duration;
use tokio::process::Command;
use tracing::{debug, info, warn};

/// Configuration for a CLI tool skill
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CliToolConfig {
    /// Tool name (must be unique)
    pub name: String,

    /// Brief description
    pub description: String,

    /// Path to the executable
    pub executable_path: PathBuf,

    /// Path to README/documentation
    pub readme_path: Option<PathBuf>,

    /// Path to JSON schema for arguments
    pub schema_path: Option<PathBuf>,

    /// Timeout for execution (seconds)
    pub timeout_seconds: Option<u64>,

    /// Whether tool supports JSON I/O
    pub supports_json: bool,

    /// Environment variables to set
    pub environment: Option<hashbrown::HashMap<String, String>>,

    /// Working directory for execution
    pub working_dir: Option<PathBuf>,
}

/// Tool execution result
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CliToolResult {
    /// Exit code
    pub exit_code: i32,

    /// Standard output
    pub stdout: String,

    /// Standard error
    pub stderr: String,

    /// Parsed JSON output (if available)
    pub json_output: Option<Value>,

    /// Execution time in milliseconds
    pub execution_time_ms: u64,
}

/// Bridge between CLI tools and VT Code skills
#[derive(Debug, Clone)]
pub struct CliToolBridge {
    pub config: CliToolConfig,
    instructions: String,
    schema: Option<Value>,
}

impl CliToolBridge {
    /// Create a new CLI tool bridge from configuration
    pub fn new(config: CliToolConfig) -> Result<Self> {
        let instructions = Self::load_readme(&config)?;
        let schema = Self::load_schema(&config)?;

        Ok(CliToolBridge { config, instructions, schema })
    }

    /// Create a bridge from a tool directory
    pub fn from_directory(tool_dir: &Path) -> Result<Self> {
        let config_path = tool_dir.join("tool.json");
        let config: CliToolConfig = if config_path.exists() {
            read_json_file_sync(&config_path)?
        } else {
            // Auto-discover tool configuration
            Self::auto_discover_config(tool_dir)?
        };

        Self::new(config)
    }

    /// Auto-discover tool configuration from directory
    fn auto_discover_config(tool_dir: &Path) -> Result<CliToolConfig> {
        // Look for executable files
        let executables = Self::find_executables(tool_dir)?;
        if executables.is_empty() {
            return Err(anyhow!("No executable files found in {}", tool_dir.display()));
        }

        // Look for README files
        let readme_files = Self::find_readmes(tool_dir)?;

        // Use first executable and README (if found)
        let executable_path = executables[0].clone();
        let readme_path = readme_files.first().cloned();

        // Try to determine tool name from executable
        let name = executable_path
            .file_stem()
            .and_then(|s| s.to_str())
            .ok_or_else(|| anyhow!("Invalid executable filename"))?
            .to_string();

        Ok(CliToolConfig {
            name: name.clone(),
            description: format!("CLI tool: {name}"),
            executable_path,
            readme_path,
            schema_path: None,
            timeout_seconds: Some(30),
            supports_json: false, // Will be tested during execution
            environment: None,
            working_dir: Some(tool_dir.to_path_buf()),
        })
    }

    /// Find executable files in directory
    fn find_executables(dir: &Path) -> Result<Vec<PathBuf>> {
        let mut executables = vec![];

        for entry in std::fs::read_dir(dir)? {
            let entry = entry?;
            let path = entry.path();

            if path.is_file() {
                #[cfg(unix)]
                {
                    use std::os::unix::fs::PermissionsExt;
                    let metadata = entry.metadata()?;
                    let permissions = metadata.permissions();
                    if permissions.mode() & 0o111 != 0 {
                        executables.push(path);
                    }
                }

                #[cfg(windows)]
                {
                    if let Some(ext) = path.extension() {
                        if ext == "exe" || ext == "bat" || ext == "cmd" {
                            executables.push(path);
                        }
                    }
                }
            }
        }

        Ok(executables)
    }

    /// Find README files in directory
    fn find_readmes(dir: &Path) -> Result<Vec<PathBuf>> {
        let mut readmes = vec![];

        for entry in std::fs::read_dir(dir)? {
            let entry = entry?;
            let path = entry.path();

            if let Some(_name) = path
                .file_name()
                .and_then(|n| n.to_str())
                .filter(|n| path.is_file() && n.to_lowercase().starts_with("readme") && n.ends_with(".md"))
            {
                readmes.push(path);
            }
        }

        Ok(readmes)
    }

    /// Load README/documentation content
    fn load_readme(config: &CliToolConfig) -> Result<String> {
        if let Some(readme_path) = config.readme_path.as_ref().filter(|p| p.exists()) {
            return read_file_with_context_sync(readme_path, "README file");
        }

        // Generate basic instructions if no README
        Ok(format!(
            "# {}\n\nCLI tool: {}\n\nExecute with provided arguments.\n",
            config.name,
            config.executable_path.display()
        ))
    }

    /// Load JSON schema for validation
    fn load_schema(config: &CliToolConfig) -> Result<Option<Value>> {
        if let Some(schema_path) = config.schema_path.as_ref().filter(|p| p.exists()) {
            return Ok(Some(read_json_file_sync(schema_path)?));
        }

        Ok(None)
    }

    /// Execute the CLI tool with given arguments
    pub async fn execute_internal(&self, args: Value) -> Result<CliToolResult> {
        info!("Executing CLI tool: {} with args: {:?}", self.config.name, args);

        let start_time = std::time::Instant::now();

        // Validate arguments against schema if available
        if let Some(schema) = &self.schema {
            self.validate_args(&args, schema)?;
        }

        // Build command
        let mut cmd = Command::new(&self.config.executable_path);

        // Set working directory
        if let Some(working_dir) = &self.config.working_dir {
            cmd.current_dir(working_dir);
        }

        // Set environment variables
        if let Some(env) = &self.config.environment {
            for (key, value) in env {
                cmd.env(key, value);
            }
        }

        // Configure I/O
        cmd.stdin(Stdio::piped()).stdout(Stdio::piped()).stderr(Stdio::piped());

        // Add arguments based on configuration and input
        self.configure_arguments(&mut cmd, &args)?;

        // Execute with timeout
        let timeout_duration = Duration::from_secs(self.config.timeout_seconds.unwrap_or(30));
        let output_result = async_utils::with_timeout(cmd.output(), timeout_duration, "CLI tool execution").await??;

        let execution_time_ms = start_time.elapsed().as_millis() as u64;

        // Parse output
        let stdout = String::from_utf8_lossy(&output_result.stdout).into_owned();
        let stderr = String::from_utf8_lossy(&output_result.stderr).into_owned();

        // Try to parse JSON output if supported
        let json_output = if self.config.supports_json {
            serde_json::from_str(&stdout).ok()
        } else {
            None
        };

        Ok(CliToolResult {
            exit_code: output_result.status.code().unwrap_or(-1),
            stdout,
            stderr,
            json_output,
            execution_time_ms,
        })
    }

    /// Configure command arguments based on input
    fn configure_arguments(&self, cmd: &mut Command, args: &Value) -> Result<()> {
        if args.is_null() || args == &Value::Null {
            return Ok(());
        }

        // Handle different argument formats
        match args {
            Value::String(s) => {
                // Single string argument
                cmd.arg(s);
            }
            Value::Array(arr) => {
                // Array of arguments
                for arg in arr {
                    if let Some(s) = arg.as_str() {
                        cmd.arg(s);
                    }
                }
            }
            Value::Object(map) => {
                // Named arguments - convert to command-line flags
                for (key, value) in map {
                    if let Some(s) = value.as_str() {
                        cmd.arg(format!("--{key}"));
                        cmd.arg(s);
                    } else if value.as_bool().is_some_and(|flag| flag) {
                        cmd.arg(format!("--{key}"));
                    }
                }
            }
            _ => {
                // Fallback: serialize to JSON and pass as single argument
                let json_str = serde_json::to_string(args)?;
                cmd.arg(json_str);
            }
        }

        Ok(())
    }

    /// Validate arguments against JSON schema
    fn validate_args(&self, args: &Value, schema: &Value) -> Result<()> {
        // Basic validation - in production, use jsonschema crate
        debug!("Validating args against schema: {:?}", schema);

        // For now, just check required fields
        if let Some(required) = schema.get("required").and_then(|v| v.as_array()) {
            for field in required {
                if let Some(field_name) = field.as_str().filter(|f| args.get(*f).is_none()) {
                    return Err(anyhow!("Missing required field: {field_name}"));
                }
            }
        }

        Ok(())
    }

    /// Test if tool supports JSON I/O
    pub async fn test_json_support(&self) -> Result<bool> {
        debug!("Testing JSON support for tool: {}", self.config.name);

        // Try to execute with --help-json or similar flag
        let mut cmd = Command::new(&self.config.executable_path);
        cmd.arg("--help-json").stdout(Stdio::piped()).stderr(Stdio::piped());

        let result = cmd.output().await;

        match result {
            Ok(output) => {
                let stdout = String::from_utf8_lossy(&output.stdout);
                // Check if output is valid JSON
                Ok(serde_json::from_str::<Value>(&stdout).is_ok())
            }
            Err(_) => Ok(false),
        }
    }

    /// Convert to VT Code Skill
    pub fn to_skill(&self) -> Result<Skill> {
        let manifest = SkillManifest {
            name: self.config.name.clone(),
            description: self.config.description.clone(),
            version: Some("1.0.0".to_string()),
            author: Some("VT Code CLI Bridge".to_string()),
            variety: crate::skills::types::SkillVariety::SystemUtility,
            ..Default::default()
        };

        let mut skill = Skill::new(
            manifest,
            self.config
                .executable_path
                .parent()
                .unwrap_or_else(|| Path::new("."))
                .to_path_buf(),
            self.instructions.clone(),
        )?;

        // Add schema as resource if available
        if let Some(schema) = &self.schema {
            skill.add_resource(
                "schema.json".to_string(),
                SkillResource {
                    path: "schema.json".to_string(),
                    resource_type: crate::skills::types::ResourceType::Reference,
                    content: Some(schema.to_string().into_bytes()),
                },
            );
        }

        Ok(skill)
    }
}

#[async_trait]
impl Tool for CliToolBridge {
    fn name(&self) -> &str {
        &self.config.name
    }

    fn description(&self) -> &str {
        &self.config.description
    }

    fn parameter_schema(&self) -> Option<Value> {
        self.schema.clone()
    }

    fn default_permission(&self) -> ToolPolicy {
        ToolPolicy::Prompt
    }

    async fn execute(&self, args: Value) -> Result<Value> {
        let result = self.execute_internal(args).await?;
        Ok(serde_json::to_value(result)?)
    }
}

/// Discover CLI tools in project-local locations.
///
/// Only project-scoped directories are scanned (`~/.local/bin`, `./tools`,
/// `./vendor/tools`). System directories such as `/usr/bin` and
/// `/usr/local/bin` are intentionally excluded: treating every system
/// executable as a skill pollutes the catalog with hundreds of unrelated
/// binaries (`kubectl`, `binhex`, versioned `python3.12`/`python3.15` pairs
/// that collapse to the same `file_stem` name), slows startup, and exposes
/// system binaries as model-invocable skills.
pub fn discover_cli_tools() -> Result<Vec<CliToolConfig>> {
    let mut tools = vec![];

    // Project-local locations to search (no system directories).
    let search_paths = vec![
        PathBuf::from("~/.local/bin").expand_home()?,
        PathBuf::from("./tools"),
        PathBuf::from("./vendor/tools"),
    ];

    for path in search_paths {
        if path.exists() && path.is_dir() {
            match discover_tools_in_directory(&path) {
                Ok(dir_tools) => tools.extend(dir_tools),
                Err(e) => warn!("Failed to discover tools in {}: {}", path.display(), e),
            }
        }
    }

    debug!("Discovered {} CLI tools", tools.len());
    Ok(tools)
}

/// Build a CLI tool config from an executable path.
///
/// This is the single shared predicate for "is this binary a skill": the
/// path must be an executable file shipping with explicit per-tool metadata
/// (`<stem>.md`, `<stem>.json`, or a sibling `tool.json`). Bare binaries
/// without docs return `None` so system executables never pollute the skill
/// catalog. Both directory scanners delegate here so the rule cannot drift.
pub(crate) fn cli_tool_config_from_executable(dir: &Path, path: &Path) -> Option<CliToolConfig> {
    if !path.is_file() {
        return None;
    }
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        let Ok(metadata) = path.metadata() else {
            return None;
        };
        if metadata.permissions().mode() & 0o111 == 0 {
            return None;
        }
    }
    #[cfg(windows)]
    {
        match path.extension().and_then(|ext| ext.to_str()) {
            Some(ext) if matches!(ext.to_lowercase().as_str(), "exe" | "bat" | "cmd") => {}
            _ => return None,
        }
    }

    let stem = path.file_stem().and_then(|stem| stem.to_str())?;
    let readme_path = dir.join(format!("{stem}.md"));
    let schema_path = dir.join(format!("{stem}.json"));
    let tool_json_path = dir.join("tool.json");
    if !readme_path.exists() && !schema_path.exists() && !tool_json_path.exists() {
        return None;
    }

    Some(CliToolConfig {
        name: stem.to_string(),
        description: format!("CLI tool: {}", path.display()),
        executable_path: path.to_path_buf(),
        readme_path: readme_path.exists().then(|| readme_path.clone()),
        schema_path: if schema_path.exists() {
            Some(schema_path)
        } else if tool_json_path.exists() {
            Some(tool_json_path)
        } else {
            None
        },
        timeout_seconds: Some(30),
        supports_json: false,
        environment: None,
        working_dir: Some(dir.to_path_buf()),
    })
}

/// Discover tools in a specific directory
fn discover_tools_in_directory(dir: &Path) -> Result<Vec<CliToolConfig>> {
    let mut tools = vec![];

    for entry in std::fs::read_dir(dir)? {
        let entry = entry?;
        let path = entry.path();

        if let Some(config) = cli_tool_config_from_executable(dir, &path) {
            tools.push(config);
        }
    }

    Ok(tools)
}

/// Extension trait for PathBuf to expand home directory
trait PathExt {
    fn expand_home(&self) -> Result<PathBuf>;
}

impl PathExt for PathBuf {
    fn expand_home(&self) -> Result<PathBuf> {
        if let Some(home) = std::env::var("HOME").ok().filter(|_| self.starts_with("~")) {
            let stripped = self.strip_prefix("~").unwrap_or(self);
            return Ok(PathBuf::from(home).join(stripped));
        }
        Ok(self.clone())
    }
}

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

    #[test]
    fn test_cli_tool_config_creation() {
        let config = CliToolConfig {
            name: "test-tool".to_string(),
            description: "Test tool".to_string(),
            executable_path: PathBuf::from("/bin/echo"),
            readme_path: None,
            schema_path: None,
            timeout_seconds: Some(10),
            supports_json: false,
            environment: None,
            working_dir: None,
        };

        assert_eq!(config.name, "test-tool");
        assert_eq!(config.timeout_seconds, Some(10));
    }

    #[tokio::test]
    async fn test_simple_tool_execution() {
        let config = CliToolConfig {
            name: "echo".to_string(),
            description: "Echo command".to_string(),
            executable_path: PathBuf::from("/bin/echo"),
            readme_path: None,
            schema_path: None,
            timeout_seconds: Some(5),
            supports_json: false,
            environment: None,
            working_dir: None,
        };

        let bridge = CliToolBridge::new(config).unwrap();
        let result = bridge.execute_internal(Value::String("hello world".to_string())).await.unwrap();

        assert_eq!(result.exit_code, 0);
        assert!(result.stdout.contains("hello world"));
    }

    #[cfg(unix)]
    fn write_executable(dir: &Path, name: &str) -> PathBuf {
        use std::os::unix::fs::PermissionsExt;
        let path = dir.join(name);
        std::fs::write(&path, "#!/bin/sh\necho hi\n").expect("write executable");
        let mut perms = std::fs::metadata(&path).expect("metadata").permissions();
        perms.set_mode(0o755);
        std::fs::set_permissions(&path, perms).expect("chmod");
        path
    }

    #[cfg(unix)]
    #[test]
    fn bare_executables_without_docs_are_not_skills() {
        let temp = TempDir::new().expect("tempdir");
        write_executable(temp.path(), "bare-tool");
        // Versioned system-style binaries without docs must not collide either.
        write_executable(temp.path(), "python3.12");
        write_executable(temp.path(), "python3.15");

        let tools = discover_tools_in_directory(temp.path()).expect("discover tools");
        assert!(
            tools.is_empty(),
            "bare executables without <stem>.md/.json or tool.json must be skipped, got {:?}",
            tools.iter().map(|t| &t.name).collect::<Vec<_>>()
        );
    }

    #[cfg(unix)]
    #[test]
    fn documented_executables_are_discovered_as_skills() {
        let temp = TempDir::new().expect("tempdir");
        write_executable(temp.path(), "doc-tool");
        std::fs::write(temp.path().join("doc-tool.md"), "# doc-tool\n").expect("write readme");
        write_executable(temp.path(), "schema-tool");
        std::fs::write(temp.path().join("schema-tool.json"), "{}").expect("write schema");

        let tools = discover_tools_in_directory(temp.path()).expect("discover tools");
        let names: Vec<&str> = tools.iter().map(|t| t.name.as_str()).collect();
        assert!(names.contains(&"doc-tool"), "expected doc-tool, got {names:?}");
        assert!(names.contains(&"schema-tool"), "expected schema-tool, got {names:?}");
        assert_eq!(tools.len(), 2, "only documented tools should load, got {names:?}");
    }

    #[cfg(unix)]
    #[test]
    fn non_executable_with_docs_is_skipped() {
        let temp = TempDir::new().expect("tempdir");
        let script = temp.path().join("not-executable");
        std::fs::write(&script, "#!/bin/sh\necho hi\n").expect("write script");
        #[cfg(unix)]
        {
            use std::os::unix::fs::PermissionsExt;
            let mut perms = std::fs::metadata(&script).expect("metadata").permissions();
            perms.set_mode(0o644);
            std::fs::set_permissions(&script, perms).expect("chmod");
        }
        std::fs::write(temp.path().join("not-executable.md"), "# docs\n").expect("write readme");

        let tools = discover_tools_in_directory(temp.path()).expect("discover tools");
        assert!(
            tools.is_empty(),
            "non-executable files must be skipped even with docs, got {:?}",
            tools.iter().map(|t| &t.name).collect::<Vec<_>>()
        );
    }

    #[cfg(unix)]
    #[test]
    fn sibling_tool_json_counts_as_docs() {
        let temp = TempDir::new().expect("tempdir");
        write_executable(temp.path(), "json-tool");
        std::fs::write(temp.path().join("tool.json"), "{}").expect("write tool.json");

        let tools = discover_tools_in_directory(temp.path()).expect("discover tools");
        assert_eq!(tools.len(), 1, "sibling tool.json should qualify the executable");
        assert_eq!(tools[0].name, "json-tool");
    }
}