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
- ✅ Work seamlessly with Android Studio
- ✅ Support proxy/air-gapped environments
- ✅ **Start from professional templates with working code** ⭐ NEW in v1.1.0!

Students focus on building robots, not navigating SDK internals.

---

## ⭐ What's New in v1.1.0

### Professional Templates - The Game Changer!

**Start with working, tested code instead of empty files!**

```bash
# Create with our professional testing showcase
weevil new my-robot --template testing

cd my-robot
./gradlew test    # 45 tests pass in < 2 seconds ✓
```

**You get:**
- ✅ 3 complete, working subsystems
- ✅ Full hardware abstraction layer
- ✅ 45 passing tests demonstrating best practices  
- ✅ Professional documentation (6 files)
- ✅ Real patterns used in competition

**Why this matters:** Most FTC teams start with empty projects and learn by trial-and-error on hardware. Now you can learn from professional code, run tests instantly on your PC, and modify working examples for your robot.

This is the kind of code students would write if they had years of experience. Now they can START with it.

---

## Features

### 🎯 Professional Templates (v1.1.0)

```bash
# List available templates
weevil new --list-templates

# Create with basic template (minimal)
weevil new my-robot

# Create with testing template (professional showcase)
weevil new my-robot --template testing
```

**Available Templates:**

| Template | Description | Files | Tests | Perfect For |
|----------|-------------|-------|-------|-------------|
| `basic` | Minimal starting point | ~10 | 1 | Starting from scratch |
| `testing` | Professional showcase | ~30 | 45 | Learning best practices |

**Testing Template Includes:**

**Subsystems** (3 complete implementations):
- `MotorCycler` - State machine for motor cycling with timing
- `WallApproach` - Sensor-based wall approach with deceleration
- `TurnController` - Gyro-based turning with angle wraparound

**Hardware Layer** (interfaces + implementations + mocks):
- Motor controllers with FTC wrappers
- Distance sensors with test mocks
- Gyro sensors with simulation
- Clean abstraction enabling unit testing

**Tests** (45 tests, < 2 second runtime):
- Unit tests for each subsystem
- Integration tests for system behaviors
- Mock-based testing (no hardware required!)

**Documentation** (professional quality):
- `DESIGN_AND_TEST_PLAN.md` - Complete architecture
- `TESTING_GUIDE.md` - How to write tests
- `TESTING_SHOWCASE.md` - What's included
- `SOLUTION.md` - Problem-solving patterns
- `ARCHITECTURE.md` - Design decisions
- `QUICKSTART.md` - Get started in 5 minutes

### 🎯 Clean Project Structure
```
my-robot/
├── src/
│   ├── main/java/robot/     # Your robot code lives here
│   │   ├── hardware/        # Hardware interfaces (in testing template)
│   │   ├── subsystems/      # Robot subsystems (in testing template)
│   │   └── opmodes/         # OpModes
│   └── test/java/robot/     # Unit tests (run on PC!)
│       ├── hardware/        # Hardware mocks (in testing template)
│       └── subsystems/      # Subsystem tests (in testing template)
├── docs/                    # Documentation (in testing template)
├── .idea/                   # Android Studio integration
├── build.sh / build.bat     # One command to build
├── deploy.sh / deploy.bat   # One command to deploy
└── .weevil.toml            # Project configuration
```

### 🚀 Simple Commands
```bash
# Set up development environment
weevil setup

# Create a new robot project
weevil new awesome-robot                    # Basic template
weevil new awesome-robot --template testing # Testing showcase

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

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

### 🔧 Project Management
```bash
# Check system health
weevil doctor

# 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

# Remove installed components
weevil uninstall --dry-run
weevil uninstall
```

### 🌐 Proxy Support (v1.1.0)
Work behind corporate firewalls or in air-gapped environments:

```bash
# Use HTTP proxy for all downloads
weevil --proxy http://proxy.company.com:8080 setup
weevil --proxy http://proxy.company.com:8080 new my-robot

# Bypass proxy (for local/direct connections)
weevil --no-proxy setup

# Proxy auto-detected from HTTPS_PROXY/HTTP_PROXY environment variables
export HTTPS_PROXY=http://proxy:8080
weevil setup  # Uses proxy automatically
```

### 💻 Android Studio Integration (v1.1.0)
Projects work seamlessly with Android Studio:
- **One-click deployment** - Run configurations appear automatically
- **Clean file tree** - Internal directories hidden, only your code visible
- **No configuration needed** - Just open the project and hit Run

See [Android Studio Setup](#android-studio-setup) for details.

### ✨ Smart Features
- **Professional templates** - Start with tested, working code ⭐ NEW!
- **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
- **System diagnostics** - `weevil doctor` checks your environment health
- **Selective uninstall** - Remove specific components without nuking everything

---

## 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 Weevil)
- Java 11+ (for running Gradle)
- Android SDK with platform-tools (for deployment)
- FTC SDK (Weevil can install it for you)

---

## Quick Start

### 1. Set Up Your Environment

```bash
weevil setup
```

Weevil will:
- Download and install FTC SDK
- Download and install Android SDK (if needed)
- Set up Gradle wrapper
- Verify all dependencies

### 2. Create Your First Project

**Recommended: Start with the testing template**
```bash
weevil new my-robot --template testing
cd my-robot
```

**Or start minimal:**
```bash
weevil new my-robot
cd my-robot
```

### 3. Run Tests (Testing Template)

```bash
./gradlew test
```

Output:
```
BasicTest > testBasic() PASSED
MotorCyclerTest > testInitialState() PASSED
MotorCyclerTest > testCycleFromOnToOff() PASSED
... 42 more tests ...

