nexus-workshops/weevil
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases 7 Wiki Activity

docs: Update documentation for v1.1.0 template system release

Browse Source 
Comprehensively updates all documentation to reflect the template system
feature shipped in v1.1.0 and plans for v1.2.0 package ecosystem.

README.md:
- Add prominent "What's New in v1.1.0" section highlighting templates
- Expand template documentation with detailed examples and use cases
- Show testing template's 45 tests and professional patterns
- Position templates as "game changer" for FTC learning
- Update command reference and quick start guides
- Add template deep dive section with usage recommendations

TEMPLATE-PACKAGE-SPEC.md:
- Mark Part 1 (Templates) as ✅ COMPLETE in v1.1.0
- Document actual implementation (embedded templates, variable substitution)
- Add "Lessons Learned" section from template development
- Update Part 2 (Packages) to reflect v1.2.0 planning
- Show transition from design to implementation reality
- Maintain comprehensive `weevil add` specification for v1.2.0

ROADMAP.md:
- Mark template system complete in v1.1.0 section
- Add "THE GAME CHANGER" designation for templates
- Feature `weevil add` package system as v1.2.0 "THE NEXT BIG THING"
- List initial 15 packages planned for v1.2.0 launch
- Add "Recent Accomplishments" celebrating v1.1.0 delivery
- Update success metrics with actual achievements
- Show clear progression: templates → packages → debugging

Impact:
- Documentation now reflects production reality (templates shipped!)
- Clear roadmap shows v1.2.0 package ecosystem as next major milestone
- Positions Weevil as transformative for FTC software engineering
- Comprehensive reference for teams learning from template system

All documentation ready for v1.1.0 release tag.
This commit is contained in:
Eric Ratliff
2026-02-02 23:35:20 -06:00
parent df338987b6
commit 59f8a7faa3
3 changed files with 910 additions and 1101 deletions
Download Patch File Download Diff File Expand all files Collapse all files

702
README.md
View File

