ctrlshiftleft/docs/TROUBLESHOOTING.md

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

# ctrl.shift.left Troubleshooting Guide

This guide provides solutions for common issues encountered when using the ctrl.shift.left toolkit.

## Table of Contents

1. [Installation Issues](#installation-issues)
2. [Module Resolution Problems](#module-resolution-problems)
3. [Framework-Specific Issues](#framework-specific-issues)
4. [Permission Problems](#permission-problems)
5. [AI Integration Issues](#ai-integration-issues)
6. [IDE Integration](#ide-integration)
7. [Diagnostic Tools](#diagnostic-tools)

## Installation Issues

### Global Installation Fails with Permission Errors

**Problem:** `npm install -g ctrlshiftleft` fails with permission errors.

**Solution:**

Use the user-level setup tool:

```bash
# Use our simplified user-level setup
ctrlshiftleft-setup --user
```

Or manually configure user-level installation:

```bash
# Create user-level npm directory (one-time setup)
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'

# Add to PATH in your shell profile (~/.bashrc, ~/.zshrc, or ~/.bash_profile)
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

# Install without sudo
npm install -g ctrlshiftleft
```

### Package.json Installation Issues

**Problem:** Installing with `npm install --save-dev ctrlshiftleft` causes dependency conflicts.

**Solution:**

Try installing with `--legacy-peer-deps`:

```bash
npm install --save-dev --legacy-peer-deps ctrlshiftleft
```

Or update your Node.js version:

```bash
# Using nvm (recommended)
nvm install --lts
nvm use --lts

# Then install ctrl.shift.left
npm install --save-dev ctrlshiftleft
```

## Module Resolution Problems

### "Cannot find module" Errors

**Problem:** Commands fail with errors like `Cannot find module '/node_modules/ctrlshiftleft/vscode-ext-test/generate-tests.js'`

**Solutions:**

1. **Use the repair tool**:

```bash
npx ctrlshiftleft-repair
```

2. **Manually fix module paths**:

```bash
mkdir -p node_modules/ctrlshiftleft/vscode-ext-test
cp $(npm root -g)/ctrlshiftleft/vscode-ext-test/generate-tests.js node_modules/ctrlshiftleft/vscode-ext-test/
```

3. **Reinstall specifying the correct paths**:

```bash
npm remove ctrlshiftleft
npm cache clean --force
npm install --save-dev ctrlshiftleft
```

### Path Resolution in Scripts

**Problem:** Scripts in package.json aren't finding the correct paths.

**Solution:**

As of v1.3.1, ctrl.shift.left creates a `.ctrlshiftleft` directory in your project root to store paths and configuration information. This should automatically fix most path resolution issues. If you're still experiencing problems:

1. **Check for the `.ctrlshiftleft` directory**:
   ```bash
   ls -la .ctrlshiftleft
   ```

2. **Verify the paths configuration**:
   ```bash
   cat .ctrlshiftleft/paths.js
   ```

3. **Manually set up paths**:
   ```json
   {
     "scripts": {
       "qa:gen": "node ./node_modules/ctrlshiftleft/bin/ctrlshiftleft gen ./app/components"
     }
   }
   ```

### Output Path Issues

**Problem:** Security reports and test outputs are not saving to the specified location.

**Solution:**

As of v1.3.1, ctrl.shift.left properly handles custom output paths. Use the `--output` flag to specify output locations:

```bash
# Generate security report with custom output path
npx ctrlshiftleft-ai analyze src/components/Form.jsx --output=reports/security/form-report.md

# Generate tests with custom output directory
npx ctrlshiftleft gen src/components/Button.jsx --output=tests/e2e/generated
```

You can also use the output flag in your npm scripts:

```json
{
  "scripts": {
    "qa:analyze": "ctrlshiftleft-ai analyze src --output=reports/security/analysis.md"
  }
}
```

## Framework-Specific Issues

### Next.js Issues

**Problem:** Special path handling and import issues in Next.js.

**Solution:**

Run the Next.js-specific setup:

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

For more detailed Next.js instructions, see [NEXTJS.md](./frameworks/NEXTJS.md).

### React Issues

**Problem:** React component testing issues.

**Solution:**

Ensure you have the correct testing libraries:

```bash
npm install --save-dev @testing-library/react @testing-library/jest-dom jest jest-environment-jsdom
```

### Error: "Cannot test server components"

**Problem:** Getting errors when trying to test Next.js App Router server components.

**Solution:**

Server components can't be directly tested with unit tests. Either:

1. Convert the component to a client component with `'use client'` directive
2. Use the `--client-only` flag to skip server components:

```bash
npx ctrlshiftleft gen --client-only ./app/components
```

## Permission Problems

### Command Not Found After Installation

**Problem:** After installation, the `ctrlshiftleft` command isn't found.

**Solutions:**

1. **Add to PATH**:

```bash
export PATH="$PATH:$(npm bin -g)"
```

2. **Create symlinks**:

```bash
sudo ln -s $(npm root -g)/ctrlshiftleft/bin/ctrlshiftleft /usr/local/bin/ctrlshiftleft
sudo ln -s $(npm root -g)/ctrlshiftleft/bin/ctrlshiftleft-ai /usr/local/bin/ctrlshiftleft-ai
```

3. **Use npx explicitly**:

```bash
npx ctrlshiftleft gen ./components
```

### Permission Denied When Running Commands

**Problem:** Getting "permission denied" when running commands.

**Solution:**

Add execute permission to the scripts:

```bash
chmod +x ./node_modules/ctrlshiftleft/bin/ctrlshiftleft
chmod +x ./node_modules/ctrlshiftleft/bin/ctrlshiftleft-ai
```

## AI Integration Issues

### OpenAI API Key Issues

**Problem:** AI features not working due to missing API key.

**Solutions:**

1. **Set the environment variable**:

```bash
export OPENAI_API_KEY="your-api-key-here"
```

2. **Add to .env file**:

```
# .env file in your project root
OPENAI_API_KEY=your-api-key-here
```

3. **Use with dotenv in npm scripts**:

```json
{
  "scripts": {
    "qa:analyze": "dotenv -e .env -- npx ctrlshiftleft-ai analyze ./src"
  }
}
```

### Fallback to Pattern-Based Analysis

**Problem:** Want to ensure security analysis works even without API key.

**Solution:**

The tool automatically falls back to pattern-based analysis when the OpenAI API key is unavailable. You can explicitly skip AI features with:

```bash
npx ctrlshiftleft-ai analyze --no-ai ./src
```

## IDE Integration

### VS Code Integration Issues

**Problem:** VS Code extension not working properly.

**Solutions:**

1. **Install from the local package**:

```bash
code --install-extension ./node_modules/ctrlshiftleft/vscode-ext-test/ctrlshiftleft-*.vsix
```

2. **Restart VS Code**:
   
   - Close all VS Code windows
   - Reopen VS Code
   - Go to Extensions and verify ctrl.shift.left is enabled

### Cursor AI Integration Issues

**Problem:** Integration with Cursor AI not working.

**Solution:**

Run the cursor integration setup:

```bash
npm run cursor:integrate
```

Or manually configure:

```bash
npx ctrlshiftleft-cursor setup
```

## Diagnostic Tools

### Using the Repair Tool

The repair tool can diagnose and fix most common issues:

```bash
# Run interactive repair
npx ctrlshiftleft-repair

# Only scan for issues
npx ctrlshiftleft-repair --scan

# Automatically fix issues
npx ctrlshiftleft-repair --fix

# Generate a diagnostic report
npx ctrlshiftleft-repair --report

# Check Next.js compatibility 
npx ctrlshiftleft-repair --nextjs

# Run a comprehensive scan for all issues
npx ctrlshiftleft-repair --comprehensive
```

### Manual Diagnostics

If the repair tool doesn't fix your issue, try these manual diagnostic steps:

1. **Check for module existence**:

```bash
ls -la node_modules/ctrlshiftleft/bin
ls -la node_modules/ctrlshiftleft/vscode-ext-test
```

2. **Verify PATH includes npm bin directories**:

```bash
echo $PATH | grep -o npm
```

3. **Check for file permissions**:

```bash
ls -la $(npm root -g)/ctrlshiftleft/bin
ls -la node_modules/ctrlshiftleft/bin
```

4. **Test a command with full debugging**:

```bash
NODE_DEBUG=module npx ctrlshiftleft --version
```

## QA Validation Issues

### API Route Integration Issues

**Problem:** Issues with integrating QA validation middleware with API routes.

**Solutions:**

1. **Check imports**:

Ensure you're importing the middleware correctly:

```javascript
// For CommonJS
const { createValidationMiddleware } = require('ctrlshiftleft/middleware/qa-validation');

// For ESM
import { createValidationMiddleware } from 'ctrlshiftleft/middleware/qa-validation';
```

2. **Fix next.js integration**:

For Next.js, use the compatibility layer:

```bash
npx ctrlshiftleft-setup --nextjs --fix-middleware
```

## Still Having Issues?

If you've tried the solutions above and are still experiencing problems:

1. Run the complete diagnostic report:

```bash
npx ctrlshiftleft-repair --comprehensive --report
```

2. Open an issue on GitHub with the diagnostic report attached:
   - https://github.com/johngaspar/ctrlshiftleft/issues

3. Include details about your environment:
   - Operating System
   - Node.js version (`node -v`)
   - npm version (`npm -v`)
   - Project details (framework, structure)