XAVVA CLI 🚀

Ultra-fast development toolkit for Java Enterprise (Tomcat) on Windows, Linux & macOS

Xavva is a high-performance CLI built with Bun that transforms the Java/Tomcat development experience. It brings modern development workflows (like Node.js/Vite) to the Java Enterprise ecosystem with hot-reload, smart logging, automated deployment, and a powerful plugin system.

✨ Features

Core

• ⚡ Hot Reload — Incremental compilation and class injection without server restart
• 📊 Interactive Dashboard — Real-time TUI with system metrics and shortcuts
• 🧠 Smart Log Analyzer — Stack trace folding and root cause highlighting
• 🔒 Security Audit — Automated vulnerability scanning via OSV.dev
• 📦 Dependency Analysis — Detect conflicts and outdated dependencies
• 🎯 Maven & Gradle — Native support for both build tools
• 🔧 Auto-Healing — Automatic diagnosis and repair of common issues
• 🐱 Embedded Tomcat — Auto-install with mirror selection, checksum verification, download resume, and backup/rollback
• 📦 WAR Generation — Build as .war file or exploded directory

Developer Experience

• 🔤 Encoding Converter — Convert file encodings (UTF-8, Windows-1252, ISO-8859-1) and fix mojibake
• 🧙 Interactive Wizard — xavva init for easy project setup
• 🔔 Desktop Notifications — Get notified when builds/deploys complete
• 📜 Command History — Track and replay commands with xavva history and xavva redo
• 🏥 Health Check — Verify environment (Java, ports, memory, disk) with xavva health
• 🔧 Auto-Fix — Automatically fix common issues with xavva doctor --fix
• 🧹 Clean Command — Clean cache, build, and logs with xavva clean
• 🔮 Shell Completions — Auto-complete for bash, zsh, and fish

Advanced

• 🧪 Test Runner — Run JUnit/TestNG tests with watch mode and coverage
• 🗄️ Database Migrations — Flyway/Liquibase integration
• 🌐 HTTP Client — Test APIs without leaving the terminal
• 🐳 Docker Integration — Generate configs, build and run containers
• 🌍 Multi-Environment — Dev, test, staging configurations
• 🔌 Plugin System — Extend functionality with custom plugins
• 💻 IDE Integration — Generate configs for VS Code, IntelliJ, Eclipse
• 📊 Performance Profiler — Detailed timing with --profile
• 🛡️ Security — Input sanitization, path validation, checksum verification

📦 Installation

# Via NPM
npm install -g @archznn/xavva

# Or run directly with Bun
bunx @archznn/xavva dev

🚀 Quick Start

# Initialize project configuration (interactive wizard)
xavva init

# Start development mode with dashboard
xavva dev --tui

# Deploy to Tomcat
xavva deploy

# Build and deploy as .war file
xavva deploy --war

# Clean everything (cache, build, logs)
xavva clean

# Analyze dependencies for issues
xavva deps

# Update safe dependencies (non-breaking)
xavva deps --update-safe

# Check for security vulnerabilities
xavva audit

# Diagnose and auto-fix environment issues
xavva doctor --fix

# Convert file encoding (UTF-8 → Windows-1252)
xavva encoding convert --to cp1252 --backup src/main/java/

# Use embedded Tomcat (auto-install)
xavva dev --yes

# Check environment health
xavva health

# View command history
xavva history

# Repeat last command
xavva redo

# Run tests
xavva test
xavva test --watch
xavva test --coverage

# Database migrations
xavva db status
xavva db migrate
xavva db reset --force

# HTTP API testing
xavva http GET /api/users
xavva http POST /api/users --body '{"name":"John"}'

# Docker integration
xavva docker init
xavva docker build
xavva docker up

# Generate IDE configuration
xavva ide --ide vscode
xavva ide --ide idea
xavva ide --ide eclipse

# Multi-environment
xavva deploy --env staging
xavva dev --env dev

# Profile performance
xavva build --profile

# Dry-run (simulate without executing)
xavva deploy --dry-run

# Enable shell completions (bash example)
eval "$(xavva completion bash)"

📖 Commands

Core Development

| Command | Description | | -------------- | ------------------------------------------------------ | | xavva dev | Full development mode (build + deploy + watch + debug) | | xavva deploy | Build and deploy application to Tomcat | | xavva build | Compile project only | | xavva start | Start Tomcat server only | | xavva clean | Clean cache, build directories, and logs |

