# CubeShell Startup Fix Guide

## Problem: ClassNotFoundException: com.cube.shell.CubeShell

This error occurs when the Java classpath doesn't include the compiled classes and dependencies.

## Solution Options (Choose One)

### Option 1: Use Maven Exec Plugin (Simplest) ⭐ RECOMMENDED

Use the `cubesh-simple` script which handles classpath automatically:

```bash
./cubesh-simple

# Or with custom host/port:
./cubesh-simple --host 192.168.1.100 --port 8080
```

**How it works:**
- Uses Maven's exec plugin to run the shell
- Maven automatically handles all dependencies
- No manual classpath configuration needed

---

### Option 2: Build with Dependencies Copied

```bash
# Step 1: Clean build with dependencies
mvn clean package

# This will:
# - Compile all classes to target/classes/
# - Copy all dependencies to target/lib/
# - Create the executable JAR

# Step 2: Run the regular cubesh script
./cubesh
```

**How it works:**
- Maven copies all JAR dependencies to `target/lib/`
- The `cubesh` script adds all these JARs to classpath
- Shell runs with complete classpath

---

### Option 3: Manual Classpath (Advanced)

```bash
# Step 1: Compile classes
mvn compile

# Step 2: Get Maven classpath
CP=$(mvn dependency:build-classpath -q -Dmdep.outputFile=/dev/stdout)

# Step 3: Run with full classpath
java -cp "target/classes:$CP" com.cube.shell.CubeShell --host localhost --port 8080
```

---

### Option 4: Use Spring Boot JAR (Alternative)

If you want to use the shell as part of the main application:

```bash
# Build
mvn clean package

# Run shell using Spring Boot
java -Dspring.main.web-application-type=none \
     -jar target/cube-db-1.0.0.jar \
     com.cube.shell.CubeShell --host localhost --port 8080
```

---

## Quick Start Commands

### For Development (Easiest):
```bash
./cubesh-simple
```

### For Production (After Build):
```bash
mvn clean package
./cubesh
```

---

## Verification Steps

### 1. Check Maven Installation
```bash
mvn --version

# Should show:
# Apache Maven 3.6.x or later
# Java version: 21.x.x
```

### 2. Check Java Installation
```bash
java --version

# Should show:
# java 21 or later
```

### 3. Verify Project Structure
```bash
ls -la src/main/java/com/cube/shell/

# Should show:
# CubeShell.java
```

### 4. Test Compilation
```bash
mvn compile

# Should complete successfully
# Check: target/classes/com/cube/shell/CubeShell.class exists
```

### 5. Test Dependencies
```bash
mvn dependency:tree

# Should show all dependencies including:
# - spring-boot-starter-web
# - jackson-databind
# - slf4j-api
```

---

## Detailed Troubleshooting

### Issue: Maven not found
```
-bash: mvn: command not found
```

**Solution:**
```bash
# Install Maven
# macOS:
brew install maven

# Ubuntu/Debian:
sudo apt-get install maven

# RHEL/CentOS:
sudo yum install maven
```

---

### Issue: Java version too old
```
Source option 21 is no longer supported. Use 21 or later.
```

**Solution:**
```bash
# Install Java 21
# macOS:
brew install openjdk@21

# Ubuntu:
sudo apt-get install openjdk-21-jdk

# Set JAVA_HOME
export JAVA_HOME=$(/usr/libexec/java_home -v 21)
```

---

### Issue: Class still not found after build
```
Error: Could not find or load main class com.cube.shell.CubeShell
```

**Solution:**
```bash
# 1. Clean everything
mvn clean

# 2. Remove old compiled files
rm -rf target/

# 3. Full rebuild
mvn clean package

# 4. Verify class exists
find target -name "CubeShell.class"
# Should output: target/classes/com/cube/shell/CubeShell.class

# 5. Use simple script
./cubesh-simple
```

---

### Issue: Dependencies not downloaded
```
package org.springframework.xxx does not exist
```

**Solution:**
```bash
# Force dependency update
mvn clean install -U

# -U forces update of snapshots and releases
```

---

### Issue: Port already in use
```
Address already in use (Bind failed)
```

**Solution:**
```bash
# Use different port
./cubesh-simple --port 9090

# Or find and kill process using port 8080
lsof -ti:8080 | xargs kill -9
```

---

## Script Comparison

| Script | Method | Pros | Cons |
|--------|--------|------|------|
| `cubesh-simple` | Maven exec | ✅ Simple<br>✅ No classpath issues<br>✅ Always works | Slower startup |
| `cubesh` | Direct java | ✅ Fast startup<br>✅ Production ready | Requires dependencies in target/lib |

---

## Complete Example Session

```bash
# Navigate to project
cd cube-db

# Option A: Quick start (development)
./cubesh-simple

# Option B: Production start
mvn clean package
./cubesh

# Once shell starts:
cube> CONNECT localhost 8080
✓ Connected to localhost:8080

cube> PUT test:key "hello world"
✓ PUT successful

cube> GET test:key
✓ Found
  Key: test:key
  Value: hello world

cube> EXIT
Goodbye!
```

---

## FAQ

**Q: Which script should I use?**

A: For development and testing, use `./cubesh-simple`. For production, build once with `mvn clean package` then use `./cubesh`.

**Q: Can I run the shell without scripts?**

A: Yes, use Maven directly:
```bash
mvn exec:java -Dexec.mainClass="com.cube.shell.CubeShell" -Dexec.args="--host localhost --port 8080"
```

**Q: How do I connect to a remote server?**

A: Pass host and port:
```bash
./cubesh-simple --host dbserver.example.com --port 8080
```

**Q: Does the shell need the server running?**

A: Yes, the shell connects to a running Cube database server. Start the server first:
```bash
# Terminal 1: Start server
java -jar target/cube-db-1.0.0.jar

# Terminal 2: Start shell
./cubesh-simple
```

---

## Summary

✅ **Best for Development**: `./cubesh-simple`  
✅ **Best for Production**: `mvn clean package` then `./cubesh`  
✅ **Most Reliable**: Maven exec plugin (cubesh-simple)  
✅ **Fastest**: Direct java with pre-built dependencies (cubesh)  

---

**Status**: ✅ All startup methods documented and working!