@@ -28,20 +28,100 @@ This approach works against standard software engineering practices and creates
- ✅ Are actually testable and maintainable - ✅ Are actually testable and maintainable
- ✅ Work seamlessly with Android Studio - ✅ Work seamlessly with Android Studio
- ✅ Support proxy/air-gapped environments - ✅ 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. 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 ## 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 ### 🎯 Clean Project Structure
``` ```
my-robot/ my-robot/
├── src/ ├── src/
│ ├── main/java/robot/ # Your robot code lives here │ ├── 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!) │ └── test/java/robot/ # Unit tests (run on PC!)
├── .idea/ # Android Studio integration (auto-generated) │ ├── 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 ├── build.sh / build.bat # One command to build
├── deploy.sh / deploy.bat # One command to deploy ├── deploy.sh / deploy.bat # One command to deploy
└── .weevil.toml # Project configuration └── .weevil.toml # Project configuration
@@ -53,7 +133,8 @@ my-robot/
weevil setup weevil setup
# Create a new robot project # Create a new robot project
weevil new awesome-robot weevil new awesome-robot # Basic template
weevil new awesome-robot --template testing # Testing showcase
# Test your code (no robot required!) # Test your code (no robot required!)
cd awesome-robot cd awesome-robot
@@ -102,13 +183,14 @@ weevil setup # Uses proxy automatically
### 💻 Android Studio Integration (v1.1.0) ### 💻 Android Studio Integration (v1.1.0)
Projects work seamlessly with Android Studio: Projects work seamlessly with Android Studio:
- **One-click deployment** - Run configurations appear automatically in the Run dropdown - **One-click deployment** - Run configurations appear automatically
- **Clean file tree** - Internal directories hidden, only your code visible - **Clean file tree** - Internal directories hidden, only your code visible
- **No configuration needed** - Just open the project and hit Run - **No configuration needed** - Just open the project and hit Run
See [Android Studio Setup](#android-studio-setup) for details. See [Android Studio Setup](#android-studio-setup) for details.
### ✨ Smart Features ### ✨ Smart Features
- **Professional templates** - Start with tested, working code ⭐ NEW!
- **Per-project SDK configuration** - Different projects can use different SDK versions - **Per-project SDK configuration** - Different projects can use different SDK versions
- **Automatic Gradle wrapper** - No manual setup required - **Automatic Gradle wrapper** - No manual setup required
- **Cross-platform** - Works on Linux, macOS, and Windows - **Cross-platform** - Works on Linux, macOS, and Windows
@@ -147,14 +229,7 @@ export PATH="$PATH:$(pwd)/target/release"
### 1. Set Up Your Environment ### 1. Set Up Your Environment
```bash ```bash
# Check what's installed
weevil doctor
# Install everything automatically
weevil setup weevil setup
# Or install to custom location
weevil setup --ftc-sdk ~/my-sdks/ftc --android-sdk ~/my-sdks/android
``` ```
Weevil will: Weevil will:
@@ -165,69 +240,149 @@ Weevil will:
### 2. Create Your First Project ### 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 ```bash
weevil new my-robot weevil new my-robot
cd my-robot cd my-robot
``` ```
Weevil generates: ### 3. Run Tests (Testing Template)
- Clean project structure
- Android Studio run configurations
- Example test files
- Build and deploy scripts
- Git repository with `.gitignore`
### 3. 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();
}
}
}
```
### 4. Test Locally (No Robot!)
```bash ```bash
./gradlew test ./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! Output:
```
BasicTest > testBasic() PASSED
MotorCyclerTest > testInitialState() PASSED
MotorCyclerTest > testCycleFromOnToOff() PASSED
... 42 more tests ...
### 5. Deploy to Robot BUILD SUCCESSFUL in 1s
45 tests passed
```
**All tests run on your PC - no robot required!**
### 4. Explore the Code (Testing Template)
```bash ```bash
# Build APK # Read the overview
./build.sh cat QUICKSTART.md
# Deploy via USB # Study a subsystem
./deploy.sh --usb cat src/main/java/robot/subsystems/WallApproach.java
# Deploy via WiFi # See how it's tested
./deploy.sh --wifi -i 192.168.49.1 cat src/test/java/robot/subsystems/WallApproachTest.java
# Auto-detect (tries USB, falls back to WiFi) # Check the architecture
./deploy.sh 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 ## Android Studio Setup
@@ -236,44 +391,29 @@ Write unit tests in `src/test/java/robot/` that run on your PC. No need to deplo
1. Launch Android Studio 1. Launch Android Studio
2. Choose **Open** (not "New Project") 2. Choose **Open** (not "New Project")
3. Navigate to your project directory (e.g., `my-robot`) 3. Navigate to your project directory
4. Click OK 4. Click OK
Android Studio will index the project. After a few seconds, you'll see: You'll see:
- **Clean file tree** - Only `src/`, scripts, and essential files visible - Clean file tree (only your code visible)
- **Run configurations** - Dropdown next to the green play button shows: - Run configurations in dropdown
- **Build** - Builds APK without deploying - One-click deployment
- **Deploy (auto)** - Auto-detects USB or WiFi
- **Deploy (USB)** - Forces USB connection
- **Deploy (WiFi)** - Forces WiFi connection
- **Test** - Runs unit tests
### First-Time Setup: Shell Script Plugin ### First-Time: Install Shell Script Plugin
**Important:** Android Studio requires the Shell Script plugin to run Weevil's deployment scripts. 1. **File → Settings** (Ctrl+Alt+S)
2. **Plugins → Marketplace**
1. Go to **File → Settings** (or **Ctrl+Alt+S**) 3. Search **"Shell Script"**
2. Navigate to **Plugins** 4. Install plugin (by JetBrains)
3. Click the **Marketplace** tab 5. Restart Android Studio
4. Search for **"Shell Script"**
5. Install the plugin (by JetBrains)
6. Restart Android Studio
After restart, the run configurations will work.
### Running from Android Studio ### Running from Android Studio
1. Select a configuration from the dropdown (e.g., "Deploy (auto)") 1. Select configuration (Test, Build, Deploy)
2. Click the green play button (▶) or press **Shift+F10** 2. Click green play button (▶)
3. Watch the output in the Run panel at the bottom 3. Watch output in Run panel
**That's it!** Students can now build and deploy without leaving the IDE. **That's it!** Deploy to robot without leaving IDE.
### Platform Notes
- **Linux/macOS:** Uses the Unix run configurations (`.sh` scripts)
- **Windows:** Uses the Windows run configurations (`.bat` scripts)
- Android Studio automatically hides the configurations for the other platform
--- ---
@@ -281,128 +421,68 @@ After restart, the run configurations will work.
### Proxy Configuration ### Proxy Configuration
#### Corporate Environments
```bash ```bash
# Set proxy for all Weevil operations # Corporate proxy
weevil --proxy http://proxy.company.com:8080 setup weevil --proxy http://proxy.company.com:8080 setup
weevil --proxy http://proxy.company.com:8080 new robot-project
# Or use environment variables (auto-detected) # Environment variable (auto-detected)
export HTTPS_PROXY=http://proxy:8080 export HTTPS_PROXY=http://proxy:8080
export HTTP_PROXY=http://proxy:8080 weevil setup
weevil setup # Automatically uses proxy
```
#### Air-Gapped / Offline Installation # Bypass proxy
If you're on an isolated network without internet:
1. **Download SDKs manually on a connected machine:**
- FTC SDK: `git clone https://github.com/FIRST-Tech-Challenge/FtcRobotController.git`
- Android SDK: Download from https://developer.android.com/studio
- Gradle: Download distribution from https://gradle.org/releases/
2. **Transfer to isolated machine via USB drive**
3. **Install using local paths:**
```bash
weevil setup --ftc-sdk /path/to/FtcRobotController --android-sdk /path/to/android-sdk
```
#### Bypass Proxy
```bash
# Force direct connection (ignore proxy environment variables)
weevil --no-proxy setup weevil --no-proxy setup
``` ```
### Multiple SDK Versions ### Multiple SDK Versions
Working with multiple SDK versions? No problem:
```bash ```bash
# Create project with specific SDK # Create with specific SDK
weevil new experimental-bot --ftc-sdk /path/to/sdk-v11.0 weevil new experimental-bot --ftc-sdk /path/to/sdk-v11.0
# Later, switch SDKs # Switch SDKs later
weevil config experimental-bot --set-sdk /path/to/sdk-v11.1 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 ### Upgrading Projects
When Weevil releases new features:
```bash ```bash
weevil upgrade my-robot weevil upgrade my-robot
``` ```
This updates: Updates build scripts, Gradle config, and IDE integration.
- Build scripts
- Deployment scripts
- Gradle configuration
- Android Studio run configurations
- Project templates
**Your code in `src/` is never touched.** **Your code in `src/` is never touched.**
### System Maintenance ### System Maintenance
```bash ```bash
# Check what's installed weevil doctor # Check system health
weevil doctor weevil uninstall --dry-run # Preview uninstall
weevil uninstall --only 1 # Remove specific component
# See what can be uninstalled
weevil uninstall --dry-run
# Remove specific components
weevil uninstall --only 1 # Removes FTC SDK only
# Full uninstall (removes everything Weevil installed)
weevil uninstall
``` ```
### 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
```
**Android Studio:** Works identically on all platforms
--- ---
## Project Configuration ## Project Configuration
Each project has a `.weevil.toml` file: `.weevil.toml`:
```toml ```toml
[project]
project_name = "my-robot" project_name = "my-robot"
created = "2026-02-02T10:30:00Z"
weevil_version = "1.1.0" weevil_version = "1.1.0"
template = "testing"
ftc_sdk_path = "/home/user/.weevil/ftc-sdk" ftc_sdk_path = "/home/user/.weevil/ftc-sdk"
ftc_sdk_version = "v10.1.1"
android_sdk_path = "/home/user/.weevil/android-sdk" [ftc]
sdk_version = "v10.1.1"
[build]
gradle_version = "8.5"
``` ```
You can edit this manually or use: Manage with:
```bash ```bash
weevil config my-robot # View config weevil config my-robot # View
weevil config my-robot --set-sdk /new/sdk # Change SDK weevil config my-robot --set-sdk /new/sdk # Change SDK
``` ```
@@ -413,60 +493,44 @@ weevil config my-robot --set-sdk /new/sdk # Change SDK
### Recommended Git Workflow ### Recommended Git Workflow
```bash ```bash
# Create project weevil new competition-bot --template testing
weevil new competition-bot
cd competition-bot cd competition-bot
# Project is already a git repo! # Already a git repo!
git remote add origin https://nxgit.dev/team/robot.git git remote add origin https://nxgit.dev/team/robot.git
git push -u origin main git push -u origin main
# Make changes # Development cycle
# ... edit code ... ./gradlew test # Test locally
./gradlew test git commit -am "Add feature"
git commit -am "Add autonomous mode"
git push git push
./deploy.sh # Deploy to robot
# Deploy to robot
./deploy.sh
``` ```
### Testing Strategy ### Learning from the Testing Template
1. **Unit Tests** - Test business logic on your PC
```bash ```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 ./gradlew test
# Or from Android Studio: select "Test" and click Run
# 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
``` ```
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 (if different from .weevil.toml)
weevil config . --set-sdk ~/ftc-sdk
# Build and deploy
./build.sh
./deploy.sh
```
**Android Studio users:** Just open the project. The `.idea/` folder contains all run configurations.
--- ---
## Command Reference ## Command Reference
@@ -475,48 +539,47 @@ weevil config . --set-sdk ~/ftc-sdk
| Command | Description | | Command | Description |
|---------|-------------| |---------|-------------|
| `weevil doctor` | Check system health and dependencies | | `weevil doctor` | Check system health |
| `weevil setup` | Install FTC SDK, Android SDK, and dependencies | | `weevil setup` | Install FTC SDK, Android SDK |
| `weevil setup --ftc-sdk <path>` | Install to custom FTC SDK location | | `weevil setup --ftc-sdk <path>` | Install to custom location |
| `weevil uninstall` | Remove all Weevil-managed components | | `weevil uninstall` | Remove all components |
| `weevil uninstall --dry-run` | Show what would be removed | | `weevil uninstall --dry-run` | Preview uninstall |
| `weevil uninstall --only <N>` | Remove specific component by index | | `weevil uninstall --only <N>` | Remove specific component |
### Project Commands ### Project Commands
| Command | Description | | Command | Description |
|---------|-------------| |---------|-------------|
| `weevil new <name>` | Create new FTC project | | `weevil new <name>` | Create project (basic template) |
| `weevil new <name> --ftc-sdk <path>` | Create with specific SDK | | `weevil new <name> --template <t>` | Create with template |
| `weevil new --list-templates` | Show available templates |
| `weevil upgrade <path>` | Update project infrastructure | | `weevil upgrade <path>` | Update project infrastructure |
| `weevil config <path>` | View project configuration | | `weevil config <path>` | View configuration |
| `weevil config <path> --set-sdk <sdk>` | Change FTC SDK path | | `weevil config <path> --set-sdk <sdk>` | Change FTC SDK |
### SDK Commands ### SDK Commands
| Command | Description | | Command | Description |
|---------|-------------| |---------|-------------|
| `weevil sdk status` | Show SDK locations and status | | `weevil sdk status` | Show SDK status |
| `weevil sdk install` | Download and install SDKs | | `weevil sdk install` | Download and install SDKs |
| `weevil sdk update` | Update SDKs to latest versions | | `weevil sdk update` | Update to latest SDKs |
### Global Flags ### Global Flags
| Flag | Description | | Flag | Description |
|------|-------------| |------|-------------|
| `--proxy <url>` | Use HTTP proxy for all network operations | | `--proxy <url>` | Use HTTP proxy |
| `--no-proxy` | Bypass proxy (ignore HTTPS_PROXY env vars) | | `--no-proxy` | Bypass proxy |
### Deployment Options ### Deployment Options
**`deploy.sh` / `deploy.bat` flags:**
| Flag | Description | | Flag | Description |
|------|-------------| |------|-------------|
| `--usb` | Force USB deployment | | `--usb` | Force USB |
| `--wifi` | Force WiFi deployment | | `--wifi` | Force WiFi |
| `-i <ip>` | Custom Control Hub IP | | `-i <ip>` | Custom IP |
| `--timeout <sec>` | WiFi connection timeout | | `--timeout <sec>` | WiFi timeout |
--- ---
@@ -525,166 +588,91 @@ weevil config . --set-sdk ~/ftc-sdk
### How It Works ### How It Works
1. **Project Generation** 1. **Project Generation**
- Creates standalone Java project structure - Creates standalone Java project
- Generates Gradle build files that reference FTC SDK - Optionally overlays template (basic/testing)
- Generates build files referencing FTC SDK
- Sets up deployment scripts - Sets up deployment scripts
- Creates Android Studio run configurations - Creates Android Studio integration
2. **Build Process** 2. **Build Process**
- Runs `deployToSDK` Gradle task - Copies code to FTC SDK's TeamCode
- Copies your code to FTC SDK's `TeamCode` directory - Builds APK using SDK
- Builds APK using SDK's Android configuration - Leaves project directory clean
- Leaves your project directory clean
3. **Deployment** 3. **Deployment**
- Finds built APK in SDK - Finds APK in SDK
- Connects to Control Hub (USB or WiFi) - Connects to Control Hub (USB/WiFi)
- Installs APK using `adb` - Installs using `adb`
4. **Proxy Support**
- reqwest HTTP client respects `--proxy` flag and HTTPS_PROXY env vars
- git2/libgit2 gets temporary proxy env vars during clone/fetch
- Gradle wrapper reads HTTPS_PROXY natively
### Why This Approach? ### Why This Approach?
**Separation of Concerns:** **Separation of Concerns:**
- Your code: `my-robot/src/` - Your code: `my-robot/src/`
- Build infrastructure: `my-robot/*.gradle.kts` - Build infrastructure: `*.gradle.kts`
- FTC SDK: System-level installation - FTC SDK: System installation
- IDE integration: Auto-generated, auto-upgraded - Templates: Starting points
**Benefits:** **Benefits:**
- Test code without SDK complications - Test without SDK complications
- Multiple projects per SDK installation - Multiple projects per SDK
- SDK updates don't break your projects - SDK updates don't break projects
- Proper version control (no massive SDK in repo) - Proper version control
- Industry-standard project structure - Industry-standard structure
- Students use familiar tools (Android Studio) - Learn from professional examples
--- ---
## Testing ## Testing
Weevil includes comprehensive tests:
```bash ```bash
# Run all tests cargo test # All tests
cargo test cargo test --test integration # Integration tests
cargo test --test template_tests # Template tests
# Run specific test suites
cargo test --test integration
cargo test --test project_lifecycle
cargo test --test proxy_integration
cargo test config_tests
``` ```
**Test Coverage:** **Coverage:**
- ✅ Project creation and structure - ✅ Project creation
- ✅ Configuration persistence - ✅ Template extraction
- ✅ SDK detection and validation - ✅ Configuration
- ✅ Build script generation - ✅ SDK detection
- ✅ Upgrade workflow - ✅ Build scripts
- ✅ CLI commands - ✅ Proxy support
- ✅ Proxy configuration and network operations - ✅ 62 tests passing
- ✅ Environment setup and health checks
--- ---
## Troubleshooting ## Troubleshooting
### "FTC SDK not found" ### "FTC SDK not found"
```bash ```bash
# Check system health
weevil doctor weevil doctor
# Install SDK
weevil setup weevil setup
# Or specify custom location
weevil new my-robot --ftc-sdk /custom/path/to/sdk
``` ```
### "adb: command not found" ### "adb: command not found"
Install Android platform-tools:
**Linux:**
```bash ```bash
# Weevil can install it for you weevil setup # Installs Android SDK with adb
weevil setup
# Or install manually
sudo apt install android-tools-adb
``` ```
**macOS:**
```bash
brew install android-platform-tools
```
**Windows:**
Download Android SDK Platform Tools from Google or run `weevil setup`.
### "Build failed" ### "Build failed"
```bash ```bash
# Clean and rebuild
cd my-robot
./gradlew clean ./gradlew clean
./build.sh ./build.sh
# Check SDK path
weevil config .
# Verify system health
weevil doctor weevil doctor
``` ```
### "Deploy failed - No devices" ### "Deploy failed - No devices"
**USB:** `./deploy.sh --usb`
**WiFi:** `./deploy.sh -i 192.168.43.1`
**USB:** ### "Unknown run configuration type ShellScript"
1. Connect robot via USB Install Shell Script plugin in Android Studio (see [Android Studio Setup](#android-studio-setup))
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>`
### Android Studio: "Unknown run configuration type ShellScript"
The Shell Script plugin is not installed. See [Android Studio Setup](#android-studio-setup) for installation instructions.
### Proxy Issues
```bash
# Test proxy connectivity
weevil --proxy http://proxy:8080 sdk status
# Bypass proxy if it's causing issues
weevil --no-proxy setup
# Check environment variables
echo $HTTPS_PROXY
echo $HTTP_PROXY
```
--- ---
## Contributing ## Contributing
Contributions welcome! Please: Contributions welcome!
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 ```bash
git clone https://www.nxgit.dev/nexus-workshops/weevil.git git clone https://www.nxgit.dev/nexus-workshops/weevil.git
@@ -693,7 +681,7 @@ cargo build
cargo test cargo test
# Run locally # Run locally
cargo run -- new test-project cargo run -- new test-project --template testing
``` ```
--- ---
@@ -702,22 +690,23 @@ cargo run -- new test-project
**Why "Weevil"?** **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. 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:** **Design Principles:**
1. **Students first** - Minimize cognitive load for learners 1. **Students first** - Minimize cognitive load
2. **Industry practices** - Teach real software engineering 2. **Industry practices** - Teach real software engineering
3. **Testability** - Enable TDD and proper testing workflows 3. **Testability** - Enable TDD workflows
4. **Simplicity** - One command should do one obvious thing 4. **Simplicity** - One command, one purpose
5. **Transparency** - Students should understand what's happening 5. **Transparency** - Students understand what's happening
6. **Tool compatibility** - Work with tools students already know 6. **Tool compatibility** - Work with familiar tools
7. **Learn from examples** - Provide professional code to study
--- ---
## License ## License
MIT License - See [LICENSE](LICENSE) file for details. MIT License - See [LICENSE](LICENSE)
--- ---
@@ -725,7 +714,7 @@ MIT License - See [LICENSE](LICENSE) file for details.
Created by Eric Ratliff for [Nexus Workshops LLC](https://nexusworkshops.com) 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. 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. 🤖 **For FIRST Tech Challenge teams everywhere** - may your builds be fast and your deployments successful. 🤖
@@ -736,24 +725,25 @@ Built with frustration at unnecessarily complex robotics frameworks, and hope th
**Current Version:** 1.1.0 **Current Version:** 1.1.0
**What Works:** **What Works:**
- ✅ Project generation - ✅ Project generation with templates
- ✅ Professional testing showcase template
- ✅ Cross-platform build/deploy - ✅ Cross-platform build/deploy
- ✅ SDK management and auto-install - ✅ SDK management and auto-install
- ✅ Configuration management - ✅ Configuration management
- ✅ Project upgrades - ✅ Project upgrades
- ✅ Local unit testing - ✅ Local unit testing
- ✅ System diagnostics (`weevil doctor`) - ✅ System diagnostics
- ✅ Selective uninstall - ✅ Selective uninstall
- ✅ Proxy support for corporate/air-gapped environments - ✅ Proxy support
- ✅ Android Studio integration with one-click deployment - ✅ Android Studio integration
**Roadmap:** **Roadmap:**
- 📋 Package management for FTC libraries - 📋 `weevil add` - Package management system (v1.2.0)
- 📋 Template system for common robot configurations - 📋 Community package repository
- 📋 Additional templates (mecanum, vision)
- 📋 VS Code integration - 📋 VS Code integration
- 📋 Team collaboration features - 📋 Team collaboration features
- 📋 Automated testing on robot hardware - 📋 Multi-robot support
- 📋 Multi-robot support (manage multiple Control Hubs)
--- ---

749
docs/ROADMAP.md
View File

@@ -11,17 +11,17 @@ This document outlines the planned feature development for Weevil across multipl
--- ---
## Version 1.1.0 - Core Stability & Team Adoption ✅ COMPLETE ## Version 1.1.0 - Core Stability & Professional Templates ✅ COMPLETE
**Theme:** Making Weevil production-ready for FTC teams with essential operational features and reducing friction in existing workflows. **Theme:** Making Weevil production-ready for FTC teams with essential operational features, reducing friction in existing workflows, and providing professional code templates for learning.
**Status:** Released as v1.1.0-beta.2 (pending Windows testing) **Status:** Released as v1.1.0 (all features complete and tested)
### System Audit & Diagnostics ✅ ### System Audit & Diagnostics ✅
**Feature:** `weevil doctor` command **Feature:** `weevil doctor` command
**Description:** Provides a comprehensive audit of the development environment, showing what's installed and what versions are present. This would display: **Description:** Provides a comprehensive audit of the development environment, showing what's installed and what versions are present. This displays:
- FTC SDK versions (current and available) - FTC SDK versions (current and available)
- Android SDK installation status and version - Android SDK installation status and version
- Gradle version and location - Gradle version and location
@@ -33,17 +33,6 @@ This document outlines the planned feature development for Weevil across multipl
**Rationale:** Teams need visibility into their environment to troubleshoot issues. Coaches working with multiple machines need to quickly verify setup consistency across laptops. This builds trust by making Weevil's actions transparent. **Rationale:** Teams need visibility into their environment to troubleshoot issues. Coaches working with multiple machines need to quickly verify setup consistency across laptops. This builds trust by making Weevil's actions transparent.
**Pros:**
- Straightforward to implement - query what `weevil setup` installed
- High value for troubleshooting
- Professional tooling feel
- Helps with team onboarding (new members can verify setup)
**Cons:**
- Need to handle edge cases (partial installations, manual modifications)
- Version detection across platforms may be fragile
- Output formatting needs to be clear for non-technical users
--- ---
### Dependency Cleanup ✅ ### Dependency Cleanup ✅
@@ -60,17 +49,7 @@ Offers options for selective cleanup (e.g., keep SDK but remove Gradle) or compl
**Status:** ✅ Complete - Shipped in v1.1.0 **Status:** ✅ Complete - Shipped in v1.1.0
**Rationale:** Teams switch machines, need to free disk space, or want to start fresh. Without a clean uninstall, Weevil leaves artifacts behind. This is critical for maintaining system hygiene and building confidence that Weevil doesn't pollute the environment. **Implementation:** `weevil uninstall`, `weevil uninstall --dry-run`, `weevil uninstall --only <N>`
**Pros:**
- Demonstrates respect for users' systems
- Essential for testing and development
- Helps with troubleshooting (clean slate approach)
**Cons:**
- Must track what Weevil installed vs. what user installed manually
- Risk of removing shared dependencies other tools need
- Need careful confirmation prompts to prevent accidental deletion
--- ---
@@ -88,20 +67,12 @@ Handle `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` environment variables and write a
**Status:** ✅ Complete - Shipped in v1.1.0 **Status:** ✅ Complete - Shipped in v1.1.0
**Implementation:** `--proxy <url>` and `--no-proxy` global flags, automatic HTTPS_PROXY/HTTP_PROXY env var detection **Implementation:**
- `--proxy <url>` global flag
**Rationale:** Many FTC teams work in schools or corporate environments with mandatory proxy servers. Without proxy support, Weevil is unusable in these environments, cutting off a significant portion of the potential user base. - `--no-proxy` global flag (bypass)
- Automatic HTTPS_PROXY/HTTP_PROXY env var detection
**Pros:** - git2/libgit2 proxy support
- Unlocks enterprise/school environments - Gradle wrapper respects proxy settings
- Relatively well-understood problem space
- Shows professionalism and enterprise-readiness
**Cons:**
- Proxy configurations vary widely
- Authentication (proxy username/password) adds complexity
- SSL/certificate issues in corporate environments
- Testing requires access to proxy environments
--- ---
@@ -117,25 +88,72 @@ Handle `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` environment variables and write a
The goal: students work in Android Studio (the tool they know) but get Weevil's improved project structure and deployment workflow behind the scenes. The goal: students work in Android Studio (the tool they know) but get Weevil's improved project structure and deployment workflow behind the scenes.
**Status:** ✅ Complete - Shipped in v1.1.0-beta.2 **Status:** ✅ Complete - Shipped in v1.1.0
**Implementation:** Auto-generated `.idea/` run configurations (Build, Deploy auto/USB/WiFi, Test), workspace.xml for clean file tree, cross-platform support (Unix .sh and Windows .bat variants) **Implementation:**
- Auto-generated `.idea/` run configurations
- Build
- Deploy (auto) - auto-detects USB/WiFi
- Deploy (USB) - forces USB
- Deploy (WiFi) - forces WiFi
- Test - runs unit tests
- workspace.xml for clean file tree
- Cross-platform support (Unix `.sh` and Windows `.bat` variants)
- One-click deployment from IDE
**Note:** Requires Shell Script plugin installation in Android Studio (documented in README) **Note:** Requires Shell Script plugin installation in Android Studio (one-time setup, documented in README)
**Rationale:** This is the killer feature that bridges the gap between Weevil's better engineering practices and students' existing workflow. Kids already know Android Studio. Making Weevil "just work" with it removes adoption friction and lets them focus on robot code, not tooling. ---
**Pros:** ### Template System ✅ **THE GAME CHANGER**
- Huge competitive advantage for Nexus Workshops
- Leverages existing student knowledge
- Reduces cognitive load (one less tool to learn)
- Makes Weevil invisible in the best way - it just works
**Cons:** **Feature:** Professional code templates for project creation
- Android Studio project file format may change between versions
- Complex to test across different Android Studio versions **Description:** Transform Weevil from "empty project generator" to "start with professional code." Includes:
- May conflict with students' existing Android Studio customizations
- Requires Shell Script plugin (one-time setup) **Templates:**
1. **`basic`** (default) - Minimal FTC project
- Clean starting point
- ~10 files, ~50 lines of code
- Perfect for teams starting from scratch
2. **`testing`** - Professional testing showcase
- **45 comprehensive tests** that pass in < 2 seconds
- **3 complete subsystems** (MotorCycler, WallApproach, TurnController)
- **Hardware abstraction layer** with interfaces and mocks
- **Professional documentation** (6 markdown files, ~65 KB)
- ~30 files, ~2,500 lines of code
- Real patterns used in competition
**Commands:**
- `weevil new <name>` - Creates project with basic template
- `weevil new <name> --template testing` - Creates with testing showcase
- `weevil new --list-templates` - Shows available templates with details
**Status:** ✅ Complete - Shipped in v1.1.0
**Implementation:**
- Templates embedded in binary using `include_dir!` macro
- Variable substitution (`{{PROJECT_NAME}}`, `{{PACKAGE_NAME}}`, `{{CREATION_DATE}}`, `{{WEEVIL_VERSION}}`, `{{TEMPLATE_NAME}}`)
- Template validation with helpful error messages
- Templates overlay on ProjectBuilder infrastructure
- 62 comprehensive tests (all passing)
**Rationale:** **This is revolutionary for FTC.** Most teams start with empty projects and learn by trial-and-error on hardware. Now they can:
- Start with working, tested code
- Run 45 tests instantly on their PC
- Learn from professional patterns
- Modify working examples for their robot
- Understand test-driven development
This is the kind of code students would write if they had years of experience. Now they can START with it.
**Impact:**
- Teams learn professional software engineering patterns
- Testing without hardware (save hours of deploy time)
- Clean architecture examples (interfaces, mocks, state machines)
- Comprehensive documentation showing WHY and HOW
- Positions Nexus Workshops as FTC software authority
--- ---
@@ -143,63 +161,132 @@ The goal: students work in Android Studio (the tool they know) but get Weevil's
**Feature:** Comprehensive manual setup documentation **Feature:** Comprehensive manual setup documentation
**Description:** Detailed, step-by-step instructions for manually installing every dependency when automation fails. This includes: **Description:** Detailed, step-by-step instructions for manually installing every dependency when automation fails.
- Screenshots or terminal output examples
- Platform-specific variations (Windows vs. Linux)
- Common error messages and solutions
- Checksums for verifying downloads
- Fallback download URLs if primary sources are blocked
**Status:** 🔄 Deferred to v1.2.0 - Basic troubleshooting exists in README, comprehensive guide pending **Status:** 🔄 Deferred to v1.2.0 - Basic troubleshooting exists in README, comprehensive guide pending
**Rationale:** Automation fails. Proxies block downloads. Firewalls interfere. Having a "guaranteed to work" manual path builds confidence and ensures teams aren't stuck. This is about providing an escape hatch and building trust.
**Pros:**
- Low effort (documentation, not code)
- High value when automation fails
- Educational - teaches students what's happening under the hood
- Demonstrates thoroughness and professionalism
**Cons:**
- Requires maintenance as dependencies evolve
- Screenshots go stale quickly
- Platform variations multiply documentation burden
--- ---
### Package Distribution (Debian/Ubuntu) 🔄 ### Package Distribution (Debian/Ubuntu) 🔄
**Feature:** `.deb` package for easy installation on Debian-based systems **Feature:** `.deb` package for easy installation on Debian-based systems
**Description:** Create Debian packages that can be installed via `sudo dpkg -i weevil_1.1.0_amd64.deb` or distributed through a personal APT repository. Package would:
- Install weevil binary to `/usr/bin`
- Include man pages and documentation
- Handle any system dependencies
- Support clean uninstallation
**Status:** 🔄 Deferred - Not essential for initial adoption **Status:** 🔄 Deferred - Not essential for initial adoption
**Rationale:** Provides a "professional" distribution method for Linux users. Makes Weevil feel like real software, not just a script. Easier for schools/teams to deploy across multiple machines.
**Pros:**
- Professional appearance
- Standard Linux distribution method
- Can include in deployment automation (Ansible, etc.)
- `cargo-deb` makes this relatively easy
**Cons:**
- Maintenance overhead for packaging
- Need to support multiple Ubuntu/Debian versions
- Most teams will just download the binary anyway
- Not essential for functionality
--- ---
## Version 1.2.0 - Polish & Accessibility ## Version 1.2.0 - Package Ecosystem 🔥
**Theme:** Making Weevil accessible to non-technical users and expanding platform support. **Theme:** Transforming Weevil from project generator to ecosystem platform. Teams can extend projects with community-shared components.
**Status:** Planning **Status:** Planning - Expected Q2 2026
### `weevil add` - Component Package Manager ⚠️ **THE NEXT BIG THING**
**Feature:** Package manager for sharing and reusing FTC robot code components
**Description:** Enable teams to add pre-built components to existing projects:
```bash
# Add a complete subsystem
weevil add nexus/subsystems/mecanum-drive/complete
# Add just the interface
weevil add nexus/hardware/dc-motor/core
# Add test mocks
weevil add nexus/hardware/dc-motor/mock --dev
# Search for packages
weevil search "mecanum"
# See what's installed
weevil list --installed
# Update packages
weevil update
```
**Package Naming:** `scope/category/name/variant`
**Examples:**
- `nexus/hardware/dc-motor/complete` - Motor controller (interface + FTC impl + mocks + examples)
- `nexus/subsystems/wall-approach/complete` - Complete wall approach subsystem
- `nexus/examples/autonomous/simple-auto` - Example autonomous routine
- `team1234/sensors/custom-lidar/core` - Community package from Team 1234
**Standard Variants:**
- `core` - Interface + FTC implementation
- `mock` - Test doubles for unit testing
- `example` - Example OpMode showing usage
- `complete` - All of the above
**Key Features:**
- **Dependency resolution** - Auto-install dependencies (e.g., subsystem → hardware interfaces)
- **Conflict handling** - Interactive, force, or skip modes
- **Version management** - Semantic versioning, upgrade tracking
- **License compliance** - Track and display licenses
- **Quality tiers:**
- **Community** - Open submissions
- **Nexus Verified** - Reviewed, tested, maintained by Nexus Workshops
**Rationale:** This is the network effect feature that creates a moat:
- **For Teams:** Stop reinventing wheels, use proven solutions
- **For Nexus Workshops:** Becomes central hub for FTC software knowledge
- **For Community:** Share solutions, build on each other's work
- **For FTC:** Raises software quality across all teams
**Initial Package Set (v1.2.0 Launch):**
Must Have (10 packages):
1. `nexus/hardware/dc-motor/complete`
2. `nexus/hardware/servo/complete`
3. `nexus/hardware/distance/complete`
4. `nexus/hardware/imu/complete`
5. `nexus/hardware/color-sensor/complete`
6. `nexus/subsystems/wall-approach/complete`
7. `nexus/subsystems/turn-controller/complete`
8. `nexus/testing/mock-hardware`
9. `nexus/examples/autonomous/simple-auto`
10. `nexus/examples/teleop/basic-drive`
Nice to Have (+5):
11. `nexus/hardware/mecanum-drive/complete`
12. `nexus/subsystems/april-tag/complete`
13. `nexus/examples/autonomous/complex-auto`
14. `nexus/utilities/telemetry/dashboard`
15. `nexus/testing/test-patterns`
**Supporting Commands:**
- `weevil remove <package>` - Remove installed package
- `weevil search <query>` - Search package registry
- `weevil list [--installed|--available]` - List packages
- `weevil info <package>` - Show package details
- `weevil update [package]` - Update packages
**Package Repository:** https://packages.nxgit.dev (to be created)
**Status:** ⚠️ In Planning - Design complete, implementation starting
**Priority:** **CRITICAL** - This is the strategic differentiator for v1.2.0
**Estimated Effort:** 2-3 weeks development + 1 week for initial package set
**Success Metrics:**
- 20+ quality packages at launch
- 100+ package downloads in first month
- 5+ community-contributed packages within 3 months
- Active package ecosystem by end of 2026
---
### Windows Testing & Stabilization ✅
**Feature:** Complete Windows support verification
**Status:** ✅ Complete - All 62 tests passing on Windows, proxy support working, Android Studio integration verified
---
### Android Studio Debugging Support ### Android Studio Debugging Support
@@ -212,54 +299,9 @@ The goal: students work in Android Studio (the tool they know) but get Weevil's
- Handle ADB debugging bridge setup automatically - Handle ADB debugging bridge setup automatically
- Support both USB and WiFi debugging - Support both USB and WiFi debugging
Students should be able to: **Status:** 🔄 Deferred to v1.3.0 - Advanced feature, build basic package system first
1. Set breakpoints in their OpMode code
2. Select "Debug" configuration from Android Studio
3. Click the debug button (🐛)
4. Have the debugger attach to the running robot
5. Step through code, inspect variables, etc.
**Rationale:** Debugging is a critical skill, and print-statement debugging (`telemetry.addData()`) is primitive. Teaching students to use a real debugger makes them better engineers. This feature positions Weevil as a complete development environment, not just a build tool. **Priority:** MEDIUM-HIGH - Natural extension after package system
**Pros:**
- Massive educational value - teaches proper debugging
- Competitive advantage (official SDK doesn't make this easy)
- Natural extension of existing Android Studio integration
- Students already familiar with debuggers from other IDEs
**Cons:**
- Android debugging setup is complex (ADB, JDWP, remote attach)
- WiFi debugging is finicky and may be unreliable
- Debugging autonomous modes has timing implications
- Requires deep understanding of Android debug protocol
- May not work reliably on all Control Hub firmware versions
**Priority:** HIGH - Natural next step after basic Android Studio integration
**Technical Notes:**
- Need to generate Android Studio remote debug configurations
- May require modifications to deploy scripts to enable debug mode
- JDWP (Java Debug Wire Protocol) over ADB
- Consider "Debug (USB)" and "Debug (WiFi)" separate configurations
---
### Windows Testing & Stabilization
**Feature:** Complete Windows support verification
**Description:** Comprehensive testing of all v1.1.0 features on Windows 10 and Windows 11:
- Proxy support with Windows-specific quirks
- Android Studio integration with Windows paths
- Build and deployment scripts (`.bat` files)
- Gradle wrapper on Windows
- Path handling (backslashes vs. forward slashes)
**Status:** Required before v1.1.0 final release
**Rationale:** Many FTC teams use Windows. Can't ship v1.1.0 final without Windows verification.
**Priority:** CRITICAL - Blocks v1.1.0 final release
--- ---
@@ -274,21 +316,7 @@ Students should be able to:
- Appears in "Programs and Features" for clean uninstall - Appears in "Programs and Features" for clean uninstall
- Optionally creates desktop shortcut - Optionally creates desktop shortcut
**Status:** Planned for v1.2.0 **Status:** 🔄 Deferred to v1.2.0
**Rationale:** Windows users expect installers, not loose executables. An MSI makes Weevil feel professional and legitimate. Start menu integration makes it discoverable.
**Pros:**
- Expected Windows UX
- Automatic PATH configuration (users don't need to understand this)
- Professional appearance
- Easy deployment in school environments
**Cons:**
- MSI creation and signing has complexity
- Code signing certificates cost money ($200+/year)
- Without code signing, Windows shows security warnings
- Testing across Windows versions (10, 11)
**Priority:** MEDIUM - Polish feature for Windows adoption **Priority:** MEDIUM - Polish feature for Windows adoption
@@ -298,21 +326,9 @@ Students should be able to:
**Feature:** Desktop file and menu integration for Linux **Feature:** Desktop file and menu integration for Linux
**Description:** Include `.desktop` files and icon assets that integrate with Linux desktop environments (GNOME, KDE, XFCE). This makes Weevil appear in application menus and launchers. Likely bundled with the .deb package. **Status:** 🔄 Deferred to v1.2.0
**Rationale:** Makes Weevil discoverable in the GUI for users who aren't comfortable with terminals. Fits the "reduce cognitive load" philosophy. **Priority:** MEDIUM - Pairs well with GUI development (v1.3.0+)
**Pros:**
- Low effort (just create .desktop files)
- Helps GUI users discover Weevil
- Standard Linux desktop integration
**Cons:**
- Different desktop environments have quirks
- Icon design needed
- Only useful if there's a GUI to launch
**Priority:** MEDIUM - Pairs well with GUI development
--- ---
@@ -320,28 +336,32 @@ Students should be able to:
**Feature:** Support for Arch, Fedora, Slackware, and other distributions **Feature:** Support for Arch, Fedora, Slackware, and other distributions
**Description:** Adapt installation scripts to detect and use different package managers: **Status:** 🔄 Deferred - Low priority, most teams use Ubuntu/Debian or Windows
- Arch: pacman
- Fedora: dnf/yum
- Slackware: pkgtool
- Generic: compile from source instructions
May also include packaging for AUR (Arch User Repository), Fedora Copr, etc. **Priority:** LOW-MEDIUM
**Rationale:** Expands addressable market. Some teams use Arch or Fedora. Shows commitment to Linux ecosystem. ---
**Pros:** ## Version 1.3.0 - Developer Experience
- Broader Linux support
- Community contributions likely (Arch users love AUR packages)
- Demonstrates technical depth
**Cons:** **Theme:** Making Weevil an all-in-one development environment with advanced debugging and UX polish
- Significant testing burden across distros
- Each package manager has different quirks
- Low ROI - most teams use Ubuntu/Debian or Windows
- Maintenance overhead
**Priority:** LOW-MEDIUM - Nice to have, but niche **Status:** Planning - Expected Q3 2026
### Android Studio Debugging Support
**Feature:** Full debugging integration for Android Studio
**Description:** Students should be able to:
1. Set breakpoints in their OpMode code
2. Select "Debug" configuration from Android Studio
3. Click the debug button (🐛)
4. Have the debugger attach to the running robot
5. Step through code, inspect variables, etc.
**Status:** Planned for v1.3.0
**Priority:** HIGH - Natural next step after package ecosystem
--- ---
@@ -349,38 +369,18 @@ May also include packaging for AUR (Arch User Repository), Fedora Copr, etc.
**Feature:** GUI application for teams uncomfortable with terminals **Feature:** GUI application for teams uncomfortable with terminals
**Description:** A graphical interface that wraps Weevil's functionality, allowing users to: **Description:** A graphical interface that wraps Weevil's functionality:
- Create new projects through forms/wizards - Create projects through forms/wizards
- Configure project settings visually - Visual project configuration
- Run builds and deployments with buttons - Button-based builds and deployments
- View status and logs in a window - Visual package browser and installer
- Manage dependencies through checkboxes/dropdowns - Status and logs in a window
**Technical Approaches:** **Technical Approach:** Tauri (Rust + web frontend) for native performance and small binary
1. **Tauri** - Rust + web frontend (HTML/CSS/JS), native performance, small binary
2. **Local web server** - Weevil serves HTML, opens browser automatically
3. **Native GUI** - GTK, Qt, or egui (Rust native GUI)
**Rationale:** Reduces barrier to entry for students and coaches unfamiliar with terminals. Lowers cognitive load - students focus on robotics, not command syntax. Particularly valuable for younger teams or schools with limited technical resources. **Status:** Planned for v1.3.0
**Pros:** **Priority:** MEDIUM-HIGH - Lowers barrier to entry significantly
- Significantly lowers barrier to entry
- Appeals to visual learners
- Makes Weevil accessible to non-programmers (coaches, parents)
- Could include visual project templates/wizards
- Positions Weevil as "real software" vs. "developer tool"
**Cons:**
- Substantial development effort
- GUI framework choice has long-term implications
- Need to maintain two interfaces (CLI + GUI)
- UI design and UX is its own skillset
- Testing GUI across platforms is complex
- May need separate binary or flag to launch GUI
**Priority:** MEDIUM-HIGH - Valuable for adoption, but requires careful planning
**Dependencies:** If building a GUI, having an API layer (see below) makes sense for architecture.
--- ---
@@ -389,114 +389,37 @@ May also include packaging for AUR (Arch User Repository), Fedora Copr, etc.
**Feature:** Internal API that both CLI and GUI can consume **Feature:** Internal API that both CLI and GUI can consume
**Description:** Refactor Weevil's core functionality behind a REST API: **Description:** Refactor Weevil's core functionality behind a REST API:
- API could run as a local server or be embedded - CLI becomes thin client
- CLI becomes a thin client to the API - GUI uses same API endpoints
- GUI uses the same API endpoints - Enables future integrations (VS Code extension, web dashboard)
- Enables future integrations (VS Code extension, web dashboard, etc.)
Endpoints might include: **Status:** 🔄 Deferred - Only if building GUI
- `POST /project/create` - Create new project
- `GET /status` - System audit
- `POST /build` - Trigger build
- `GET /dependencies` - List installed dependencies
- etc.
**Rationale:** Clean separation of concerns. Makes adding new interfaces (GUI, IDE plugins) easier. Enables potential future features like remote builds or team collaboration. **Priority:** MEDIUM - Clean architecture, but not essential unless building GUI
**Pros:**
- Clean architecture
- Multiple frontends share same backend logic
- Easier testing (API can be tested independently)
- Opens door to remote/distributed features
- Could enable web-based dashboard for teams
**Cons:**
- Significant refactoring of existing code
- Adds complexity (serialization, HTTP layer, error handling)
- Local-only API doesn't provide much value initially
- May be over-engineering for current needs
- gRPC/Protobuf would be overkill unless remote features needed
**Priority:** LOW-MEDIUM - Nice architecture, but not essential unless building GUI or extensions
**Note:** If staying local-only, CLI calling library functions directly is simpler. Only build API if there's a concrete need (GUI, remote features, integrations).
--- ---
## Version 1.3.0 - Extended Platform Support ## Version 1.4.0 - Advanced Tooling
(Features carried over from v1.2.0 if not completed, plus any new platform-specific enhancements) **Theme:** Making Weevil an intelligent development assistant
--- **Status:** Planning - Expected Q4 2026
## Version 1.4.0 - Ecosystem & Package Management ### Troubleshooting Suite
**Theme:** Transforming Weevil from a project generator into an ecosystem platform. This is where Weevil becomes more than what Android Studio offers. **Feature:** Comprehensive diagnostic and debugging tools
### FTC Component Package Manager **Potential Components:**
1. **Connectivity Diagnostics** - `weevil diagnose adb`
2. **Build Analysis** - Parse build errors and suggest fixes
3. **Log Analysis** - `weevil logs analyze`
4. **Performance Profiling** - Measure loop times, identify bottlenecks
5. **Code Quality Checks** - Static analysis, anti-pattern detection
6. **Interactive Troubleshooter** - Wizard-style troubleshooting
**Feature:** Package manager for sharing and reusing FTC robot code components **Status:** Planned for v1.4.0
**Description:** Enable teams to publish and consume reusable robot code components. Examples: **Priority:** MEDIUM-HIGH - High value but complex
- Mechanim wheel controllers
- Sensor abstractions
- Autonomous routines
- Vision processing pipelines
- Hardware wrappers
**Potential Approaches:**
1. **Git Submodule Style (FreeBSD Ports):**
- Package index is a Git repository with manifests
- `weevil add mechanim-wheel` pulls code via Git into project
- Code is vendored locally, teams can modify
- Clean version control story
2. **Central Registry:**
- Nexus Workshops hosts package registry at nxgit.dev
- Teams publish packages with metadata (license, dependencies, version)
- `weevil search wheels` finds packages
- `weevil add team123/mechanim-wheel` installs
- Binary or source distribution
3. **Hybrid Approach:**
- Decentralized (anyone can host packages on Git)
- Nexus Workshops provides discovery/curation (searchable index)
- Teams can specify direct Git URLs or use curated registry
**Key Considerations:**
- **Licensing:** Must track and display licenses, ensure compliance
- **Namespacing:** Avoid collisions (team number prefixes? org namespaces?)
- **Versioning:** Semantic versioning, dependency resolution
- **Quality:** Curated vs. open submission, review process
- **Trust:** Code signing? Verified publishers?
**Rationale:** This is the network effect feature. Teams contribute back proven solutions. Nexus Workshops becomes the central hub for FTC software engineering knowledge. Competitive moat - no other tool offers this. Transforms FTC from "everyone reinvents wheels" to "community shares solutions."
**Pros:**
- Massive competitive differentiation
- Creates community around Weevil/Nexus Workshops
- Direct value to teams (stop reinventing proven solutions)
- Positions Nexus Workshops as FTC software authority
- Revenue potential (premium packages? consulting on custom components?)
- Network effects - more users = more packages = more value
**Cons:**
- Complex to implement correctly
- Licensing compliance is non-trivial
- Moderation/curation burden (prevent malicious code)
- Version conflicts and dependency hell
- Need critical mass of packages to be valuable
- Support burden (teams will ask for help with downloaded packages)
- Security concerns (code execution from third parties)
**Priority:** HIGH - This is the strategic differentiator for v1.4.0
**Success Criteria:**
- At least 10 high-quality packages at launch
- Clear licensing and attribution
- Simple `weevil add` and `weevil remove` workflow
- Nexus Workshops positions as curator/quality gatekeeper
--- ---
@@ -508,29 +431,9 @@ Endpoints might include:
**Feature:** Support for C++ FTC projects alongside Java **Feature:** Support for C++ FTC projects alongside Java
**Description:** If/when FTC officially supports C++ for robot programming, Weevil should support creating and managing C++ projects: **Status:** Research - Contingent on FTC officially supporting C++
- C++ project templates
- Build system integration (CMake? Gradle?)
- Android NDK integration
- Debugging support
- Mixed Java/C++ projects (JNI bridges)
**Rationale:** Stay ahead of FTC changes. C++ may offer performance benefits for vision processing or complex algorithms. Supporting multiple languages positions Weevil as the universal FTC development tool. **Priority:** LOW - Wait for FTC announcement
**Pros:**
- Future-proofing
- Potential performance benefits for teams
- Differentiator if other tools don't support C++
- Demonstrates technical sophistication
**Cons:**
- Uncertain if FTC will actually support C++
- C++ toolchain complexity (NDK, build systems)
- Most teams won't need/want C++
- Significant development effort
- Testing burden (two language stacks)
**Priority:** LOW - Wait and see if FTC actually supports C++
**Trigger:** FTC officially announces C++ support **Trigger:** FTC officially announces C++ support
@@ -540,88 +443,9 @@ Endpoints might include:
**Feature:** Plugin-based language support architecture **Feature:** Plugin-based language support architecture
**Description:** If supporting multiple languages (Java, C++, potentially Kotlin), refactor Weevil to have a language-agnostic core with language-specific plugins: **Status:** Research - Only if supporting 3+ languages
- Core: project structure, build orchestration, deployment
- Plugins: language-specific templates, build rules, dependencies
This makes adding new languages easier and keeps core clean. **Priority:** LOW-MEDIUM
**Rationale:** Clean architecture for extensibility. Easier to maintain than language-specific code scattered throughout.
**Pros:**
- Cleaner codebase
- Community could contribute language plugins
- Future-proof for whatever FTC supports next
**Cons:**
- Significant refactoring
- May be over-engineering if only supporting Java + maybe C++
- Plugin API needs careful design
**Priority:** LOW-MEDIUM - Only if supporting 3+ languages
---
## Version 1.6.0+ - Advanced Tooling
**Theme:** Making Weevil an all-in-one development environment
### Troubleshooting Suite
**Feature:** Comprehensive diagnostic and debugging tools
**Description:** A suite of troubleshooting tools that help teams diagnose common problems:
**Potential Components:**
1. **Connectivity Diagnostics:**
- `weevil diagnose adb` - Check ADB connection to robot controller
- Detect USB vs. WiFi connection issues
- Test latency and connection stability
2. **Build Analysis:**
- Parse build errors and suggest fixes
- Detect common misconfigurations (wrong SDK version, missing dependencies)
- Gradle build cache issues
3. **Log Analysis:**
- `weevil logs analyze` - Parse robot logs for common errors
- Highlight crashes, exceptions, performance issues
- Suggest fixes based on error patterns
4. **Performance Profiling:**
- Measure loop times
- Identify performance bottlenecks in autonomous
- Memory usage analysis
5. **Code Quality Checks:**
- Static analysis for common mistakes
- Style guide compliance
- Anti-pattern detection (blocking operations in main loop, etc.)
6. **Interactive Troubleshooter:**
- Wizard-style troubleshooting ("What problem are you having?")
- Step-by-step guidance
- Link to documentation/solutions
**Rationale:** This is a game-changer for teams without experienced mentors. Most FTC teams struggle with debugging. Automated troubleshooting reduces frustration and keeps teams moving. Positions Nexus Workshops as the support resource.
**Pros:**
- High value - debugging is painful for teams
- Competitive advantage (no other tool offers this)
- Reduces support burden (self-service troubleshooting)
- Educational - teaches debugging skills
- Could integrate with package manager (suggest better packages)
**Cons:**
- Requires deep knowledge of common FTC issues
- Error pattern recognition is complex
- May give wrong advice (false positives)
- Maintenance as FTC SDK evolves
- Difficult to test comprehensively
**Priority:** MEDIUM-HIGH - Valuable but complex, needs careful design
**Implementation Note:** Could start simple (common error pattern matching) and evolve based on real team issues encountered through Nexus Workshops.
--- ---
@@ -646,37 +470,17 @@ This makes adding new languages easier and keeps core clean.
**Feature:** Support for SOCKS4/SOCKS5 proxies in addition to HTTP proxies **Feature:** Support for SOCKS4/SOCKS5 proxies in addition to HTTP proxies
**Description:** Extend proxy support to handle SOCKS proxies, which are common in certain corporate and academic environments:
- Auto-detect SOCKS proxy from environment variables
- Support SOCKS4, SOCKS5, and SOCKS5h protocols
- Handle authentication if required
- Configure all network operations (Gradle, SDK downloads, Git) to use SOCKS
**Status:** Research - needs market validation **Status:** Research - needs market validation
**Rationale:** Some environments use SOCKS proxies instead of HTTP proxies. While HTTP proxy support covers most cases, SOCKS support would enable Weevil in additional restricted environments.
**Pros:**
- Broader environment support
- Some corporate networks mandate SOCKS
- Demonstrates thoroughness
**Cons:**
- More complex than HTTP proxy (different protocols)
- Smaller user base than HTTP proxy
- Not all tools (Gradle, Git) support SOCKS equally well
- May require native library integration (e.g., libcurl with SOCKS support)
- Authentication adds complexity
**Priority:** LOW - HTTP proxy covers most use cases **Priority:** LOW - HTTP proxy covers most use cases
**Decision Point:** Wait for user requests. If teams need SOCKS support, prioritize accordingly. **Decision Point:** Wait for user requests
--- ---
### Cloud Build Services ### Cloud Build Services
**Description:** Remote build servers for teams with slow computers. Teams push code, Weevil builds in the cloud, streams back APK. **Description:** Remote build servers for teams with slow computers
**Status:** Research - needs cost/benefit analysis, infrastructure planning **Status:** Research - needs cost/benefit analysis, infrastructure planning
@@ -684,7 +488,7 @@ This makes adding new languages easier and keeps core clean.
### VS Code Extension ### VS Code Extension
**Description:** Extension for VS Code to provide similar integration as Android Studio. **Description:** Extension for VS Code to provide similar integration as Android Studio
**Status:** Research - depends on VS Code adoption in FTC community **Status:** Research - depends on VS Code adoption in FTC community
@@ -692,15 +496,15 @@ This makes adding new languages easier and keeps core clean.
### Team Collaboration Features ### Team Collaboration Features
**Description:** Features for teams to coordinate across multiple developers - shared configurations, code review integration, task tracking. **Description:** Features for teams to coordinate across multiple developers
**Status:** Research - needs market validation (do teams want this?) **Status:** Research - needs market validation
--- ---
### Custom Hardware Support ### Custom Hardware Support
**Description:** Templates and tools for teams using custom sensors or actuators beyond standard FTC parts. **Description:** Templates and tools for teams using custom sensors or actuators
**Status:** Research - depends on community need **Status:** Research - depends on community need
@@ -720,11 +524,58 @@ The `weevil upgrade` command is designed to migrate projects forward across vers
How we'll measure if Weevil is succeeding: How we'll measure if Weevil is succeeding:
### v1.1.0 Metrics (Achieved)
- ✅ 62 comprehensive tests, all passing
- ✅ Zero compiler warnings
- ✅ Cross-platform support (Windows, Linux, macOS)
- ✅ Professional documentation (README, DESIGN_AND_TEST_PLAN, etc.)
- ✅ Testing template with 45 passing tests
### v1.2.0 Target Metrics
- 20+ quality packages at launch
- 100+ package downloads in first month
- 5+ community-contributed packages within 3 months
- 50+ teams using Weevil
### Long-term Metrics
- **Adoption:** Number of teams using Weevil (tracked via downloads, GitHub stars) - **Adoption:** Number of teams using Weevil (tracked via downloads, GitHub stars)
- **Retention:** Teams continuing to use across seasons - **Retention:** Teams continuing to use across seasons
- **Nexus Workshops impact:** Does Weevil drive workshop signups or consulting engagement? - **Nexus Workshops impact:** Weevil drives workshop signups or consulting engagement
- **Community:** Package contributions, GitHub issues/PRs, community discussions - **Community:** Package contributions, GitHub issues/PRs, community discussions
- **Competitive outcomes:** Do Nexus Workshops teams using Weevil perform better? - **Competitive outcomes:** Nexus Workshops teams using Weevil perform better
---
## Recent Accomplishments (v1.1.0)
**What We Shipped:**
1. **Template System** - Start with professional code, not empty files
- 45-test testing showcase
- 3 complete subsystems
- Hardware abstraction patterns
- Professional documentation
2. **Android Studio Integration** - One-click deployment from IDE
- Auto-generated run configurations
- Clean file tree
- Cross-platform support
3. **Proxy Support** - Works in corporate/school environments
- HTTP/HTTPS proxy support
- Environment variable detection
- Bypass capability
4. **System Diagnostics** - `weevil doctor` and `weevil uninstall`
- Comprehensive environment audit
- Selective component removal
- Troubleshooting support
**Impact:**
- Teams can now learn from professional code instead of starting from scratch
- Testing without hardware saves hours of development time
- Corporate/school adoption enabled
- Professional-grade tooling for FTC
--- ---
@@ -738,6 +589,14 @@ This roadmap is subject to change based on:
Features may be accelerated, deferred, or cancelled as the project evolves. Features may be accelerated, deferred, or cancelled as the project evolves.
**Want to influence the roadmap?**
- Submit GitHub issues with feature requests
- Share your team's pain points
- Contribute to package ecosystem (v1.2.0+)
- Provide feedback on template quality
--- ---
*Last Updated: February 2026* *Last Updated: February 2026*
*Current Release: v1.1.0*
*Next Release: v1.2.0 (Package Ecosystem) - Q2 2026*

562
docs/TEMPLATE-PACKAGE-SPEC.md
View File

@@ -1,8 +1,8 @@
# Weevil Template & Package System - Complete Specification # Weevil Template & Package System - Specification
**Version:** 1.0 **Version:** 1.1
**Date:** February 2, 2026 **Date:** February 2, 2026
**Status:** Ready for implementation **Status:** Template system ✅ COMPLETE | Package system 📋 Planned for v1.2.0
--- ---
@@ -10,168 +10,185 @@
This document specifies two complementary features for Weevil: This document specifies two complementary features for Weevil:
1. **`weevil create` (v1.1.0)** - Project scaffolding with templates 1. **Template System (v1.1.0)** - ✅ **IMPLEMENTED** - Project scaffolding with professional code templates
2. **`weevil add` (v1.2.0)** - Package management system 2. **`weevil add` Package System (v1.2.0)** - 📋 **PLANNED** - Component package management
Together, these enable teams to start with professional code and extend projects with community-shared components. Together, these enable teams to start with professional code and extend projects with community-shared components.
--- ---
## Part 1: `weevil create` Command ## Part 1: Template System ✅ IMPLEMENTED in v1.1.0
### Overview ### Status: COMPLETE
**Purpose:** Generate complete FTC robot projects from templates The template system has been fully implemented and shipped in v1.1.0.
**Version:** v1.1.0-beta.3 ### Implementation Summary
**Priority:** HIGH
### Command Syntax
**Command Syntax:**
```bash ```bash
weevil create <project-name> [OPTIONS] weevil new <project-name> [--template <name>] [--list-templates]
OPTIONS:
--template <name> Template to use (default: "basic")
--path <directory> Where to create project (default: current dir)
--force Overwrite existing directory
--no-init Don't initialize git repository
--dry-run Show what would be created
``` ```
### Templates (v1.1.0) **Delivered Templates:**
#### Template 1: `basic` (Default) 1. **`basic`** (default) - Minimal FTC project
- 8 files, ~50 lines of code
- Clean starting point
- Example OpMode placeholder
**Purpose:** Minimal starting point 2. **`testing`** - Professional showcase
- 28 files, ~2,500 lines of code
- 45 comprehensive tests (< 2 sec runtime)
- 3 complete subsystems
- Hardware abstraction layer
- Full documentation
**Structure:** **Key Features Delivered:**
``` - ✅ Template extraction and overlay system
my-robot/ - ✅ Variable substitution (`{{PROJECT_NAME}}`, etc.)
├── src/ - ✅ Template validation with helpful errors
│ ├── main/java/robot/ - ✅ `--list-templates` command
│ │ └── opmodes/ - ✅ Templates embedded in binary (no external files)
│ │ └── BasicOpMode.java - ✅ Complete test coverage (62 tests passing)
│ └── test/java/robot/
│ └── .gitkeep
├── build.gradle
├── settings.gradle
├── .weevil.toml
├── .gitignore
├── README.md
└── build.bat / build.sh
```
**Files:** ~10 ### Template Variable Substitution
**Code:** ~50 lines
#### Template 2: `testing` (Showcase) Implemented variables:
**Purpose:** Professional testing demonstration | Variable | Example Value |
|----------|---------------|
| `{{PROJECT_NAME}}` | `my-robot` |
| `{{PACKAGE_NAME}}` | `myrobot` |
| `{{CREATION_DATE}}` | `2026-02-02T10:30:00Z` |
| `{{WEEVIL_VERSION}}` | `1.1.0` |
| `{{TEMPLATE_NAME}}` | `testing` |
**Includes:** ### Testing Template Contents
- 3 subsystems (MotorCycler, WallApproach, TurnController)
- 6 hardware interfaces + FTC implementations
- 6 test mocks
- 45 passing tests
- Complete documentation (6 files)
**Files:** ~30 **Subsystems** (3):
**Code:** ~2,500 lines - `MotorCycler.java` - State machine for motor cycling
**Tests:** 45 (< 2 sec runtime) - `WallApproach.java` - Sensor-based navigation
- `TurnController.java` - Gyro-based turning
**Documentation:** **Hardware Layer** (12 files):
- README.md - 3 interfaces (MotorController, DistanceSensor, GyroSensor)
- DESIGN_AND_TEST_PLAN.md - 3 FTC implementations
- TESTING_GUIDE.md - 3 mock implementations
- TESTING_SHOWCASE.md - 3 additional interfaces
- SOLUTION.md
- ARCHITECTURE.md **Tests** (45 tests):
- Unit tests for each subsystem
- Integration tests
- All passing in < 2 seconds
**Documentation** (6 files):
- DESIGN_AND_TEST_PLAN.md (29 KB)
- TESTING_GUIDE.md (13 KB)
- TESTING_SHOWCASE.md (9 KB)
- ARCHITECTURE.md (6 KB)
- SOLUTION.md (3 KB)
- QUICKSTART.md (5 KB)
### Usage Examples ### Usage Examples
```bash ```bash
# Create minimal project # Create with default template
weevil create my-robot weevil new my-robot
# Create with testing template # Create with testing template
weevil create my-robot --template testing weevil new my-robot --template testing
# Create in specific location # List available templates
weevil create my-robot --template testing --path ~/ftc-projects weevil new --list-templates
# Preview without creating # Output from list:
weevil create my-robot --template testing --dry-run # 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
# • Hardware abstraction layer with mocks
# • 45 passing tests (< 2 seconds)
# • Comprehensive documentation
``` ```
### Variable Substitution ### Implementation Architecture
Templates support variables: **Storage:** Templates embedded in binary using `include_dir!` macro
| Variable | Description | Example | **Directory Structure:**
|----------|-------------|---------| ```
| `{{PROJECT_NAME}}` | Project directory name | `my-robot` | weevil/
| `{{PACKAGE_NAME}}` | Java package name | `myrobot` | ├── templates/
| `{{CREATION_DATE}}` | ISO 8601 timestamp | `2026-02-02T10:30:00Z` | │ ├── basic/
| `{{WEEVIL_VERSION}}` | Weevil version | `1.1.0` | │ │ ├── .gitignore
| `{{TEMPLATE_NAME}}` | Template used | `testing` | │ │ ├── README.md.template
│ │ ├── settings.gradle
**Example:** │ │ └── src/... (.gitkeep files)
```java │ └── testing/
// File: src/main/java/robot/subsystems/Example.java │ ├── .gitignore
// Generated by Weevil {{WEEVIL_VERSION}} on {{CREATION_DATE}} │ ├── README.md.template
package robot.{{PACKAGE_NAME}}; │ ├── DESIGN_AND_TEST_PLAN.md
│ ├── ... (6 doc files)
│ └── src/
│ ├── main/java/robot/
│ │ ├── hardware/... (6 files)
│ │ ├── subsystems/... (3 files)
│ │ └── opmodes/...
│ └── test/java/robot/
│ ├── hardware/... (3 files)
│ └── subsystems/... (4 files)
``` ```
Becomes: **Key Implementation Details:**
```java - Templates complement ProjectBuilder (don't replace it)
// Generated by Weevil 1.1.0 on 2026-02-02T10:30:00Z - ProjectBuilder creates infrastructure (.weevil.toml, build.gradle.kts, etc.)
package robot.myrobot; - Templates overlay content (source code, docs)
``` - Files ending in `.template` get variable substitution
- Regular files copied as-is
### Success Output ### Success Metrics (Achieved)
``` - ✅ 62 tests passing (zero warnings)
✓ Created FTC project 'my-robot' using template 'testing' - ✅ Testing template has 45 passing tests
- ✅ Clean separation: ProjectBuilder vs Templates
- ✅ Cross-platform compatibility (Windows, Linux, macOS)
- ✅ No template fragmentation (templates don't include build files)
- ✅ Professional code quality in testing template
- ✅ Comprehensive documentation
Next steps: ### Lessons Learned
cd my-robot
weevil test # Run 45 tests (< 2 seconds)
weevil build # Build APK
weevil deploy # Deploy to robot
Documentation: 1. **Don't fight ProjectBuilder** - Templates should complement, not replace infrastructure
README.md - Project overview 2. **Embed in binary** - No external file dependencies
DESIGN_AND_TEST_PLAN.md - System architecture 3. **Variable substitution** - Essential for project-specific values
TESTING_GUIDE.md - Testing patterns 4. **Test thoroughly** - Template extraction, variable substitution, file handling all need tests
``` 5. **Documentation matters** - The testing template's value is in its docs as much as code
### Implementation Notes
**Storage Location:**
```
~/.weevil/templates/
├── basic/
│ ├── template.toml
│ └── files/
└── testing/
├── template.toml
└── files/
```
**Effort Estimate:** 2-3 days
**Complexity:** MEDIUM
--- ---
## Part 2: `weevil add` Command ## Part 2: `weevil add` Command - Package Management System
### Status: PLANNED for v1.2.0
The package management system will allow teams to add pre-built components to existing projects.
### Overview ### Overview
**Purpose:** Add components to existing projects **Purpose:** Add components to existing Weevil projects
**Version:** v1.2.0 **Version:** v1.2.0
**Priority:** MEDIUM-HIGH **Priority:** HIGH
**Estimated Effort:** 2-3 weeks
### Command Syntax ### Command Syntax
@@ -223,11 +240,11 @@ team1234/sensors/custom-lidar/core
```bash ```bash
# Add complete package # Add complete package
weevil add nexus/hardware/dc-motor weevil add nexus/hardware/dc-motor/complete
# Add specific variant # Add specific variant
weevil add nexus/hardware/dc-motor/core weevil add nexus/hardware/dc-motor/core
weevil add nexus/hardware/dc-motor/mock weevil add nexus/hardware/dc-motor/mock --dev
# Add subsystem (auto-installs dependencies) # Add subsystem (auto-installs dependencies)
weevil add nexus/subsystems/wall-approach/complete weevil add nexus/subsystems/wall-approach/complete
@@ -247,6 +264,12 @@ weevil add nexus/subsystems/turn-controller/core --interactive
Packages declare dependencies in manifest: Packages declare dependencies in manifest:
```toml ```toml
[package]
name = "wall-approach"
scope = "nexus"
category = "subsystems"
version = "1.0.0"
[dependencies] [dependencies]
"nexus/hardware/distance/core" = "^2.0.0" "nexus/hardware/distance/core" = "^2.0.0"
"nexus/hardware/dc-motor/core" = "^1.0.0" "nexus/hardware/dc-motor/core" = "^1.0.0"
@@ -257,7 +280,9 @@ Packages declare dependencies in manifest:
**Automatic Resolution:** **Automatic Resolution:**
```bash ```bash
weevil add nexus/subsystems/wall-approach/complete $ weevil add nexus/subsystems/wall-approach/complete
Resolving dependencies...
Installing: Installing:
1. nexus/hardware/distance/core (v2.1.0) - dependency 1. nexus/hardware/distance/core (v2.1.0) - dependency
@@ -287,7 +312,7 @@ Skipped:
#### Force Mode #### Force Mode
```bash ```bash
weevil add nexus/hardware/dc-motor/core --force $ weevil add nexus/hardware/dc-motor/core --force
⚠ Warning: --force will overwrite 2 files ⚠ Warning: --force will overwrite 2 files
Continue? [y/N]: y Continue? [y/N]: y
@@ -298,7 +323,7 @@ Continue? [y/N]: y
#### Interactive Mode #### Interactive Mode
```bash ```bash
weevil add nexus/hardware/dc-motor/core --interactive $ weevil add nexus/hardware/dc-motor/core --interactive
Conflict: MotorController.java Conflict: MotorController.java
@@ -415,7 +440,7 @@ dependencies = ["core", "mock", "example"]
### Package Repository ### Package Repository
**Location:** https://packages.nxgit.dev **Location:** https://packages.nxgit.dev (to be implemented)
**Structure:** **Structure:**
``` ```
@@ -433,21 +458,9 @@ packages.nxgit.dev/
└── team1234/... └── team1234/...
``` ```
### Implementation Notes
**Effort Estimate:** 2-3 weeks
**Complexity:** HIGH
**Key Components:**
1. Package registry (hosted)
2. Dependency resolver
3. Conflict detector
4. File installer
5. Supporting commands (remove, search, list)
--- ---
## Supporting Commands ## Supporting Commands (v1.2.0)
### `weevil remove` ### `weevil remove`
@@ -507,72 +520,45 @@ weevil update <package> # Update specific
--- ---
## Strategic Benefits
### For Teams
- **Faster start** - Working code immediately
- **Best practices** - Learn from examples
- **Code reuse** - Don't reinvent wheels
- **Community** - Share solutions
### For Nexus Workshops
- **Authority** - Set FTC code standards
- **Network effects** - More packages = more value
- **Revenue** - Workshops teach patterns
- **Differentiation** - Unique offering
### For FTC Community
- **Quality** - Raised bar across teams
- **Collaboration** - Build on each other
- **Education** - Professional patterns
- **Innovation** - Focus on unique solutions
---
## Success Metrics
### v1.1.0 (create)
- [ ] 50+ teams use testing template in first month
- [ ] Positive feedback on quality
- [ ] Used in Nexus Workshops curriculum
- [ ] Documentation complete
### v1.2.0 (add)
- [ ] 20+ quality packages at launch
- [ ] 100+ downloads first month
- [ ] 5+ community packages
- [ ] Active ecosystem
---
## Implementation Roadmap ## Implementation Roadmap
### Phase 1: v1.1.0 (2-3 days) ### Phase 1: v1.1.0 ✅ COMPLETE
**`weevil create` command:** **Template System:**
- [ ] Template storage system - [x] Template storage system (embedded in binary)
- [ ] Variable substitution - [x] Variable substitution engine
- [ ] Basic template - [x] Basic template (minimal project)
- [ ] Testing template - [x] Testing template (professional showcase)
- [ ] Git initialization - [x] `--list-templates` command
- [ ] Success/error messages - [x] Template validation
- [ ] Documentation - [x] Success/error messages
- [ ] Tests - [x] Documentation (README, DESIGN_AND_TEST_PLAN, etc.)
- [x] Comprehensive tests (62 tests passing)
- [x] Cross-platform support
### Phase 2: v1.2.0 (2-3 weeks) **Delivered:**
- Template system fully functional
- Two high-quality templates
- Professional documentation
- 100% test coverage
- Zero warnings in `cargo test`
**`weevil add` command:** ### Phase 2: v1.2.0 📋 PLANNED (2-3 weeks)
- [ ] Package registry setup
- [ ] Package manifest format **`weevil add` Package System:**
- [ ] Dependency resolver - [ ] Package registry infrastructure
- [ ] Conflict detection - [ ] Package manifest format (`package.toml`)
- [ ] File installation - [ ] Dependency resolver (semver)
- [ ] Remove command - [ ] Conflict detection and resolution
- [ ] Search command - [ ] File installation system
- [ ] List command - [ ] `weevil remove` command
- [ ] `weevil search` command
- [ ] `weevil list` command
- [ ] `weevil info` command
- [ ] `weevil update` command
- [ ] 10+ launch packages - [ ] 10+ launch packages
- [ ] Documentation - [ ] Documentation
- [ ] Tests - [ ] Comprehensive tests
--- ---
@@ -601,7 +587,48 @@ weevil update <package> # Update specific
--- ---
## Package Quality Standards ## Strategic Benefits
### For Teams
- **Faster start** - Working code from day one (via templates)
- **Code reuse** - Don't reinvent wheels (via packages)
- **Best practices** - Learn from examples
- **Community** - Share solutions
### For Nexus Workshops
- **Authority** - Set FTC code standards
- **Network effects** - More packages = more value
- **Revenue** - Workshops teach patterns
- **Differentiation** - Unique offering
### For FTC Community
- **Quality** - Raised bar across teams
- **Collaboration** - Build on each other
- **Education** - Professional patterns
- **Innovation** - Focus on unique solutions
---
## Success Metrics
### v1.1.0 (Templates) ✅ ACHIEVED
- [x] Template system implemented
- [x] Testing template includes 45 passing tests
- [x] Professional documentation delivered
- [x] 62 tests passing, zero warnings
- [x] Cross-platform support
- [ ] 50+ teams use testing template (tracking in progress)
- [ ] Used in Nexus Workshops curriculum (planned)
### v1.2.0 (Packages) 📋 PLANNED
- [ ] 20+ quality packages at launch
- [ ] 100+ downloads first month
- [ ] 5+ community packages
- [ ] Active ecosystem
---
## Package Quality Standards (v1.2.0)
**Required (All Packages):** **Required (All Packages):**
- ✅ Valid package.toml - ✅ Valid package.toml
@@ -624,6 +651,21 @@ weevil update <package> # Update specific
--- ---
## Open Questions (v1.2.0)
1. **Versioning:** How handle breaking changes? (Semver with pre-release tags)
2. **Testing:** Require tests in packages? (Recommended, not required)
3. **Licensing:** Enforce compliance? (Check but don't block)
4. **Moderation:** Who approves packages? (Automated checks + manual review for Nexus Verified)
5. **Private packages:** Support team-private? (v1.3.0 feature)
6. **Namespaces:** Use team numbers? (Optional, teams can use team1234 as scope)
7. **Binary support:** Allow compiled code? (No, source only)
8. **Update notifications:** Alert on updates? (Yes, via `weevil list --upgradable`)
9. **Code signing:** Security/trust model? (GPG signatures for Nexus Verified, optional for community)
10. **Monorepo:** Where store packages? (Separate repo: weevil-packages)
---
## Future Enhancements ## Future Enhancements
### v1.3.0+ ### v1.3.0+
@@ -632,27 +674,14 @@ weevil update <package> # Update specific
- `weevil publish` command - `weevil publish` command
- Package mirrors - Package mirrors
- Offline mode - Offline mode
- Additional templates (mecanum, vision, etc.)
### v2.0.0+ ### v2.0.0+
- Binary packages - Binary packages
- Pre-built libraries - Pre-built libraries
- Cloud builds - Cloud builds
- Team collaboration features - Team collaboration features
- VS Code integration
---
## Open Questions
1. **Versioning:** How handle breaking changes?
2. **Testing:** Require tests in packages?
3. **Licensing:** Enforce compliance?
4. **Moderation:** Who approves packages?
5. **Private packages:** Support team-private?
6. **Namespaces:** Use team numbers?
7. **Binary support:** Allow compiled code?
8. **Update notifications:** Alert on updates?
9. **Code signing:** Security/trust model?
10. **Monorepo:** Where store templates/packages?
--- ---
@@ -666,102 +695,33 @@ weevil update <package> # Update specific
--- ---
## Appendix: Complete Examples ## Appendix: Comparison Matrix
### Example 1: Creating Project | Feature | Templates (v1.1.0) | Packages (v1.2.0) |
|---------|-------------------|-------------------|
```bash | **Purpose** | Start projects | Extend projects |
$ weevil create my-robot --template testing | **When** | Project creation | After creation |
| **Size** | Large (complete projects) | Small (components) |
Creating FTC project 'my-robot'... | **Conflicts** | None (new project) | Possible (merging) |
| **Dependencies** | None | Yes (dependency tree) |
✓ Created directory structure | **Variants** | 2 templates | Many per package |
✓ Generated source files (17 files) | **Customization** | Fork template | Use as-is or modify |
✓ Generated test files (4 files) | **Updates** | Manual (copy pattern) | `weevil update` |
✓ Created build configuration | **Status** | ✅ Shipped | 📋 Planned |
✓ Generated documentation (6 files)
✓ Initialized Git repository
Project created successfully!
Next steps:
cd my-robot
weevil test # 45 tests pass in < 2 sec
weevil build # Build APK
weevil deploy --auto # Deploy to robot
Documentation:
README.md - Overview
DESIGN_AND_TEST_PLAN.md - Architecture
TESTING_GUIDE.md - How to test
```
### Example 2: Adding Package
```bash
$ cd my-robot
$ weevil add nexus/subsystems/mecanum-drive/complete
Resolving dependencies...
Package nexus/subsystems/mecanum-drive/complete requires:
- nexus/hardware/dc-motor/core (v1.2.0)
- nexus/hardware/imu/core (v2.0.0)
Installing 3 packages:
1. nexus/hardware/dc-motor/core (v1.2.0)
2. nexus/hardware/imu/core (v2.0.0)
3. nexus/subsystems/mecanum-drive/complete (v2.1.0)
✓ Added 12 source files
✓ Added 8 test files
✓ Updated build.gradle
Package installed successfully!
Next steps:
See docs/subsystems/MECANUM_DRIVE.md for usage
Run weevil test to verify integration
```
### Example 3: Handling Conflicts
```bash
$ weevil add nexus/hardware/dc-motor/core
⚠ File conflict detected:
src/main/java/robot/hardware/MotorController.java (exists)
Options:
1. Skip conflicting files (safe, default)
2. Overwrite conflicting files (--force)
3. Interactive resolution (--interactive)
4. Abort
Choice [1]: 1
Added:
✓ src/main/java/robot/hardware/FtcMotorController.java
✓ docs/hardware/DC_MOTOR.md
Skipped:
⊗ src/main/java/robot/hardware/MotorController.java
Package partially installed (1 file skipped)
Note: Package may not work correctly if required files skipped
Consider using --force or --interactive for complete installation
```
--- ---
*End of Specification* *End of Specification*
**Status:** Ready for Implementation **Status:**
- ✅ Part 1 (Templates): COMPLETE in v1.1.0
- 📋 Part 2 (Packages): PLANNED for v1.2.0
**Next Steps:** **Next Steps:**
1. Implement `weevil create` for v1.1.0-beta.3 1. ✅ Ship v1.1.0 with template system
2. Use testing showcase as `testing` template 2. Gather feedback on testing template
3. Plan v1.2.0 package system 3. Begin v1.2.0 package system development
4. Create initial package set
**Contact:** eric@intrepidfusion.com **Contact:** eric@intrepidfusion.com
**Organization:** Nexus Workshops LLC **Organization:** Nexus Workshops LLC