Code Execution

| Command | Description | | --------------------- | --------------------------------------------- | | xavva run <class> | Execute a Java class with automatic classpath | | xavva debug <class> | Debug a Java class (port 5005) |

Analysis & Monitoring

| Command | Description | | ---------------- | --------------------------------------------------------- | | xavva logs | Stream and analyze Tomcat logs in real-time | | xavva deps | Analyze dependencies — detect conflicts, find updates | | xavva audit | Security audit of JAR files via OSV.dev | | xavva doctor | Diagnose environment issues (JAVA_HOME, DCEVM) | | xavva profiles | List available Maven/Gradle profiles | | xavva docs | Generate endpoint documentation | | xavva tomcat | Manage embedded Tomcat installations | | xavva encoding | Convert file encodings (UTF-8, CP1252, ISO-8859-1) | | xavva health | Check environment health (Java, ports, memory, disk) |

Project Management

| Command | Description | | ----------------------- | ---------------------------------------------- | | xavva init | Initialize project configuration (wizard) | | xavva config | View current configuration | | xavva config --interactive | Edit configuration interactively | | xavva history | Show command history | | xavva history --clear | Clear command history | | xavva redo | Repeat the last executed command | | xavva completion <shell> | Generate shell completions (bash/zsh/fish) |

Testing & Database

| Command | Description | |---------|-------------| | xavva test | Run all tests (JUnit/TestNG) | | xavva test --watch | Run tests in watch mode | | xavva test --coverage | Generate coverage report | | xavva test <filter> | Run specific test class | | xavva db status | Show migration status | | xavva db migrate | Run pending migrations | | xavva db reset --force | Reset database (⚠️ destructive) | | xavva db seed | Populate with test data |

HTTP Client

| Command | Description | |---------|-------------| | xavva http GET <path> | Send GET request | | xavva http POST <path> --body '{}' | Send POST request | | xavva http <path> --param key=value | Add query parameters | | xavva http <path> --header "Auth: token" | Add custom headers |

Docker

| Command | Description | |---------|-------------| | xavva docker init | Generate Dockerfile & docker-compose.yml | | xavva docker build | Build Docker image | | xavva docker up | Start with docker-compose | | xavva docker down | Stop containers | | xavva docker run | Run development container | | xavva docker status | Show container status |

IDE Integration

| Command | Description | |---------|-------------| | xavva ide --ide vscode | Generate VS Code configuration (.vscode/) | | xavva ide --ide idea | Generate IntelliJ IDEA configuration (.idea/) | | xavva ide --ide eclipse | Generate Eclipse configuration (.project) |

Multi-Environment

| Command | Description | |---------|-------------| | xavva deploy --env <name> | Deploy to specific environment | | xavva dev --env <name> | Use environment configuration |

Configure environments in xavva.json:

{
  "environments": {
    "dev": { "port": 8080, "profile": "dev" },
    "staging": { "port": 8081, "profile": "staging" }
  }
}

🧹 Clean Command

The xavva clean command helps you clean up your project:

# Clean everything (cache, build, logs, tomcat work)
xavva clean

# Clean only cache
xavva clean --cache

# Clean only build directories (target/ build/)
xavva clean --build

# Clean only logs
xavva clean --logs

# Clean only Tomcat work directory
xavva clean --tomcat

🐱 Embedded Tomcat

Xavva can automatically download and manage a Tomcat installation for you with advanced features like automatic mirror selection, checksum verification, download resuming, and backup/rollback:

Basic Usage

# First time usage - auto-install Tomcat
xavva dev --yes

# List available versions to download
xavva tomcat list

# List already installed versions
xavva tomcat installed

# Install a specific version
xavva tomcat install 9.0.115

# Switch to a version for this project
xavva tomcat use 9.0.115

# Check Tomcat status
xavva tomcat status

# Remove a version
xavva tomcat uninstall 9.0.115

# Or use with flags
xavva dev --tomcat-version 9.0.115

Advanced Installation Features

# Install with automatic mirror selection (fastest mirror)
xavva tomcat install 10.1.52 --mirror auto

# Install with specific mirror
xavva tomcat install 10.1.52 --mirror "Apache (UK)"

# Install multiple versions in parallel
xavva tomcat install 9.0.115 10.1.52 11.0.6 --parallel