BUILD SUCCESSFUL in 1s
45 tests passed
```

**All tests run on your PC - no robot required!**

### 4. Explore the Code (Testing Template)

```bash
# Read the overview
cat QUICKSTART.md

# Study a subsystem
cat src/main/java/robot/subsystems/WallApproach.java

# See how it's tested
cat src/test/java/robot/subsystems/WallApproachTest.java

# Check the architecture
cat DESIGN_AND_TEST_PLAN.md
```

### 5. Modify for Your Robot

```bash
# The testing template gives you working patterns to modify
# Option 1: Modify existing subsystems
vim src/main/java/robot/subsystems/WallApproach.java

# Option 2: Copy and adapt
cp src/main/java/robot/subsystems/WallApproach.java \
   src/main/java/robot/subsystems/MyApproach.java

# Run tests to verify
./gradlew test
```

### 6. Deploy to Robot

```bash
./build.sh
./deploy.sh --wifi
```

---

## Template System

### Listing Templates

```bash
weevil new --list-templates
```

Output:
```
Available templates:

  basic (default)
    Minimal FTC project structure
    Perfect for: Teams starting from scratch
    Files: ~10 | Code: ~50 lines

  testing
    Professional testing showcase with examples
    Perfect for: Learning best practices
    Files: ~30 | Code: ~2,500 lines | Tests: 45
    Includes:
      • 3 complete subsystems (MotorCycler, WallApproach, TurnController)
      • Hardware abstraction layer with mocks
      • 45 passing tests (< 2 seconds)
      • Comprehensive documentation

Usage:
  weevil new <project-name>                    # Uses basic template
  weevil new <project-name> --template testing # Uses testing template
```

### Basic Template

**Use when:** Starting from scratch, want minimal boilerplate

**What you get:**
- Clean directory structure
- Placeholder OpMode
- Basic test file
- Build/deploy scripts
- Documentation

**Files:** ~10  
**Code:** ~50 lines  
**Tests:** 1

### Testing Template

**Use when:** Want to learn professional patterns, need working examples

**What you get:**

| Category | What's Included |
|----------|-----------------|
| **Subsystems** | 3 complete implementations demonstrating real patterns |
| **Hardware** | 6 interfaces + FTC wrappers + test mocks |
| **Tests** | 45 comprehensive tests (unit + integration) |
| **Docs** | 6 professional documentation files |
| **Patterns** | State machines, hardware abstraction, testing strategies |

**Files:** ~30  
**Code:** ~2,500 lines  
**Tests:** 45 (< 2 second runtime)

**Perfect for:**
- Learning how professional FTC code is structured
- Understanding test-driven development
- Seeing working examples before writing your own
- Teaching your team best practices
- Workshops and training sessions

---

## Android Studio Setup

### Opening a Weevil Project

1. Launch Android Studio
2. Choose **Open** (not "New Project")
3. Navigate to your project directory
4. Click OK

You'll see:
- Clean file tree (only your code visible)
- Run configurations in dropdown
- One-click deployment

### First-Time: Install Shell Script Plugin

1. **File → Settings** (Ctrl+Alt+S)
2. **Plugins → Marketplace**
3. Search **"Shell Script"**
4. Install plugin (by JetBrains)
5. Restart Android Studio

### Running from Android Studio

1. Select configuration (Test, Build, Deploy)
2. Click green play button (▶)
3. Watch output in Run panel

**That's it!** Deploy to robot without leaving IDE.

---

## Advanced Usage

### Proxy Configuration

```bash
# Corporate proxy
weevil --proxy http://proxy.company.com:8080 setup

# Environment variable (auto-detected)
export HTTPS_PROXY=http://proxy:8080
weevil setup

# Bypass proxy
weevil --no-proxy setup
```

### Multiple SDK Versions

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

# Switch SDKs later
weevil config experimental-bot --set-sdk /path/to/sdk-v11.1
```

### Upgrading Projects

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

Updates build scripts, Gradle config, and IDE integration.  
**Your code in `src/` is never touched.**

### System Maintenance

```bash
weevil doctor                 # Check system health
weevil uninstall --dry-run    # Preview uninstall
weevil uninstall --only 1     # Remove specific component
```

---

## Project Configuration

