vx-tool-node 0.2.2

# vx-tool-node


[![Crates.io](https://img.shields.io/crates/v/vx-tool-node.svg)](https://crates.io/crates/vx-tool-node)
[![Documentation](https://docs.rs/vx-tool-node/badge.svg)](https://docs.rs/vx-tool-node)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Node.js tool support for the vx universal tool manager.

## Overview


`vx-tool-node` provides Node.js runtime support for vx, enabling automatic installation, version management, and execution of Node.js and npm commands through the vx interface.

## Features


- **Node.js Runtime**: Full Node.js runtime support with version management
- **NPM Integration**: Built-in npm package manager support
- **NPX Support**: Package runner functionality for one-time tool execution
- **Auto-Installation**: Automatic download and installation of Node.js versions
- **Cross-Platform**: Windows, macOS, and Linux support
- **Version Management**: Install and switch between multiple Node.js versions
- **LTS Support**: Automatic detection and installation of LTS versions

## Supported Commands


### Node.js Runtime

```bash
# Execute Node.js scripts

vx node script.js
vx node --version
vx node -e "console.log('Hello, World!')"

# Interactive REPL

vx node
```

### NPM Package Manager

```bash
# Package management

vx npm install express
vx npm install -g typescript
vx npm uninstall lodash
vx npm update

# Project management

vx npm init
vx npm run dev
vx npm test
vx npm publish

# Information commands

vx npm list
vx npm outdated
vx npm audit
```

### NPX Package Runner

```bash
# Run packages without installing

vx npx create-react-app my-app
vx npx typescript --init
vx npx cowsay "Hello from vx!"

# Run specific versions

vx npx typescript@4.9.5 --version
vx npx -p typescript@latest tsc --version
```

## Installation


### Through vx CLI

```bash
# Install latest LTS version

vx install node

# Install specific version

vx install node@18.17.0
vx install node@20.10.0

# Install latest version

vx install node@latest
```

### Version Constraints

```bash
# Semantic version ranges

vx install node@^18.0.0    # Latest 18.x.x
vx install node@~18.17.0   # Latest 18.17.x
vx install node@>=18.0.0   # 18.0.0 or higher
```

## Configuration


### Project Configuration (.vx.toml)

```toml
[tools]
node = "18.17.0"          # Specific version
# node = "lts"            # Latest LTS

# node = "latest"         # Latest stable

# node = "^18.0.0"        # Version range


[tools.node]
auto_install = true
install_npm = true        # Install npm alongside Node.js
```

### Global Configuration

```toml
[tools.node]
default_version = "lts"
auto_install = true
install_timeout = 300
prefer_lts = true

[node.npm]
registry = "https://registry.npmjs.org/"
cache_dir = "~/.npm"
```

## Version Management


### Available Versions

The plugin supports all official Node.js releases:

- **LTS Versions**: 18.x, 20.x (recommended for production)
- **Current Versions**: Latest stable releases
- **Legacy Versions**: 16.x and older (limited support)

### Version Detection

```bash
# List available versions

vx list node

# Show current version

vx node --version

# Show installation path

vx which node
```

## Platform Support


### Windows

- **x64**: Full support
- **x86**: Legacy support
- **ARM64**: Windows 11 ARM support

### macOS

- **x64**: Intel Mac support
- **ARM64**: Apple Silicon (M1/M2) support
- **Universal**: Automatic architecture detection

### Linux

- **x64**: All major distributions
- **ARM64**: ARM-based systems
- **ARMv7**: Raspberry Pi and similar

## Integration


### With vx-core

```rust
use vx_core::{Tool, ToolManager};
use vx_tool_node::NodeTool;

let node_tool = NodeTool::new();
let manager = ToolManager::new();

// Install Node.js
manager.install_tool(&node_tool, "18.17.0").await?;

// Execute Node.js
manager.execute_tool(&node_tool, &["--version"]).await?;
```

### Plugin Registration

```rust
use vx_core::{Plugin, PluginManager};
use vx_tool_node::NodePlugin;

let plugin = NodePlugin::new();
let mut manager = PluginManager::new();

manager.register_plugin(Box::new(plugin))?;
```

## Development


### Building

```bash
cd crates/vx-tool-node
cargo build
```

### Testing

```bash
cargo test
```

### Integration Testing

```bash
# Test with actual Node.js installation

cargo test --features integration-tests
```

## Implementation Details


### Tool Structure

- **NodeTool**: Main Node.js runtime tool
- **NpmTool**: NPM package manager integration
- **NpxTool**: NPX package runner support

### Version Resolution

1. **Project Config**: Check `.vx.toml` for version specification
2. **Global Config**: Fall back to global default
3. **LTS Detection**: Use latest LTS if no version specified
4. **Auto-Install**: Download and install if not available

### Installation Process

1. **Version Lookup**: Query Node.js release API
2. **Download**: Fetch appropriate binary/installer
3. **Extraction**: Extract to vx tools directory
4. **Verification**: Verify installation integrity
5. **NPM Setup**: Configure npm if included

## Error Handling


### Common Errors

- **Network Issues**: Download failures, API timeouts
- **Permission Errors**: Installation directory access
- **Version Conflicts**: Multiple Node.js installations
- **Corruption**: Incomplete or corrupted downloads

### Recovery

```bash
# Reinstall corrupted version

vx install node@18.17.0 --force

# Clear cache and retry

vx cleanup --cache-only
vx install node@18.17.0

# Use system Node.js as fallback

vx --use-system-path node --version
```

## Performance


- **Fast Downloads**: Parallel downloading with progress tracking
- **Efficient Storage**: Shared installations across virtual environments
- **Quick Execution**: Minimal overhead for tool execution
- **Smart Caching**: Version metadata and download caching

## Security


- **Checksum Verification**: SHA256 verification of downloads
- **HTTPS Only**: Secure downloads from official sources
- **Signature Validation**: GPG signature verification (when available)
- **Sandboxed Execution**: Isolated execution environments

## Troubleshooting


### Installation Issues

```bash
# Check available versions

vx search node

# Verify network connectivity

curl -I https://nodejs.org/dist/

# Check disk space

vx stats

# Force reinstall

vx remove node@18.17.0
vx install node@18.17.0
```

### Runtime Issues

```bash
# Check Node.js installation

vx node --version
vx npm --version

# Verify PATH configuration

vx which node
vx which npm

# Test with system Node.js

vx --use-system-path node --version
```

## License


This project is licensed under the MIT License - see the [LICENSE](../../../LICENSE) file for details.

## Contributing


Contributions are welcome! Please see the [contributing guidelines](../../../CONTRIBUTING.md) for more information.

## Related Crates


- [`vx-core`](../../vx-core/README.md) - Core functionality
- [`vx-cli`](../../vx-cli/README.md) - Command-line interface
- [`vx-pm-npm`](../../vx-package-managers/vx-pm-npm/README.md) - NPM package manager
- [`vx-tool-uv`](../vx-tool-uv/README.md) - UV Python tool