Installation Issues.md - johnpeterman72/CursorRIPER.sigma GitHub Wiki

Framework Installation Issues

Common Installation Problems

Node.js Version Compatibility

Problem: Framework fails to install due to Node.js version mismatch

Symptoms:

Error: Unsupported engine
Required: node >=18.0.0
Actual: node v16.14.0

Solution:

# Check current Node.js version
node --version

# Install Node Version Manager (nvm)
# Windows
winget install CoreyButler.NVMforWindows

# macOS/Linux
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install and use Node.js 18
nvm install 18
nvm use 18

# Verify installation
node --version  # Should show v18.x.x

Package Installation Failures

Problem: npm install fails with permission errors

Symptoms:

EACCES: permission denied, mkdir '/usr/local/lib/node_modules'

Solutions:

Option 1: Fix npm permissions (Recommended)

# Create global directory for npm
mkdir ~/.npm-global

# Configure npm to use new directory
npm config set prefix '~/.npm-global'

# Add to PATH (add to ~/.bashrc or ~/.zshrc)
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Option 2: Use npx for one-time installation

npx create-cursoriper-app my-project

Option 3: Use Yarn instead of npm

# Install Yarn
npm install -g yarn

# Install dependencies with Yarn
yarn install

Framework Dependencies Missing

Problem: Framework components fail to load

Symptoms:

Error: Cannot find module '@cursoriper/core'
Module not found: Error: Can't resolve './config/framework.config.js'

Solution:

# Clean install
rm -rf node_modules package-lock.json
npm cache clean --force
npm install

# Verify framework installation
npm list @cursoriper/core
npm run framework:verify

Database Connection Issues

Problem: Cannot connect to default database during setup

Symptoms:

Error: Connection ECONNREFUSED 127.0.0.1:5432
Database connection failed during framework initialization

Solutions:

SQLite (Recommended for development)

// framework.config.js
module.exports = {
  database: {
    type: 'sqlite',
    database: './data/framework.sqlite',
    synchronize: true,
    logging: false
  }
};

Skip database during initial setup

# Initialize without database
npm run framework:init --skip-db

# Configure database later
npm run framework:setup-db

Port Conflicts

Problem: Default ports already in use

Symptoms:

Error: listen EADDRINUSE: address already in use :::3000
Port 3000 is already in use

Solution:

# Find process using port
# Windows
netstat -ano | findstr :3000
taskkill /PID <PID> /F

# macOS/Linux
lsof -ti:3000
kill -9 <PID>

# Or use different port
PORT=3001 npm start

# Or configure in framework.config.js
module.exports = {
  server: {
    port: process.env.PORT || 3001
  }
};

Environment Setup Issues

Framework Configuration Missing

Problem: Framework fails to start due to missing configuration

Symptoms:

Error: Framework configuration not found
Please run 'npm run framework:init' first

Solution:

# Initialize framework configuration
npm run framework:init

# Manual configuration
cp config/framework.config.example.js config/framework.config.js

# Edit configuration file
nano config/framework.config.js

Environment Variables Not Loaded

Problem: Environment-specific settings not working

Symptoms:

Warning: NODE_ENV not set, defaulting to development
Error: JWT_SECRET environment variable required

Solution:

# Create environment file
touch .env

# Add required variables
echo "NODE_ENV=development" >> .env
echo "JWT_SECRET=$(openssl rand -base64 32)" >> .env
echo "DATABASE_URL=sqlite://./data/framework.sqlite" >> .env

# Verify variables are loaded
npm run framework:env-check

Framework Modules Not Loading

Problem: Custom modules or plugins fail to load

Symptoms:

Error: Plugin 'bmad' failed to load
Module resolution failed for custom components

Solution:

# Check module structure
ls -la src/modules/
ls -la src/plugins/

# Verify module exports
node -e "console.log(require('./src/modules/bmad'))"

# Reinstall framework
npm run framework:reinstall

# Clear module cache
npm run framework:clear-cache

Build and Development Issues

Build Process Failures

Problem: Framework build process fails

Symptoms:

Build failed with errors
webpack compilation failed
TypeScript compilation errors

Solutions:

Clear build cache

# Clear all caches
npm run clean
rm -rf dist/ build/ .cache/

# Rebuild
npm run build

Check for syntax errors

# Run linting
npm run lint

# Fix auto-fixable issues
npm run lint:fix

# Check TypeScript (if applicable)
npm run type-check

Dependency conflicts

# Check for conflicting versions
npm ls --depth=0

# Update dependencies
npm update

# Resolve peer dependency warnings
npm install --legacy-peer-deps

Development Server Issues

Problem: Development server won't start or crashes

Symptoms:

Error: Development server crashed
Hot reload not working
Module not found errors during development

Solutions:

Restart development server

# Stop server (Ctrl+C)
# Clear cache and restart
npm run dev:clean
npm run dev

Check for file watching limits (Linux)

# Increase file watch limit
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

Fix hot reload issues

# Force full reload
# Add to framework.config.js
module.exports = {
  dev: {
    hot_reload: true,
    poll: true,  // Use polling for file changes
    watch_options: {
      ignored: /node_modules/,
      aggregateTimeout: 300
    }
  }
};

Framework CLI Issues

Problem: Framework CLI commands don't work

Symptoms:

Command 'framework' not found
CLI commands fail with module errors

Solutions:

Install CLI globally

npm install -g @cursoriper/cli

# Or use npx
npx @cursoriper/cli --version

Link local CLI

# In framework directory
npm link

# Verify CLI works
framework --help

Use npm scripts instead

# Instead of: framework generate component
npm run generate:component

# Instead of: framework db migrate
npm run db:migrate

Quick Diagnostics

Framework Health Check

#!/bin/bash
# Save as: framework-health-check.sh

echo "=== Framework Health Check ==="

# Check Node.js version
echo "Node.js version:"
node --version

# Check npm version
echo "npm version:"
npm --version

# Check framework installation
echo "Framework installation:"
npm list @cursoriper/core 2>/dev/null || echo "Framework not installed"

# Check configuration
echo "Configuration check:"
if [ -f "framework.config.js" ]; then
    echo "✓ Configuration file exists"
else
    echo "✗ Configuration file missing"
fi

# Check environment
echo "Environment variables:"
echo "NODE_ENV: ${NODE_ENV:-not set}"
echo "PORT: ${PORT:-not set}"

# Check database connectivity
echo "Database check:"
npm run db:check 2>/dev/null || echo "Database check failed"

# Check file permissions
echo "Permissions check:"
if [ -w "." ]; then
    echo "✓ Write permissions OK"
else
    echo "✗ No write permissions"
fi

echo "=== End Health Check ==="

Common Log Locations

# Framework logs
tail -f logs/framework.log
tail -f logs/error.log

# Application logs
tail -f logs/app.log

# System logs (Linux)
journalctl -u cursoriper-framework -f

# PM2 logs (if using PM2)
pm2 logs framework

Emergency Reset

#!/bin/bash
# Emergency framework reset
# WARNING: This will reset all local changes

echo "Starting emergency framework reset..."

# Stop all processes
npm run stop 2>/dev/null
pkill -f "node.*framework" 2>/dev/null

# Clean installation
rm -rf node_modules package-lock.json
rm -rf dist build .cache

# Reset configuration
cp config/framework.config.example.js config/framework.config.js

# Reinstall
npm cache clean --force
npm install

# Initialize
npm run framework:init

echo "Framework reset complete. Please reconfigure as needed."

Last Updated: June 28, 2025
Framework Version: CursorRIPER.sigma v1.0+

⚠️ **GitHub.com Fallback** ⚠️