ctrlshiftleft/README.md

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

# Ctrl.shift.left

A CLI and IDE-integrated toolkit that empowers developers to embed QA and security into early development by auto-generating, executing, and verifying end-to-end tests and QA checklists as code is authored. Now featuring AI-enhanced security analysis, Next.js framework support, and self-diagnostic capabilities!

## What's New in v1.3.1

- **Improved Path Resolution**: Enhanced module path handling with a new `.ctrlshiftleft` directory structure
- **Better Output Path Handling**: Fixed output path handling for security reports and test generation
- **Enhanced Next.js Support**: Specialized setup for Next.js projects with better framework detection
- **Improved Error Handling**: Better diagnostics and error recovery for common integration issues

## Security & QA Status

[![Security Score](./badges/security.svg)](./security-reports/) 
[![Test Coverage](./badges/tests.svg)](./tests/) 
[![QA Checklist](./badges/checklist.svg)](./checklists/) 
[![GitHub Actions Status](https://github.com/username/ctrlshiftleft/actions/workflows/security-qa.yml/badge.svg)](https://github.com/username/ctrlshiftleft/actions/workflows/security-qa.yml)

_Security and QA metrics automatically generated by ctrl.shift.left_

## Overview

Ctrl.shift.left helps developers shift quality assurance and security testing left in the development process by:

1. Automatically generating end-to-end tests from source code
2. Creating structured QA and security checklists
3. Providing verification tools to execute tests and compare against checklists
4. Integrating seamlessly with development workflows via CLI, IDE, and CI
5. **NEW:** Delivering AI-powered security analysis with sophisticated remediation suggestions
6. **NEW:** Providing a programmable API for integration with other tools
7. **NEW:** Offering an enhanced real-time watcher with AI capabilities
8. **NEW:** Providing first-class Next.js framework support and optimizations
9. **NEW:** Featuring self-diagnostic and repair utilities for seamless integration
10. **NEW:** Including QA validation middleware for API routes

## Installation

### From NPM (Recommended)

```bash
# Install from NPM
npm install -g ctrlshiftleft

# Verify installation
ctrlshiftleft --version

# For Next.js projects, run the specialized setup
ctrlshiftleft-setup --nextjs
```

### From Source

```bash
# Clone the repository
git clone <repository-url>
cd ctrlshiftleft

# Install dependencies
npm install

# Build the project
npm run build

# Create a symlink for global usage
npm link
```

## Configuration

Create a `.env` file in the root directory with the following variables:

```
# OpenAI API Key for AI-enhanced security analysis and LLM features
OPENAI_API_KEY=your_openai_api_key_here

# OpenAI model to use (optional, defaults to gpt-4)
OPENAI_MODEL=gpt-4

# Enable AI security analysis by default (optional)
CTRLSHIFTLEFT_AI_ANALYSIS=true
```

## Usage

### Self-Diagnostics & Repair

If you're experiencing issues with your installation, use the repair tool:

```bash
ctrlshiftleft-repair
```

Options:
- `--fix`: Automatically fix detected issues
- `--verbose`: Show detailed diagnostic information
- `--next`: Specifically check Next.js compatibility

### Framework-Specific Setup

For Next.js projects, use the specialized setup tool:

```bash
ctrlshiftleft-setup --nextjs
```

This creates necessary configuration files and updates your project for optimal compatibility with Next.js App Router or Pages Router.

See [NEXTJS.md](./docs/frameworks/NEXTJS.md) for framework-specific details.

### AI-Enhanced Security Analysis

Perform advanced security analysis with AI-powered insights:

```bash
ctrlshiftleft-ai analyze --ai <source-path>
```

Options:
- `--ai`: Enable AI-powered analysis (requires OPENAI_API_KEY)
- `--output=<file>`: Output file for the security report

### AI-Enhanced Full Scan

Run a complete workflow with AI security analysis, test generation, and checklist creation:

```bash
ctrlshiftleft-ai secure --ai <source-path>
```

Options:
- `--ai`: Enable AI-powered analysis (requires OPENAI_API_KEY)

### Generate Tests

Generate end-to-end tests from source code:

```bash
ctrlshiftleft gen <source-path> [options]
```

Options:
- `-o, --output <directory>`: Output directory for generated tests (default: `./tests`)
- `-f, --format <format>`: Test format (playwright or selenium) (default: `playwright`)
- `-t, --timeout <timeout>`: Timeout for test generation in seconds (default: `60`)

### Run Tests

Execute generated end-to-end tests:

```bash
ctrlshiftleft run [test-path] [options]
```

Options:
- `[test-path]`: Path to test file or directory (default: `./tests`)
- `-b, --browser <browser>`: Browser to run tests in (default: `chromium`)
- `-h, --headless`: Run browser in headless mode (default: `true`)
- `-t, --timeout <timeout>`: Test timeout in seconds (default: `30`)
- `-r, --reporter <reporter>`: Test reporter format (default: `list`)

### Watch Mode

Watch source files and auto-generate tests on changes:

```bash
ctrlshiftleft watch <source-path> [options]
```

Options:
- `-o, --output <directory>`: Output directory for generated tests (default: `./tests`)
- `-i, --ignore <patterns>`: Comma-separated glob patterns to ignore (default: `node_modules,dist,build,*.test.*`)
- `-d, --delay <ms>`: Debounce delay in milliseconds (default: `1000`)

### AI-Enhanced Watch (NEW)

Watch files with real-time AI-powered security analysis, test generation, and checklist creation:

```bash
ctrlshiftleft watch-ai <directory> [options]

# Or use the npm script
npm run ai:watch
```

Options:
- `-t, --tests`: Generate tests on file changes (default: `true`)
- `-s, --security`: Perform security analysis on file changes (default: `true`)
- `-c, --checklists`: Generate QA checklists on file changes (default: `true`)
- `-a, --ai`: Use AI-enhanced security analysis (requires OpenAI API key)
- `--test-output <dir>`: Output directory for tests (default: `./tests`)
- `--security-output <dir>`: Directory for security reports (default: `./security-reports`)
- `--checklist-output <dir>`: Directory for checklists (default: `./checklists`)
- `--include <patterns...>`: Glob patterns to include
- `--exclude <patterns...>`: Glob patterns to exclude

### Cursor AI Integration (NEW)

Get real-time feedback during development with Cursor AI and VS Code integration:

```bash
# Start real-time feedback in your editor
ctrlshiftleft-cursor --dir=./src

# Output in editor-friendly diagnostics format
ctrlshiftleft-cursor --output=diagnostics

# Or use npm scripts
npm run cursor:watch
npm run cursor:integrate
```

Options:
- `--dir, -d <path>`: Directory to watch (default: `./src`)
- `--output, -o <format>`: Output format: console, diagnostics, json (default: `console`)
- `--ai <boolean>`: Use AI-enhanced analysis (default: `true`)
- `--notify, -n <boolean>`: Show notifications in editor (default: `true`)
- `--extensions, -e <exts...>`: File extensions to watch (default: `js,jsx,ts,tsx`)

See [CURSOR_INTEGRATION.md](./docs/CURSOR_INTEGRATION.md) for VS Code tasks.json setup and more details.
- `--concurrent <n>`: Maximum concurrent tasks (default: `3`)
- `--silent`: Run in silent mode (no progress reporting)

This enhanced watcher is optimized for integration with AI code generation tools like Cursor AI, providing immediate feedback as code is created.

### Generate Checklists

Generate QA and security checklists from source code:

```bash
ctrlshiftleft checklist <source-path> [options]
```

Options:
- `-o, --output <file>`: Output JSON file for generated checklist (default: `./checklist.json`)
- `-t, --type <type>`: Type of checklist to generate (qa, security, all) (default: `all`)
- `--format <format>`: Output format (json, markdown) (default: `json`)

### Programmable API (NEW)

Use ctrl.shift.left programmatically in your Node.js applications:

```javascript
// Import the API
const ctrlShiftLeft = require('ctrlshiftleft');

// Generate end-to-end tests
const testResults = await ctrlShiftLeft.generateTests('./src/components/LoginForm.jsx', {
  outputDir: './generated-tests',
  format: 'playwright'
});
console.log(`Generated ${testResults.testCount} tests`);

// Use the AI-enhanced watcher
const { EnhancedWatcher } = ctrlShiftLeft;
const watcher = new EnhancedWatcher({
  useAIAnalysis: true,  // Requires OpenAI API key
  maxConcurrentTasks: 2
});

// Listen for events
watcher.on('analysis:complete', (result) => {
  if (result.success) {
    console.log(`Analysis completed for ${result.filePath}`);
  }
});

// Start watching
watcher.watch('./src');
```

For complete API documentation, see [API.md](./API.md).

## CI/CD Integration

### GitHub Action

Ctrl.shift.left provides an official GitHub Action that you can add to your workflow:

```yaml
name: Security & QA Check

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  test-security-qa:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Set up OpenAI API Key
        run: echo "OPENAI_API_KEY=${{ secrets.OPENAI_API_KEY }}" >> $GITHUB_ENV
      
      - name: Run ctrl.shift.left Analysis
        uses: ctrlshiftleft/action@v1
        with:
          source-path: './src'  # Path to your source code
          fail-on-security-issues: true  # Fail the build if security issues found
          framework: 'nextjs'  # Specify framework for specialized handling
```

#### Configuration Options

| Input | Description | Default |
|-------|-------------|--------|
| `source-path` | Path to source code to analyze | `./src` |
| `test-output-path` | Output directory for generated tests | `./tests/generated` |
| `checklist-output-path` | Output directory for generated checklists | `./checklists` |
| `browser` | Browser to use for tests (chromium, firefox, webkit) | `chromium` |
| `headless` | Run tests in headless mode | `true` |
| `fail-on-security-issues` | Fail build on security issues | `true` |
| `framework` | Target framework (nextjs, react, vue, etc.) | `auto` |

#### Action Outputs

| Output | Description |
|--------|-------------|
| `has-security-issues` | Boolean indicating whether security issues were found |

For more information, see the [GitHub Action README](./.github/README.md).

### Manual Integration

Alternatively, you can manually integrate ctrl.shift.left into your CI/CD pipeline:

```yaml
- name: Generate and run tests
  run: |
    npm install -g ctrlshiftleft
    ctrlshiftleft gen ./src -o ./tests
    ctrlshiftleft run ./tests
```

## Middleware Integration

Include security and QA validation in your API routes:

```javascript
// Express example
const express = require('express');
const { createValidationMiddleware } = require('ctrlshiftleft/middleware/qa-validation');

const app = express();

// Create a middleware with validation rules
const validateUser = createValidationMiddleware({
  requiredFields: ['username', 'email'],
  fieldValidations: {
    email: { type: 'email' },
    password: { type: 'password', minStrength: 'medium' },
    websiteUrl: { type: 'url', optional: true }
  }
});

// Apply the middleware to routes
app.post('/api/users', validateUser, (req, res) => {
  // If validation passes, handle the request
  // The validated data is available in req.validatedData
  res.json({ success: true });
});
```

## Troubleshooting

If you encounter any issues, refer to our comprehensive [Troubleshooting Guide](./docs/TROUBLESHOOTING.md).

## License

MIT