weevil/README.md

# 🪲 Weevil - FTC Project Generator

**Bores into complexity, emerges with clean code.**

A modern, cross-platform project generator for FIRST Tech Challenge (FTC) robotics that creates clean, testable, and maintainable robot projects — without forcing students to edit their SDK installation.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## The Problem

The official FTC SDK requires teams to:
1. Clone the entire SDK repository
2. Edit files directly inside the SDK
3. Mix team code with framework code
4. Navigate through hundreds of unfamiliar files
5. Risk breaking the SDK with every change

This approach works against standard software engineering practices and creates unnecessary barriers for students learning to code. Industry uses libraries, JARs, and dependency management for good reasons — it's time FTC robotics caught up.

## The Solution

**Weevil** generates standalone robot projects that:
- ✅ Keep your code separate from the SDK
- ✅ Support local unit testing (no robot needed!)
- ✅ Work with multiple SDK versions simultaneously
- ✅ Generate all build/deploy scripts automatically
- ✅ Enable proper version control workflows
- ✅ Are actually testable and maintainable

Students focus on building robots, not navigating SDK internals.

---

## Features

### 🎯 Clean Project Structure
```
my-robot/
├── src/
│   ├── main/java/robot/     # Your robot code lives here
│   └── test/java/robot/     # Unit tests (run on PC!)
├── build.sh / build.bat     # One command to build
├── deploy.sh / deploy.bat   # One command to deploy
└── .weevil.toml            # Project configuration
```

### 🚀 Simple Commands
```bash
# Create a new robot project
weevil new awesome-robot

# Test your code (no robot required!)
cd awesome-robot
./gradlew test

# Build and deploy to robot
./build.sh
./deploy.sh --wifi
```

### 🔧 Project Management
```bash
# Upgrade project infrastructure
weevil upgrade awesome-robot

# View/change SDK configuration
weevil config awesome-robot
weevil config awesome-robot --set-sdk /path/to/different/sdk

# Check SDK status
weevil sdk status
```

### ✨ Smart Features
- **Per-project SDK configuration** - Different projects can use different SDK versions
- **Automatic Gradle wrapper** - No manual setup required
- **Cross-platform** - Works on Linux, macOS, and Windows
- **Zero SDK modification** - Your SDK stays pristine
- **Git-ready** - Projects initialize with proper `.gitignore`
- **Upgrade-safe** - Update build scripts without losing code

---

## Installation

### From Source

```bash
git clone https://www.nxgit.dev/nexus-workshops/weevil.git
cd weevil
cargo build --release
sudo cp target/release/weevil /usr/local/bin/

# Or add to PATH
export PATH="$PATH:$(pwd)/target/release"
```

### Prerequisites
- Rust 1.70+ (for building)
- Java 11+ (for running Gradle)
- Android SDK with platform-tools (for deployment)
- FTC SDK (Weevil can download it for you)

---

## Quick Start

### 1. Create Your First Project

```bash
weevil new my-robot
cd my-robot
```

Weevil will:
- Download the FTC SDK if needed (or use existing)
- Generate your project structure
- Set up Gradle wrapper
- Initialize git repository
- Create example test files

### 2. Write Some Code

Create `src/main/java/robot/MyOpMode.java`:

```java
package robot;

import com.qualcomm.robotcore.eventloop.opmode.TeleOp;
import com.qualcomm.robotcore.eventloop.opmode.LinearOpMode;

@TeleOp(name="My OpMode")
public class MyOpMode extends LinearOpMode {
    @Override
    public void runOpMode() {
        telemetry.addData("Status", "Initialized");
        telemetry.update();
        
        waitForStart();
        
        while (opModeIsActive()) {
            telemetry.addData("Status", "Running");
            telemetry.update();
        }
    }
}
```

### 3. Test Locally (No Robot!)

```bash
./gradlew test
```

Write unit tests in `src/test/java/robot/` that run on your PC. No need to deploy to a robot for every code change!

