ctrlshiftleft/docs/CURSOR_INTEGRATION.md

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

# Cursor AI Integration for ctrl.shift.left

This document explains how to use the real-time feedback features of ctrl.shift.left with Cursor AI and VS Code.

## Overview

The ctrl.shift.left Cursor integration provides:

1. **Real-time Security Analysis**: Get immediate feedback on security vulnerabilities as you code
2. **Editor Diagnostics**: Security issues appear directly in your editor's Problems panel
3. **AI-Enhanced Analysis**: Leverages OpenAI's capabilities for deeper security insights
4. **Test Generation Suggestions**: Recommends test coverage for components as you develop them

## Installation

The cursor integration is included in the ctrl.shift.left package v1.1.0 and higher:

```bash
# Install globally
npm install -g ctrlshiftleft

# Or install in your project
npm install --save-dev ctrlshiftleft
```

## Getting Started

### Option 1: Using the CLI

```bash
# Start watching a directory with real-time feedback
ctrlshiftleft-cursor --dir=./src/components

# Output diagnostics in editor-friendly format
ctrlshiftleft-cursor --output=diagnostics --dir=./src/api
```

### Option 2: Using npm scripts

Add these to your project's package.json:

```json
"scripts": {
  "qa:watch": "ctrlshiftleft-cursor --dir=./src",
  "qa:diagnostics": "ctrlshiftleft-cursor --output=diagnostics --dir=./src"
}
```

Then run:

```bash
npm run qa:watch
```

## Configuration Options

| Option | Description | Default |
|--------|-------------|---------|
| `--dir, -d` | Directory to watch | `./src` |
| `--output, -o` | Output format (console, diagnostics, json) | `console` |
| `--ai` | Use AI-enhanced analysis | `true` |
| `--notify, -n` | Show notifications in editor | `true` |
| `--extensions, -e` | File extensions to watch | `js,jsx,ts,tsx` |

## Integration with Cursor AI

### Method 1: Terminal Integration

1. Open Cursor AI
2. Start a new terminal
3. Run: `ctrlshiftleft-cursor --output=diagnostics`
4. Edit files in your project - you'll get real-time feedback in the terminal

### Method 2: Problems Panel Integration

To get issues directly in the Problems panel:

1. Create a `.vscode/tasks.json` file in your project:

```json
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "ctrl.shift.left Watch",
      "type": "shell",
      "command": "npx ctrlshiftleft-cursor --output=diagnostics",
      "isBackground": true,
      "problemMatcher": {
        "owner": "ctrl.shift.left",
        "pattern": {
          "regexp": "^(.+):(\\d+):(\\d+)\\s+-\\s+(error|warning):\\s+(.+)\\s+\\[(.+)\\]$",
          "file": 1,
          "line": 2,
          "column": 3,
          "severity": 4,
          "message": 5,
          "code": 6
        },
        "background": {
          "activeOnStart": true,
          "beginsPattern": "Watcher started successfully",
          "endsPattern": "^$"
        }
      }
    }
  ]
}
```

2. In Cursor AI or VS Code, run the task (Ctrl+Shift+P > "Tasks: Run Task" > "ctrl.shift.left Watch")

## Environment Variables

* `OPENAI_API_KEY`: Required for AI-enhanced security analysis. Without this, the tool falls back to pattern-based analysis.

## Troubleshooting

### Common Issues

1. **Issue**: No diagnostics appearing in the editor
   **Solution**: Ensure the output format is set to `diagnostics` and the terminal output is being correctly parsed.

2. **Issue**: Limited AI analysis
   **Solution**: Check that your `OPENAI_API_KEY` environment variable is set correctly.

3. **Issue**: High latency in feedback
   **Solution**: Use more targeted watching by specifying smaller directories or specific files.

## Examples

### Example 1: Watch a specific component

```bash
ctrlshiftleft-cursor --dir=./src/components/HomePage
```

### Example 2: Generate JSON output for integration with other tools

```bash
ctrlshiftleft-cursor --output=json --dir=./src/api > security-report.json
```

### Example 3: Focus on specific file extensions

```bash
ctrlshiftleft-cursor --extensions=ts,tsx --dir=./src
```

## Next Steps

- Refer to [AI_SECURITY_GUIDE.md](./AI_SECURITY_GUIDE.md) for more information on the AI-enhanced security analysis
- Check [GITHUB_INTEGRATION.md](./GITHUB_INTEGRATION.md) for setting up continuous integration
- See [INTEGRATION.md](./INTEGRATION.md) for programmatic API usage

For further assistance, please open an issue on the GitHub repository.