vineguard/README.md

VineGuard - Complete AI-powered testing orchestration system for intelligent test execution, debugging, and analysis

# VineGuard CLI - Command Line Testing Orchestration Tool 🖥️

[![npm version](https://badge.fury.io/js/vineguard.svg)](https://www.npmjs.com/package/vineguard)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org/)

> **The complete command-line interface for AI-powered testing automation**

VineGuard CLI is your command-line testing orchestration system that handles the entire workflow from requirements analysis to automated fixes. Perfect for **CI/CD pipelines**, **terminal workflows**, and **automated testing operations**.

## 🎯 What is VineGuard CLI?

**VineGuard CLI** is the command-line interface for VineGuard's AI testing capabilities. It's designed for:

- ✅ **CI/CD Integration**: Automated testing in build pipelines
- ✅ **Terminal Workflows**: Command-line driven development
- ✅ **Batch Operations**: Process multiple projects efficiently
- ✅ **Scripting**: Integrate VineGuard into custom automation scripts

> **Looking for IDE integration?** Check out [VineGuard MCP](https://www.npmjs.com/package/vineguard-mcp) for Claude Code, Cursor, and VS Code integration.

## 🚀 Quick Start

### Installation

```bash
# Install globally for CLI usage
npm install -g vineguard

# Or install locally in your project
npm install vineguard
```

### Basic Usage

```bash
# Start VineGuard with all features
vineguard start

# Run tests with AI analysis
vineguard test

# Analyze your project
vineguard analyze

# Generate comprehensive test suite
vineguard generate tests

# Fix bugs automatically
vineguard fix

# Check system health
vineguard health
```

## 📋 CLI Commands Reference

### Core Commands

```bash
# Server Management
vineguard start              # Start full orchestration server
vineguard mcp-server        # Start MCP server for IDE integration
vineguard standalone        # Start standalone server (fallback)

# Testing Operations
vineguard test              # Run all tests with AI analysis
vineguard test src/         # Run tests for specific directory
vineguard test auth.spec.js # Run specific test file

# Project Analysis
vineguard analyze           # Analyze current project
vineguard analyze /path     # Analyze specific project

# Generation
vineguard generate tests    # Generate comprehensive test suite
vineguard generate prd      # Generate PRD from existing code
vineguard generate docs     # Generate documentation

# Bug Detection & Fixing
vineguard fix               # Scan and fix all issues
vineguard fix src/auth.js   # Fix issues in specific file

# System Management
vineguard health            # Check system health
vineguard version           # Show version information
vineguard help              # Show help information
```

### Advanced Usage

```bash
# Custom configurations
vineguard test --config custom.json
vineguard analyze --depth deep --include-deps
vineguard generate tests --framework jest,playwright

# CI/CD Integration
vineguard test --ci --coverage --report-format junit
vineguard fix --auto-commit --message "Auto-fix: VineGuard"
```

## 🎯 CLI Features

### Complete Testing Workflow
- **📋 Requirements Analysis** - Reads PRDs and extracts test scenarios
- **🔍 Code Understanding** - Scans project structure and analyzes patterns
- **📝 Test Generation** - Creates comprehensive test suites automatically
- **🚀 Test Execution** - Runs tests with enhanced debugging context
- **📊 Results Analysis** - Provides actionable insights and metrics
- **🔧 Automated Fixes** - Generates and applies fixes with regression tests

### AI-Powered Intelligence
- **Natural Language Commands** - Talk to VineGuard naturally via CLI
- **Risk-Based Testing** - Prioritizes tests based on business impact
- **Multi-Framework Support** - Jest, Playwright, Cypress, Vitest
- **Debug Context Collection** - Captures browser logs, network requests, errors
- **Intelligent Analysis** - Deep understanding of code patterns

### CLI-Specific Features
- **Batch Processing** - Handle multiple projects simultaneously
- **CI/CD Integration** - Seamless integration with build pipelines
- **Scriptable Interface** - Easy to integrate into custom automation
- **Config File Support** - JSON, YAML, and JavaScript configuration files
- **Exit Codes** - Proper exit codes for automation scripts
- **Progress Indicators** - Real-time progress feedback for long operations

## ⚙️ Configuration

### Configuration File

Create a `vineguard.config.js` in your project root:

```javascript
export default {
  // Testing framework preferences
  frameworks: ['jest', 'playwright'],

  // AI analysis settings
  analysis: {
    depth: 'deep',
    includeDependencies: true,
    riskAssessment: true
  },

  // Generation preferences
  generation: {
    testStyle: 'comprehensive',
    includeEdgeCases: true,
    accessibilityTests: true
  },

  // CI/CD specific settings
  ci: {
    coverage: {
      threshold: 80,
      format: ['text', 'html', 'lcov']
    },
    reporting: {
      formats: ['junit', 'json'],
      outputDir: './reports'
    }
  }
};
```

### Environment Variables

```bash
# Project settings
export VINEGUARD_PROJECT_ROOT="/path/to/project"
export VINEGUARD_CONFIG_FILE="custom-config.js"

# Mode settings
export VINEGUARD_MODE="orchestrator"
export VINEGUARD_DEFAULT="intelligent"

# CI/CD settings
export VINEGUARD_CI="true"
export VINEGUARD_AUTO_FIX="false"
export VINEGUARD_COVERAGE_THRESHOLD="80"
```

## 🔄 CI/CD Integration

### GitHub Actions

```yaml
name: VineGuard Testing
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '20'

      - name: Install VineGuard CLI
        run: npm install -g vineguard

      - name: Analyze Project
        run: vineguard analyze --ci

      - name: Run Tests
        run: vineguard test --ci --coverage

      - name: Auto-fix Issues
        run: vineguard fix --auto-commit
        if: github.event_name == 'push'
```

### Jenkins Pipeline

```groovy
pipeline {
    agent any
    stages {
        stage('Setup') {
            steps {
                sh 'npm install -g vineguard'
            }
        }
        stage('Analyze') {
            steps {
                sh 'vineguard analyze --ci'
            }
        }
        stage('Test') {
            steps {
                sh 'vineguard test --ci --coverage'
            }
        }
        stage('Fix') {
            when {
                branch 'main'
            }
            steps {
                sh 'vineguard fix --auto-commit'
            }
        }
    }
}
```

## 🛠️ Development

### Building from Source

```bash
# Clone the repository
git clone https://github.com/idvd20/vineguard.git
cd vineguard/vineguard

# Install dependencies
npm install

# Build the package
npm run build

# Link for global usage
npm link
```

### Running Tests

```bash
# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run in watch mode
npm run test:watch
```

## 🤔 CLI vs MCP: Which Should I Use?

### Use **VineGuard CLI** when:
- ✅ Building **CI/CD pipelines** that need automated testing
- ✅ Working primarily in the **terminal/command line**
- ✅ Need to **batch process** multiple projects
- ✅ Creating **automation scripts** that integrate testing
- ✅ Want **programmatic control** over testing workflows

### Use **VineGuard MCP** when:
- ✅ Working **interactively** in Claude Code, Cursor, or VS Code
- ✅ Want **natural language** commands while coding
- ✅ Need **real-time AI assistance** during development
- ✅ Prefer **IDE-integrated** testing workflows

### Use Both when:
- ✅ Your team uses **different workflows** (some prefer CLI, others IDE)
- ✅ You want **CLI for automation** + **MCP for development**
- ✅ Building **comprehensive** testing strategies

## 📊 Exit Codes

VineGuard CLI uses standard exit codes for automation:

```bash
0   # Success
1   # General error
2   # Test failures detected
3   # Configuration error
4   # Project analysis failed
5   # Network/dependency error
```

## 🔗 Related Packages

- **[VineGuard MCP](https://www.npmjs.com/package/vineguard-mcp)**: IDE integration server
- **[VineGuard Core](https://www.npmjs.com/package/vineguard-core)**: Core functionality
- **[VineGuard Utils](https://www.npmjs.com/package/vineguard-utils)**: Shared utilities

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](../CONTRIBUTING.md) for details.

## 📄 License

MIT License - see [LICENSE](../LICENSE) file for details.

## 🔗 Links

- **Main Project**: [VineGuard Monorepo](https://github.com/idvd20/vineguard)
- **CLI Package**: [vineguard](https://www.npmjs.com/package/vineguard)
- **MCP Package**: [vineguard-mcp](https://www.npmjs.com/package/vineguard-mcp)
- **Issues**: [Report Issues](https://github.com/idvd20/vineguard/issues)
- **Documentation**: [Full Docs](https://github.com/idvd20/vineguard/tree/main/docs)