# Install without cache (force re-download)
xavva tomcat install 10.1.52 --no-cache

# Install without checksum verification
xavva tomcat install 10.1.52 --no-checksum

# Silent mode for CI/CD
xavva tomcat install 10.1.52 --silent

# Force reinstallation
xavva tomcat install 10.1.52 --force

# Configure timeout and retries
xavva tomcat install 10.1.52 --timeout 600 --retries 5

Mirror Management

# List all available mirrors
xavva tomcat mirrors list

# Test mirror speeds
xavva tomcat mirrors test

Backup and Restore

# List available backups
xavva tomcat backup list

# List backups for specific version
xavva tomcat backup list 10.1.52

# Restore from backup
xavva tomcat backup restore 10.1.52

Download Cache

# View cache statistics
xavva tomcat cache stats

# Clear download cache
xavva tomcat cache clear

Installation Features

| Feature | Description | |---------|-------------| | Mirror Selection | Automatic selection of fastest mirror (US, BR, UK, CN, etc.) | | Checksum Verification | SHA512 verification for download integrity | | Download Resume | Resume interrupted downloads from where they stopped | | Retry with Backoff | Automatic retry with exponential backoff (1s, 2s, 4s) | | Progress Display | Real-time progress with MB/s, ETA, and percentage | | Download Cache | Persistent cache shared between projects | | Backup on Update | Automatic backup before updating existing installation | | Rollback | Automatic rollback if installation fails | | Compatibility Check | Validates Tomcat version against project requirements | | Parallel Install | Install multiple versions simultaneously | | Silent Mode | CI/CD friendly mode with no interactive output |

🔤 File Encoding

The xavva encoding command helps you convert file encodings and fix mojibake (corrupted characters):

# Detect encoding of a file
xavva encoding detect src/main/java/MyClass.java

# Convert from UTF-8 to Windows-1252 (with backup)
xavva encoding convert --from utf-8 --to cp1252 --backup src/main/java/

# Convert a single file
xavva encoding convert --to cp1252 --backup src/main/java/MyClass.java

# Fix mojibake (e.g., "A��o" → "Ação")
xavva encoding fix src/main/java/MyClass.java

# List encodings of all files in src/
xavva encoding list

# Simulate conversion without modifying files
xavva encoding convert --from utf-8 --to cp1252 --dry-run src/

Supported Encodings

• utf-8 / utf8 — UTF-8 (default)
• windows-1252 / cp1252 — Windows CP1252 (ANSI)
• iso-8859-1 / latin1 — ISO-8859-1 (Latin-1)

Configuration

Set default encoding in xavva.json:

{
  "project": {
    "encoding": "cp1252"
  }
}

Then use without --to:

xavva encoding convert --backup src/main/java/

🔍 Dependency Analysis

The xavva deps command provides comprehensive dependency analysis:

# Basic analysis
xavva deps

# With verbose output for debugging
xavva deps --verbose

# Update safe dependencies only (non-breaking)
xavva deps --update-safe

# Show fix suggestions for conflicts
xavva deps --fix

# Export report as JSON
xavva deps --output report.json

# Fail on critical conflicts (useful in CI/CD)
xavva deps --strict

What it detects:

• ⚠️ Version Conflicts — Same dependency with different versions
• ⬆️ Available Updates — Newer versions in Maven Central
• 🔴 Major Updates — Breaking changes that need attention
• 📊 Statistics — Direct vs transitive dependencies

Sample output:

══════════════════════════════════════════════════════════
📊 DEPENDENCY ANALYSIS
══════════════════════════════════════════════════════════

Statistics:
  Total: 183 dependencies
  Direct: 45 | Transitivas: 138

⚠️  VERSION CONFLICTS (2)
  ✖ com.fasterxml.jackson.core:jackson-databind
     Versions: 2.13.0, 2.12.6

⬆️  UPDATES AVAILABLE (5)
  ↑ org.postgresql:postgresql
     42.2.5 → 42.7.1

⚠️  MAJOR UPDATES (1)
  ! org.springframework.boot:spring-boot-starter
     2.5.0 → 3.1.0

⚙️ Configuration

Create xavva.json in your project root:

{
  "project": {
    "appName": "my-application",
    "buildTool": "maven",
    "profile": "dev",
    "tui": false,
    "encoding": "utf-8",
    "plugins": [
      "@xavva/plugin-sass"
    ]
  },
  "tomcat": {
    "path": "/home/user/apache-tomcat",
    "port": 8080
  },
  "environments": {
    "dev": { "port": 8080, "profile": "dev" },
    "staging": { "port": 8081, "profile": "staging" }
  }
}