`.weevil.toml`:
```toml
[project]
project_name = "my-robot"
created = "2026-02-02T10:30:00Z"
weevil_version = "1.1.0"
template = "testing"
ftc_sdk_path = "/home/user/.weevil/ftc-sdk"

[ftc]
sdk_version = "v10.1.1"

[build]
gradle_version = "8.5"
```

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

---

## Development Workflow

### Recommended Git Workflow

```bash
weevil new competition-bot --template testing
cd competition-bot

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

# Development cycle
./gradlew test              # Test locally
git commit -am "Add feature"
git push
./deploy.sh                 # Deploy to robot
```

### Learning from the Testing Template

```bash
# Create learning project
weevil new learning --template testing
cd learning

# Study the architecture
cat DESIGN_AND_TEST_PLAN.md

# Run tests and see patterns
./gradlew test

# Read a subsystem
cat src/main/java/robot/subsystems/MotorCycler.java

# Read its tests
cat src/test/java/robot/subsystems/MotorCyclerTest.java

# Copy patterns for your robot
cp src/main/java/robot/subsystems/MotorCycler.java \
   src/main/java/robot/subsystems/MySystem.java
```

---

## Command Reference

### Environment Commands

| Command | Description |
|---------|-------------|
| `weevil doctor` | Check system health |
| `weevil setup` | Install FTC SDK, Android SDK |
| `weevil setup --ftc-sdk <path>` | Install to custom location |
| `weevil uninstall` | Remove all components |
| `weevil uninstall --dry-run` | Preview uninstall |
| `weevil uninstall --only <N>` | Remove specific component |

### Project Commands

| Command | Description |
|---------|-------------|
| `weevil new <name>` | Create project (basic template) |
| `weevil new <name> --template <t>` | Create with template |
| `weevil new --list-templates` | Show available templates |
| `weevil upgrade <path>` | Update project infrastructure |
| `weevil config <path>` | View configuration |
| `weevil config <path> --set-sdk <sdk>` | Change FTC SDK |

### SDK Commands

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

### Global Flags

| Flag | Description |
|------|-------------|
| `--proxy <url>` | Use HTTP proxy |
| `--no-proxy` | Bypass proxy |

### Deployment Options

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

---

## Architecture

### How It Works

1. **Project Generation**
   - Creates standalone Java project
   - Optionally overlays template (basic/testing)
   - Generates build files referencing FTC SDK
   - Sets up deployment scripts
   - Creates Android Studio integration

2. **Build Process**
   - Copies code to FTC SDK's TeamCode
   - Builds APK using SDK
   - Leaves project directory clean

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

### Why This Approach?

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

**Benefits:**
- Test without SDK complications
- Multiple projects per SDK
- SDK updates don't break projects
- Proper version control
- Industry-standard structure
- Learn from professional examples

---

## Testing

```bash
cargo test                      # All tests
cargo test --test integration   # Integration tests
cargo test --test template_tests # Template tests
```

**Coverage:**
- ✅ Project creation
- ✅ Template extraction
- ✅ Configuration
- ✅ SDK detection
- ✅ Build scripts
- ✅ Proxy support
- ✅ 62 tests passing

---

## Troubleshooting

### "FTC SDK not found"
```bash
weevil doctor
weevil setup
```

### "adb: command not found"
```bash
weevil setup  # Installs Android SDK with adb
```

### "Build failed"
```bash
./gradlew clean
./build.sh
weevil doctor
```

### "Deploy failed - No devices"
**USB:** `./deploy.sh --usb`  
**WiFi:** `./deploy.sh -i 192.168.43.1`

### "Unknown run configuration type ShellScript"
Install Shell Script plugin in Android Studio (see [Android Studio Setup](#android-studio-setup))

---

## Contributing

Contributions welcome!

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

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

---

## Philosophy

**Why "Weevil"?**

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

**Design Principles:**

1. **Students first** - Minimize cognitive load
2. **Industry practices** - Teach real software engineering
3. **Testability** - Enable TDD workflows
4. **Simplicity** - One command, one purpose
5. **Transparency** - Students understand what's happening
6. **Tool compatibility** - Work with familiar tools
7. **Learn from examples** - Provide professional code to study

---

## License

MIT License - See [LICENSE](LICENSE)

---

## Acknowledgments

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

Built with frustration at unnecessarily complex 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.1.0

**What Works:**
- ✅ Project generation with templates
- ✅ Professional testing showcase template
- ✅ Cross-platform build/deploy
- ✅ SDK management and auto-install
- ✅ Configuration management
- ✅ Project upgrades
- ✅ Local unit testing
- ✅ System diagnostics
- ✅ Selective uninstall
- ✅ Proxy support
- ✅ Android Studio integration

**Roadmap:**
- 📋 `weevil add` - Package management system (v1.2.0)
- 📋 Community package repository
- 📋 Additional templates (mecanum, vision)
- 📋 VS Code integration
- 📋 Team collaboration features
- 📋 Multi-robot support

---

**Questions? Issues? Suggestions?**

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

Building better tools so you can build better robots. 🤖