ctrlshiftleft/docs/UPGRADE_TO_AI.md

AI-powered toolkit for embedding QA and security testing into development workflows

# Upgrading to AI-Enhanced ctrl.shift.left

This guide will walk you through the process of upgrading your existing ctrl.shift.left installation to take advantage of the new AI-enhanced security analysis capabilities.

## Overview of New Features

The AI-enhanced version of ctrl.shift.left includes:

1. **AI-Powered Security Analysis**: Deeper vulnerability detection with contextual understanding
2. **Sophisticated Remediation Suggestions**: Specific code examples to fix detected vulnerabilities
3. **Enhanced VS Code Integration**: Direct access to AI capabilities from your editor
4. **Improved CLI**: New `ctrlshiftleft-ai` CLI tool with AI options

## Prerequisites

- An OpenAI API key (obtain from [OpenAI's platform](https://platform.openai.com/))
- Node.js 14.0 or higher
- Existing ctrl.shift.left installation

## Installation Steps

### 1. Update Your Environment

First, set up your environment with the required OpenAI API key:

```bash
# Add to your shell profile or .env file in project root
export OPENAI_API_KEY="your-api-key-here"

# Optional: Specify the model (defaults to gpt-4)
export OPENAI_MODEL="gpt-4"
```

### 2. Update VS Code Extension

To update the VS Code extension:

1. Navigate to your extension directory
   ```bash
   cd /Users/johngaspar/CascadeProjects/ctrlshiftleft/vscode-ext-test
   ```

2. Replace the existing extension files with the AI-enhanced versions
   ```bash
   cp package-enhanced.json package.json
   cp extension-enhanced.js extension-simple.js
   ```

3. Reload VS Code
   - Press `Cmd+Shift+P` (or `Ctrl+Shift+P` on Windows/Linux)
   - Type "Reload Window" and press Enter

### 3. Test the AI Installation

Verify your installation by running the AI-enhanced security analysis:

```bash
# From your project root
./bin/ctrlshiftleft-ai analyze --ai demo/samples/vulnerable-auth.js
```

You should see output indicating that the AI-enhanced analyzer is being used.

## Using the New AI Features

### Command Line

The new CLI offers AI-enhanced versions of all commands:

```bash
# Run AI-enhanced security analysis
./bin/ctrlshiftleft-ai analyze --ai <file-path>

# Run the full workflow with AI security analysis
./bin/ctrlshiftleft-ai secure --ai <file-path>
```

### VS Code

The VS Code extension now includes:

1. **AI Security Analysis**: Right-click on a file → "Ctrl+Shift+Left: AI Security Analysis"
2. **AI Full Scan**: Right-click on a file → "Ctrl+Shift+Left: AI Full Scan"

The extension will prompt for your OpenAI API key if it's not found in your environment.

## Troubleshooting

### API Key Issues

If you encounter errors related to the OpenAI API key:

1. Ensure the key is correctly set in your environment
2. Check that the key has the necessary permissions
3. Verify you have sufficient API credits in your OpenAI account

### Fallback to Pattern-Based Analysis

If AI analysis fails for any reason, the system will automatically fall back to pattern-based analysis. You can check the console output to see if this happened.

### VS Code Extension Not Loading

If the VS Code extension doesn't load correctly after updating:

1. Check the VS Code Developer Console for errors (Help → Toggle Developer Tools)
2. Ensure all file permissions are set correctly
3. Try reinstalling the extension manually

## Reverting to Previous Version

If needed, you can revert to the non-AI version:

```bash
# Use the original CLI
./bin/ctrlshiftleft analyze <file-path>

# For VS Code, restore the original extension files
cd /Users/johngaspar/CascadeProjects/ctrlshiftleft/vscode-ext-test
git checkout -- package.json extension-simple.js
```

## Performance Considerations

- AI-enhanced analysis is slower (typically 5-15 seconds per file)
- API usage incurs costs based on your OpenAI plan
- For large codebases, consider batching analysis or focusing on critical components

## Next Steps

For more detailed information about the AI-enhanced capabilities, please refer to:

- [AI Security Guide](/docs/AI_SECURITY_GUIDE.md)
- [API Documentation](/docs/API.md)

## Feedback

We value your feedback on the AI-enhanced features! Please share your experience and suggestions.