vx-tool-standard

Standard tool runtime interface and utilities for vx tool management.

English | 中文

Overview

vx-tool-standard provides a standardized interface and utilities for implementing tool runtimes in the vx ecosystem. It defines common patterns, traits, and helper functions that tool implementations can use to ensure consistency and interoperability.

Features

• Standard Tool Runtime Interface: Common traits for tool runtime operations
• Platform Abstraction: Cross-platform tool execution and management
• Configuration Management: Standardized tool configuration handling
• Error Handling: Consistent error types and handling patterns
• Utility Functions: Common operations for tool implementations
• Testing Utilities: Helper functions for testing tool implementations

Installation

Add this to your Cargo.toml:

[dependencies]
vx-tool-standard = "0.2.6"

Usage

Implementing a Tool Runtime

use vx_tool_standard::{ToolRuntime, VxResult, Platform};
use async_trait::async_trait;

struct MyToolRuntime {
    name: String,
    version: Option<String>,
}

#[async_trait]
impl ToolRuntime for MyToolRuntime {
    async fn is_available(&self) -> VxResult<bool> {
        // Check if tool is available on the system
        Ok(which::which(&self.name).is_ok())
    }

    async fn get_version(&self) -> VxResult<Option<String>> {
        // Get installed version
        Ok(self.version.clone())
    }

    async fn get_path(&self) -> VxResult<Option<PathBuf>> {
        // Get tool executable path
        which::which(&self.name)
            .map(Some)
            .map_err(|e| e.into())
    }

    async fn execute(&self, args: &[String]) -> VxResult<i32> {
        // Execute tool with arguments
        let status = std::process::Command::new(&self.name)
            .args(args)
            .status()?;
        
        Ok(status.code().unwrap_or(1))
    }
}

Using Standard Configurations

use vx_tool_standard::{StandardConfig, Platform};

let config = StandardConfig::builder()
    .name("my-tool")
    .version("1.0.0")
    .description("My awesome tool")
    .for_platforms(vec![Platform::Windows, Platform::Linux, Platform::MacOS])
    .build();

println!("Tool: {} v{}", config.name(), config.version());

Platform-Specific Operations

use vx_tool_standard::Platform;

let current_platform = Platform::current();

match current_platform {
    Platform::Windows => {
        // Windows-specific logic
        println!("Running on Windows");
    }
    Platform::Linux => {
        // Linux-specific logic
        println!("Running on Linux");
    }
    Platform::MacOS => {
        // macOS-specific logic
        println!("Running on macOS");
    }
    Platform::Unknown => {
        println!("Unknown platform");
    }
}

Error Handling

use vx_tool_standard::{VxResult, VxError};

fn tool_operation() -> VxResult<String> {
    // Operation that might fail
    if some_condition {
        Ok("Success".to_string())
    } else {
        Err(VxError::ToolNotFound("my-tool".to_string()))
    }
}

match tool_operation() {
    Ok(result) => println!("Success: {}", result),
    Err(VxError::ToolNotFound(tool)) => {
        eprintln!("Tool not found: {}", tool);
    }
    Err(e) => eprintln!("Error: {}", e),
}

Architecture

Core Traits

• ToolRuntime: Main interface for tool runtime operations
• Configurable: Interface for tools with configuration
• Executable: Interface for executable tools
• Versionable: Interface for tools with version information

Utility Types

• Platform: Platform detection and abstraction
• StandardConfig: Standard configuration structure
• VxResult: Standard result type with error handling
• VxError: Standard error types for tool operations

Advanced Usage

Custom Tool Configuration

use vx_tool_standard::{StandardConfig, Configurable};
use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
struct MyToolConfig {
    #[serde(flatten)]
    standard: StandardConfig,
    custom_option: String,
    debug_mode: bool,
}

impl Configurable for MyToolConfig {
    type Config = Self;
    
    fn config(&self) -> &Self::Config {
        self
    }
}

Testing Utilities

use vx_tool_standard::testing::{MockToolRuntime, TestEnvironment};

#[tokio::test]
async fn test_tool_runtime() {
    let mut mock = MockToolRuntime::new("test-tool");
    mock.expect_is_available().returning(|| Ok(true));
    mock.expect_get_version().returning(|| Ok(Some("1.0.0".to_string())));
    
    assert!(mock.is_available().await.unwrap());
    assert_eq!(mock.get_version().await.unwrap(), Some("1.0.0".to_string()));
}

#[test]
fn test_with_environment() {
    let env = TestEnvironment::new()
        .with_tool("node", "18.17.0")
        .with_tool("npm", "9.6.7");
    
    env.run(|| {
        // Test code that depends on tools being available
        assert!(which::which("node").is_ok());
        assert!(which::which("npm").is_ok());
    });
}

Integration with vx Ecosystem

Plugin Integration

use vx_tool_standard::{ToolRuntime, StandardConfig};
use vx_plugin::VxTool;

struct StandardTool {
    config: StandardConfig,
    runtime: Box<dyn ToolRuntime>,
}

impl VxTool for StandardTool {
    fn name(&self) -> &str {
        self.config.name()
    }
    
    fn description(&self) -> &str {
        self.config.description()
    }
    
    // Implement other VxTool methods using runtime
}

Configuration Integration

use vx_tool_standard::StandardConfig;
use vx_config::VxConfig;

let vx_config = VxConfig::load()?;
let tool_config = StandardConfig::from_vx_config(&vx_config, "my-tool")?;

Examples

Check the examples/ directory for complete examples:

• basic_tool.rs - Basic tool runtime implementation
• configurable_tool.rs - Tool with custom configuration
• platform_specific.rs - Platform-specific tool behavior
• testing_example.rs - Testing tool implementations

Testing

cargo test

Run with logging:

RUST_LOG=vx_tool_standard=debug cargo test

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.