Note: On Windows use "path": "C:/apache-tomcat" format.

CLI Options

| Option | Description | | ---------------------- | ------------------------------- | | -p, --path <path> | Tomcat installation path | | -t, --tool <tool> | Build tool: maven or gradle | | -n, --name <name> | Application name (WAR context) | | --port <port> | Tomcat port (default: 8080) | | -P, --profile <prof> | Maven/Gradle profile | | -e, --encoding <enc> | Source encoding (utf8, cp1252) | | -w, --watch | Enable file watching | | --tui | Interactive dashboard mode | | -d, --debug | Enable JPDA debugger | | -c, --clean | Clean logs before start | | -s, --no-build | Skip initial build | | -W, --war | Generate .war file (vs exploded)| | --cache | Use build cache (faster) | | -y, --yes | Auto-install Tomcat (no prompt) | | -V, --verbose | Detailed output | | -i, --interactive | Interactive mode (for config) | | --profile | Show performance profile | | --dry-run | Simulate without executing |

🧙 Interactive Wizard

Initialize a new project with the interactive setup wizard:

xavva init

The wizard will guide you through:

• Build tool selection (auto-detected from pom.xml or build.gradle)
• Application name
• Profile selection (detects profiles from your build file)
• Tomcat port configuration
• Embedded Tomcat settings
• Build cache and TUI preferences

🏥 Health Check & Doctor

Verify your development environment:

# Check all components
xavva health

# Diagnose and show issues
xavva doctor

# Auto-fix common issues
xavva doctor --fix

Checks include:

• Java version (JDK 11+ recommended)
• Maven/Gradle availability
• Tomcat configuration
• Port availability
• Memory and disk space
• JAR file integrity
• File encoding (BOM detection)

📜 Command History

Track and replay your commands:

# Show recent commands
xavva history

# Show more entries
xavva history --limit 20

# Clear history
xavva history --clear

# Repeat last command
xavva redo

🔮 Shell Completions

Enable tab completion for your shell:

# Bash (add to ~/.bashrc)
eval "$(xavva completion bash)"

# Zsh (add to ~/.zshrc)
eval "$(xavva completion zsh)"

# Fish
xavva completion fish > ~/.config/fish/completions/xavva.fish

Supported shells: bash, zsh, fish

💻 Platform Support

Xavva works on all major platforms:

| Platform | Status | Notes | |----------|--------|-------| | Windows | ✅ Full | PowerShell for system integration | | Linux | ✅ Full | Bash/Zsh auto-configuration | | macOS | ✅ Full | Native terminal support |

Requirements

• Bun runtime (latest version)
• Java 11 or higher (JDK)
• Maven 3.6+ or Gradle 7+
• Git (optional, for version info)

🔌 Plugin System

Extend Xavva with custom plugins:

# Install a plugin
xavva plugin install @xavva/plugin-sass

# List installed plugins
xavva plugin list

Create a plugin (example: my-plugin.ts):

import type { XavvaPlugin } from "@archznn/xavva/plugins";

export default {
  name: "my-plugin",
  version: "1.0.0",
  description: "My custom plugin",
  
  hooks: {
    beforeBuild: async (context) => {
      console.log("Building...", context.config.project.appName);
    },
    afterBuild: async (context, success) => {
      console.log("Build finished:", success ? "success" : "failed");
    }
  }
} as XavvaPlugin;

Configure in xavva.json:

{
  "project": {
    "plugins": [
      "@xavva/plugin-sass",
      "./scripts/my-plugin.ts"
    ]
  }
}

🏗️ Architecture

Xavva uses a modular service-oriented architecture:

• DashboardService — TUI management and interactivity
• LogAnalyzer — Intelligent log processing
• DependencyAnalyzerService — Dependency conflict detection
• DependencyCacheService — Cache parsed dependencies
• ProjectService — Project structure discovery
• BuildService — Maven/Gradle integration
• TomcatService — Server lifecycle management
• PluginManager — Plugin loading and hook execution
• PerformanceProfiler — Performance measurement
• ErrorHandler — Contextual error messages

🤝 Contributing

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

📄 License

MIT License — see LICENSE for details.