### 4. Deploy to Robot

```bash
# Build APK
./build.sh

# Deploy via USB
./deploy.sh --usb

# Deploy via WiFi
./deploy.sh --wifi -i 192.168.49.1

# Auto-detect (tries USB, falls back to WiFi)
./deploy.sh
```

---

## Advanced Usage

### Multiple SDK Versions

Working with multiple SDK versions? No problem:

```bash
# Create project with specific SDK
weevil new experimental-bot --ftc-sdk /path/to/sdk-v11.0

# Later, switch SDKs
weevil config experimental-bot --set-sdk /path/to/sdk-v11.1

# Rebuild with new SDK
weevil upgrade experimental-bot
cd experimental-bot
./build.sh
```

### Upgrading Projects

When Weevil releases new features:

```bash
weevil upgrade my-robot
```

This updates:
- Build scripts
- Deployment scripts
- Gradle configuration
- Project templates

**Your code in `src/` is never touched.**

### Cross-Platform Development

All scripts work on Windows, Linux, and macOS:

**Linux/Mac:**
```bash
./build.sh
./deploy.sh --wifi
```

**Windows:**
```cmd
build.bat
deploy.bat --wifi
```

---

## Project Configuration

Each project has a `.weevil.toml` file:

```toml
project_name = "my-robot"
weevil_version = "1.0.0"
ftc_sdk_path = "/home/user/.weevil/ftc-sdk"
ftc_sdk_version = "v10.1.1"
```

You can edit this manually or use:

```bash
weevil config my-robot                    # View config
weevil config my-robot --set-sdk /new/sdk # Change SDK
```

---

## Development Workflow

### Recommended Git Workflow

```bash
# Create project
weevil new competition-bot
cd competition-bot

# Project is already a git repo!
git remote add origin https://nxgit.dev/team/robot.git
git push -u origin main

# Make changes
# ... edit code ...
./gradlew test
git commit -am "Add autonomous mode"
git push

# Deploy to robot
./deploy.sh
```

### Testing Strategy

1. **Unit Tests** - Test business logic on your PC
   ```bash
   ./gradlew test
   ```

2. **Integration Tests** - Test on actual hardware
   ```bash
   ./build.sh
   ./deploy.sh --usb
   # Run via Driver Station
   ```

### Team Collaboration

**Project Structure is Portable:**
```bash
# Team member clones repo
git clone https://nxgit.dev/team/robot.git
cd robot

# Check SDK location
weevil config .

# Set SDK to local path
weevil config . --set-sdk ~/ftc-sdk

# Build and deploy
./build.sh
./deploy.sh
```

---

## Command Reference

### Project Commands

| Command | Description |
|---------|-------------|
| `weevil new <name>` | Create new FTC project |
| `weevil upgrade <path>` | Update project infrastructure |
| `weevil config <path>` | View project configuration |
| `weevil config <path> --set-sdk <sdk>` | Change FTC SDK path |

### SDK Commands

| Command | Description |
|---------|-------------|
| `weevil sdk status` | Show SDK locations and status |
| `weevil sdk install` | Download and install SDKs |
| `weevil sdk update` | Update SDKs to latest versions |

### Deployment Options

**`deploy.sh` / `deploy.bat` flags:**

| Flag | Description |
|------|-------------|
| `--usb` | Force USB deployment |
| `--wifi` | Force WiFi deployment |
| `-i <ip>` | Custom Control Hub IP |
| `--timeout <sec>` | WiFi connection timeout |

---

## Architecture

### How It Works

1. **Project Generation**
   - Creates standalone Java project structure
   - Generates Gradle build files that reference FTC SDK
   - Sets up deployment scripts

2. **Build Process**
   - Runs `deployToSDK` Gradle task
   - Copies your code to FTC SDK's `TeamCode` directory
   - Builds APK using SDK's Android configuration
   - Leaves your project directory clean

