Package Exports

vineguard
vineguard/mcp-server

Readme

VineGuard - Complete AI-Powered Testing Orchestration System

VineGuard is your complete AI-powered testing orchestration system that handles the entire workflow from requirements analysis to automated fixes. This package includes all VineGuard features and provides a unified CLI for easy usage.

🚀 Quick Start

Installation

# Install globally for CLI usage
npm install -g vineguard

# Or install locally in your project
npm install vineguard

Basic Usage

# 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

🎯 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
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

IDE Integration

Claude Code - Native MCP integration
Cursor - AI pair programming support
VS Code - Extension and MCP support
Universal MCP - Works with any MCP-compatible IDE

📋 CLI Commands

Core Commands

# 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

# Environment Variables
VINEGUARD_MODE=orchestrator vineguard start
VINEGUARD_LOG_LEVEL=debug vineguard test
NODE_ENV=production vineguard health

# With specific configurations
vineguard test --coverage --watch
vineguard generate tests --framework=jest --coverage=90
vineguard fix --auto-commit --dry-run

🔧 IDE Integration

Claude Code

Add to your .claude_code_config.json:

{
  "mcpServers": {
    "vineguard": {
      "command": "vineguard",
      "args": ["mcp-server"],
      "env": {
        "VINEGUARD_MODE": "orchestrator"
      }
    }
  }
}

Cursor

Add to your Cursor settings:

{
  "mcp.servers": {
    "vineguard": {
      "command": "vineguard",
      "args": ["mcp-server"]
    }
  }
}

VS Code

Install the VineGuard extension or configure MCP:

{
  "vineguard.autoStart": true,
  "vineguard.mode": "orchestrator",
  "vineguard.debugCapture": true
}

📦 API Usage

Programmatic Usage

import VineGuard from 'vineguard';

// Run tests programmatically
await VineGuard.runTests(['src/components']);

// Analyze project
await VineGuard.analyzeProject('/path/to/project');

// Generate tests
await VineGuard.generate('tests', ['src/']);

// Fix issues
await VineGuard.fixIssues(['src/auth.js']);

// Check health
const health = await VineGuard.checkSystemHealth();

Individual Package Usage

// Use specific components
import { ProjectScanner } from 'vineguard-core';
import { PlaywrightRunner } from 'vineguard-e2e-runner';
import { JestRunner } from 'vineguard-jest-runner';

const scanner = new ProjectScanner();
const e2eRunner = new PlaywrightRunner();
const jestRunner = new JestRunner();

🎯 Use Cases

For Developers

# Complete QA workflow
vineguard analyze           # Understand project
vineguard generate tests    # Create comprehensive tests
vineguard test             # Run with AI insights
vineguard fix              # Auto-fix issues

For QA Engineers

# Test strategy development
vineguard analyze --deep    # Deep project analysis
vineguard generate prd      # Extract requirements
vineguard generate tests --risk-based  # Risk-based test planning

For Teams

# CI/CD Integration
vineguard test --ci         # Run in CI mode
vineguard health --export   # Export health metrics
vineguard fix --safe        # Safe automated fixes

🔧 Configuration

Environment Variables

# Core Configuration
VINEGUARD_MODE=orchestrator          # Operation mode
VINEGUARD_LOG_LEVEL=info            # Logging level
VINEGUARD_TIMEOUT_MS=300000         # Operation timeout

# Testing Configuration
VINEGUARD_TEST_FRAMEWORKS=jest,playwright  # Preferred frameworks
VINEGUARD_COVERAGE_THRESHOLD=80     # Coverage requirement
VINEGUARD_AUTO_FIX=true            # Enable auto-fixing

# Debug & Monitoring
VINEGUARD_DEBUG_CAPTURE=true       # Capture debug context
VINEGUARD_METRICS_ENABLED=true     # Enable metrics
VINEGUARD_HEALTH_CHECK_PORT=8080   # Health check port

Project Configuration

Create vineguard.config.js:

export default {
  mode: 'orchestrator',
  testFrameworks: ['jest', 'playwright'],
  coverage: {
    threshold: 85,
    include: ['src/**/*.ts'],
    exclude: ['**/*.test.ts']
  },
  analysis: {
    deep: true,
    includeTypes: ['unit', 'integration', 'e2e'],
    riskBased: true
  },
  fixes: {
    autoApply: false,
    safeMode: true,
    createBackups: true
  }
};

📊 Monitoring & Health

Health Endpoints

VineGuard provides monitoring endpoints:

# Health check
curl http://localhost:8080/health

# Metrics (Prometheus format)
curl http://localhost:9090/metrics

# System status
curl http://localhost:8080/status

Health Dashboard

# Start with monitoring
vineguard start --monitoring

# View health dashboard
open http://localhost:8080/dashboard

🚀 Advanced Features

Natural Language Commands

VineGuard understands natural language:

vineguard "analyze my React project and generate comprehensive tests"
vineguard "find bugs in the authentication module and fix them"
vineguard "create e2e tests for the user registration flow"
vineguard "check test coverage and fill the gaps"

Debug Context Collection

Automatically captures:

Browser console logs
Network requests and responses
JavaScript errors and stack traces
Performance metrics
User interactions

Intelligent Test Analysis

Identifies flaky tests
Suggests test improvements
Detects missing test coverage
Recommends test strategies

🤝 Contributing

VineGuard is open source and welcomes contributions:

Fork the repository
Create a feature branch
Add tests for new features
Submit a pull request

📄 License

🔗 Links

GitHub: https://github.com/idvd20/vineguard
npm: https://www.npmjs.com/package/vineguard
Documentation: https://github.com/idvd20/vineguard/tree/main/docs
Issues: https://github.com/idvd20/vineguard/issues

VineGuard - Your Complete AI Testing Partner 🍇