🔧 vx-core

Core Engine for the vx Universal Tool Manager

Foundational traits, types, and utilities powering the vx ecosystem

🎯 Overview

vx-core provides the foundational traits, types, and utilities that power the vx tool management system. It defines the core abstractions for tool management, version handling, configuration, and plugin architecture. With the integration of vx-installer, it now offers state-of-the-art installation capabilities with beautiful progress tracking.

✨ Features

🔧 Core Functionality

• Tool Management: Advanced traits for tool installation, version management, and execution
• Plugin Architecture: Extensible plugin system with trait-based design for adding new tools
• Configuration Management: Unified configuration system using Figment with TOML support
• Version Handling: Semantic version parsing, comparison, and constraint resolution

🚀 Enhanced Installation System (via vx-installer)

• 🎨 Beautiful Progress Bars: Rich progress tracking with ETA and transfer rates
• 📦 Universal Format Support: ZIP, TAR.GZ, TAR.XZ, TAR.BZ2, and raw binaries
• 🔒 Security First: Built-in checksum verification and secure HTTPS downloads
• ⚡ Async Performance: Lightning-fast concurrent downloads and installations
• 🎯 Flexible Methods: Support for archives, binaries, scripts, and package managers

🛠️ Advanced Features

• Virtual Environments: Symlink-based virtual environment management with isolation
• Cross-Platform: Seamless operation on Windows, macOS, and Linux
• Error Handling: Comprehensive error types with recovery suggestions
• HTTP Utilities: Advanced HTTP client with retry logic and timeout handling

Core Traits

Tool Management

use vx_core::{Tool, ToolManager, Version};

// Define a custom tool
struct MyTool;

impl Tool for MyTool {
    fn name(&self) -> &str { "mytool" }
    fn description(&self) -> &str { "My custom tool" }
    // ... implement other required methods
}

Plugin System

use vx_core::{Plugin, PluginManager};

// Create a plugin for your tool
struct MyPlugin;

impl Plugin for MyPlugin {
    fn name(&self) -> &str { "my-plugin" }
    fn tools(&self) -> Vec<Box<dyn Tool>> {
        vec![Box::new(MyTool)]
    }
}

Configuration

use vx_core::config::{Config, ConfigManager};

// Load configuration from multiple sources
let config = ConfigManager::load()?;
let auto_install = config.auto_install.enabled;

Key Components

Version Management

• Version: Semantic version representation
• VersionManager: Version comparison and resolution
• VersionParser: Parse version strings and constraints

Tool Installation (Enhanced with vx-installer)

• InstallerAdapter: Bridge to the powerful vx-installer engine
• Universal Installation: Support for multiple archive formats and installation methods
• Progress Tracking: Beautiful progress bars with customizable styles
• Security: Checksum verification and secure download protocols
• Platform: Cross-platform path and architecture detection with smart defaults

Virtual Environments

• VirtualEnvironment: Manage isolated tool environments
• SymlinkVenv: Symlink-based virtual environment implementation

Configuration System

• Config: Global and project-specific configuration
• ConfigFigment: Figment-based configuration loading
• InstallConfigs: Tool-specific installation configurations

💡 Usage Examples

Enhanced Tool Installation with vx-installer

use vx_core::InstallerAdapter;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Create installer adapter with beautiful progress tracking
    let installer = InstallerAdapter::new().await?;

    // Install tools with automatic progress bars and checksum verification
    let node_path = installer
        .download_and_install(
            "node",
            "18.17.0",
            "https://nodejs.org/dist/v18.17.0/node-v18.17.0-linux-x64.tar.gz"
        )
        .await?;

    println!("✅ Node.js installed to: {}", node_path.display());

    // Check if a tool version is installed
    let is_installed = installer.is_version_installed("node", "18.17.0").await?;
    println!("Node.js 18.17.0 installed: {}", is_installed);

    Ok(())
}

Basic Tool Management

use vx_core::{ToolManager, GlobalToolManager};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let manager = GlobalToolManager::new()?;
    
    // Install a tool
    manager.install_tool("node", "18.17.0").await?;
    
    // List installed tools
    let tools = manager.list_installed_tools()?;
    for tool in tools {
        println!("{}: {}", tool.name, tool.version);
    }
    
    Ok(())
}

Configuration Management

use vx_core::config::ConfigManager;

let config = ConfigManager::load()?;

// Check if auto-install is enabled
if config.auto_install.enabled {
    println!("Auto-install is enabled");
}

// Get tool-specific configuration
if let Some(node_config) = config.tools.get("node") {
    println!("Node.js version: {}", node_config.version);
}

Virtual Environment

use vx_core::{VirtualEnvironment, SymlinkVenv};

let venv = SymlinkVenv::new("my-project")?;

// Add tools to the environment
venv.add_tool("node", "18.17.0")?;
venv.add_tool("uv", "latest")?;

// Activate the environment
venv.activate()?;

Configuration

vx-core uses a hierarchical configuration system:

1. Global Config: ~/.vx/config/global.toml
2. Project Config: .vx.toml in project root
3. Environment Variables: VX_* prefixed variables

Example Configuration

[auto_install]
enabled = true
timeout = 300

[tools]
node = "18.17.0"
uv = "latest"

[settings]
cache_duration = "7d"
parallel_downloads = 4

Error Handling

vx-core uses anyhow::Result for error handling:

use vx_core::error::VxError;

fn example() -> anyhow::Result<()> {
    // Operations that might fail
    let tool = manager.find_tool("nonexistent")?;
    Ok(())
}

Platform Support

• Windows: Full support with proper path handling
• macOS: Native support for both Intel and Apple Silicon
• Linux: Support for major distributions

📦 Dependencies

Core Dependencies

• vx-installer: Universal installation engine with progress tracking
• vx-config: Configuration management system
• vx-plugin: Plugin system and trait definitions
• serde: Serialization and deserialization
• tokio: Async runtime for high-performance operations
• anyhow: Comprehensive error handling

Installation & HTTP

• reqwest: HTTP client for downloads
• figment: Advanced configuration management
• dirs: Platform-specific directory handling
• walkdir: Directory traversal utilities

Development Dependencies

• tempfile: Temporary file handling for tests
• tokio-test: Async testing utilities

Development

Building

cargo build

Testing

cargo test

Documentation

cargo doc --open

Integration

vx-core is designed to be used by:

• vx-cli: Command-line interface
• Tool Plugins: Individual tool implementations
• Package Manager Plugins: Package manager integrations
• External Applications: Third-party integrations

License

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

Contributing

Contributions are welcome! Please see the contributing guidelines for more information.

🔗 Related Crates

• vx-installer - 🆕 Universal installation engine with progress tracking
• vx-cli - Command-line interface with rich UX
• vx-config - Configuration management system
• vx-plugin - Plugin system and trait definitions
• vx-tool-node - Node.js tool plugin
• vx-tool-uv - UV Python tool plugin
• vx-pm-npm - NPM package manager plugin

Built with ❤️ for the vx ecosystem

📖 Documentation | 🚀 Main Project | 🤝 Contributing