3. **Deployment**
   - Finds built APK in SDK
   - Connects to Control Hub (USB or WiFi)
   - Installs APK using `adb`

### Why This Approach?

**Separation of Concerns:**
- Your code: `my-robot/src/`
- Build infrastructure: `my-robot/*.gradle.kts`
- FTC SDK: System-level installation

**Benefits:**
- Test code without SDK complications
- Multiple projects per SDK installation
- SDK updates don't break your projects
- Proper version control (no massive SDK in repo)
- Industry-standard project structure

---

## Testing

Weevil includes comprehensive tests:

```bash
# Run all tests
cargo test

# Run specific test suites
cargo test --test integration
cargo test --test project_lifecycle
cargo test config_tests
```

**Test Coverage:**
- ✅ Project creation and structure
- ✅ Configuration persistence
- ✅ SDK detection and validation
- ✅ Build script generation
- ✅ Upgrade workflow
- ✅ CLI commands

---

## Troubleshooting

### "FTC SDK not found"

```bash
# Check SDK status
weevil sdk status

# Install SDK
weevil sdk install

# Or specify custom location
weevil new my-robot --ftc-sdk /custom/path/to/sdk
```

### "adb: command not found"

Install Android platform-tools:

**Linux:**
```bash
sudo apt install android-tools-adb
```

**macOS:**
```bash
brew install android-platform-tools
```

**Windows:**
Download Android SDK Platform Tools from Google.

### "Build failed"

```bash
# Clean and rebuild
cd my-robot
./gradlew clean
./build.sh

# Check SDK path
weevil config .
```

### "Deploy failed - No devices"

**USB:**
1. Connect robot via USB
2. Run `adb devices` to verify connection
3. Try `./deploy.sh --usb`

**WiFi:**
1. Connect to robot's WiFi network
2. Find Control Hub IP (usually 192.168.43.1 or 192.168.49.1)
3. Try `./deploy.sh -i <ip>`

---

## Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Write tests for new features
4. Ensure `cargo test` passes with zero warnings
5. Submit a pull request

### Development Setup

```bash
git clone https://www.nxgit.dev/nexus-workshops/weevil.git
cd weevil
cargo build
cargo test

# Run locally
cargo run -- new test-project
```

---

## Philosophy

**Why "Weevil"?**

Like the boll weevil that bores through complex cotton bolls to reach the valuable fibers inside, this tool bores through the complexity of the FTC SDK structure to help students reach what matters: building robots and learning to code.

**Design Principles:**

1. **Students first** - Minimize cognitive load for learners
2. **Industry practices** - Teach real software engineering
3. **Testability** - Enable TDD and proper testing workflows  
4. **Simplicity** - One command should do one obvious thing
5. **Transparency** - Students should understand what's happening

---

## License

MIT License - See [LICENSE](LICENSE) file for details.

---

## Acknowledgments

Created by Eric Ratliff for [Nexus Workshops LLC](https://nexusworkshops.com)

Built with frustration at unnecessarily complex robotics frameworks, and hope that students can focus on robotics instead of build systems.

**For FIRST Tech Challenge teams everywhere** - may your builds be fast and your deployments successful. 🤖

---

## Project Status

**Current Version:** 1.0.0-rc1

**What Works:**
- ✅ Project generation
- ✅ Cross-platform build/deploy
- ✅ SDK management
- ✅ Configuration management
- ✅ Project upgrades
- ✅ Local testing

**Roadmap:**
- 📋 Package management for FTC libraries
- 📋 Template system for common robot configurations
- 📋 IDE integration (VS Code, IntelliJ)
- 📋 Team collaboration features
- 📋 Automated testing on robot hardware

---

**Questions? Issues? Suggestions?**

📧 Email: [eric@nxws.dev](mailto:eric@nxws.dev)
🐛 Issues: Open an issue on the repository

Building better tools so you can build better robots. 🤖