diff --git a/README.md b/README.md index e706268..2895d95 100644 --- a/README.md +++ b/README.md @@ -28,20 +28,100 @@ This approach works against standard software engineering practices and creates - ✅ 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!) -├── .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 ├── deploy.sh / deploy.bat # One command to deploy └── .weevil.toml # Project configuration @@ -53,7 +133,8 @@ my-robot/ weevil setup # 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!) cd awesome-robot @@ -102,13 +183,14 @@ weevil setup # Uses proxy automatically ### 💻 Android Studio Integration (v1.1.0) 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 - **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 @@ -147,14 +229,7 @@ export PATH="$PATH:$(pwd)/target/release" ### 1. Set Up Your Environment ```bash -# Check what's installed -weevil doctor - -# Install everything automatically weevil setup - -# Or install to custom location -weevil setup --ftc-sdk ~/my-sdks/ftc --android-sdk ~/my-sdks/android ``` Weevil will: @@ -165,69 +240,149 @@ Weevil will: ### 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 ``` -Weevil generates: -- 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!) +### 3. Run Tests (Testing Template) ```bash ./gradlew test ``` -Write unit tests in `src/test/java/robot/` that run on your PC. No need to deploy to a robot for every code change! +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 -# Build APK -./build.sh +# Read the overview +cat QUICKSTART.md -# Deploy via USB -./deploy.sh --usb +# Study a subsystem +cat src/main/java/robot/subsystems/WallApproach.java -# Deploy via WiFi -./deploy.sh --wifi -i 192.168.49.1 +# See how it's tested +cat src/test/java/robot/subsystems/WallApproachTest.java -# Auto-detect (tries USB, falls back to WiFi) -./deploy.sh +# 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 # Uses basic template + weevil new --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 @@ -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 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 -Android Studio will index the project. After a few seconds, you'll see: -- **Clean file tree** - Only `src/`, scripts, and essential files visible -- **Run configurations** - Dropdown next to the green play button shows: - - **Build** - Builds APK without deploying - - **Deploy (auto)** - Auto-detects USB or WiFi - - **Deploy (USB)** - Forces USB connection - - **Deploy (WiFi)** - Forces WiFi connection - - **Test** - Runs unit tests +You'll see: +- Clean file tree (only your code visible) +- Run configurations in dropdown +- One-click deployment -### 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. Go to **File → Settings** (or **Ctrl+Alt+S**) -2. Navigate to **Plugins** -3. Click the **Marketplace** tab -4. Search for **"Shell Script"** -5. Install the plugin (by JetBrains) -6. Restart Android Studio - -After restart, the run configurations will work. +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 a configuration from the dropdown (e.g., "Deploy (auto)") -2. Click the green play button (▶) or press **Shift+F10** -3. Watch the output in the Run panel at the bottom +1. Select configuration (Test, Build, Deploy) +2. Click green play button (▶) +3. Watch output in Run panel -**That's it!** Students can now build and deploy without leaving the 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 +**That's it!** Deploy to robot without leaving IDE. --- @@ -281,128 +421,68 @@ After restart, the run configurations will work. ### Proxy Configuration -#### Corporate Environments - ```bash -# Set proxy for all Weevil operations +# Corporate proxy 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 HTTP_PROXY=http://proxy:8080 -weevil setup # Automatically uses proxy -``` +weevil setup -#### Air-Gapped / Offline Installation - -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) +# Bypass proxy weevil --no-proxy setup ``` ### Multiple SDK Versions -Working with multiple SDK versions? No problem: - ```bash -# Create project with specific SDK +# Create with specific SDK 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 - -# Rebuild with new SDK -weevil upgrade experimental-bot -cd experimental-bot -./build.sh ``` ### Upgrading Projects -When Weevil releases new features: - ```bash weevil upgrade my-robot ``` -This updates: -- Build scripts -- Deployment scripts -- Gradle configuration -- Android Studio run configurations -- Project templates - +Updates build scripts, Gradle config, and IDE integration. **Your code in `src/` is never touched.** ### System Maintenance ```bash -# Check what's installed -weevil doctor - -# 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 +weevil doctor # Check system health +weevil uninstall --dry-run # Preview uninstall +weevil uninstall --only 1 # Remove specific component ``` -### 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 -Each project has a `.weevil.toml` file: - +`.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" -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 -weevil config my-robot # View config +weevil config my-robot # View 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 ```bash -# Create project -weevil new competition-bot +weevil new competition-bot --template testing cd competition-bot -# Project is already a git repo! +# Already a git repo! git remote add origin https://nxgit.dev/team/robot.git git push -u origin main -# Make changes -# ... edit code ... -./gradlew test -git commit -am "Add autonomous mode" +# Development cycle +./gradlew test # Test locally +git commit -am "Add feature" git push - -# Deploy to robot -./deploy.sh +./deploy.sh # Deploy to robot ``` -### Testing Strategy +### Learning from the Testing Template -1. **Unit Tests** - Test business logic on your PC - ```bash - ./gradlew test - # Or from Android Studio: select "Test" and click Run - ``` - -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 +# Create learning project +weevil new learning --template testing +cd learning -# Check SDK location -weevil config . +# Study the architecture +cat DESIGN_AND_TEST_PLAN.md -# Set SDK to local path (if different from .weevil.toml) -weevil config . --set-sdk ~/ftc-sdk +# Run tests and see patterns +./gradlew test -# Build and deploy -./build.sh -./deploy.sh +# 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 ``` -**Android Studio users:** Just open the project. The `.idea/` folder contains all run configurations. - --- ## Command Reference @@ -475,48 +539,47 @@ weevil config . --set-sdk ~/ftc-sdk | Command | Description | |---------|-------------| -| `weevil doctor` | Check system health and dependencies | -| `weevil setup` | Install FTC SDK, Android SDK, and dependencies | -| `weevil setup --ftc-sdk ` | Install to custom FTC SDK location | -| `weevil uninstall` | Remove all Weevil-managed components | -| `weevil uninstall --dry-run` | Show what would be removed | -| `weevil uninstall --only ` | Remove specific component by index | +| `weevil doctor` | Check system health | +| `weevil setup` | Install FTC SDK, Android SDK | +| `weevil setup --ftc-sdk ` | Install to custom location | +| `weevil uninstall` | Remove all components | +| `weevil uninstall --dry-run` | Preview uninstall | +| `weevil uninstall --only ` | Remove specific component | ### Project Commands | Command | Description | |---------|-------------| -| `weevil new ` | Create new FTC project | -| `weevil new --ftc-sdk ` | Create with specific SDK | +| `weevil new ` | Create project (basic template) | +| `weevil new --template ` | Create with template | +| `weevil new --list-templates` | Show available templates | | `weevil upgrade ` | Update project infrastructure | -| `weevil config ` | View project configuration | -| `weevil config --set-sdk ` | Change FTC SDK path | +| `weevil config ` | View configuration | +| `weevil config --set-sdk ` | Change FTC SDK | ### SDK Commands | 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 update` | Update SDKs to latest versions | +| `weevil sdk update` | Update to latest SDKs | ### Global Flags | Flag | Description | |------|-------------| -| `--proxy ` | Use HTTP proxy for all network operations | -| `--no-proxy` | Bypass proxy (ignore HTTPS_PROXY env vars) | +| `--proxy ` | Use HTTP proxy | +| `--no-proxy` | Bypass proxy | ### Deployment Options -**`deploy.sh` / `deploy.bat` flags:** - | Flag | Description | |------|-------------| -| `--usb` | Force USB deployment | -| `--wifi` | Force WiFi deployment | -| `-i ` | Custom Control Hub IP | -| `--timeout ` | WiFi connection timeout | +| `--usb` | Force USB | +| `--wifi` | Force WiFi | +| `-i ` | Custom IP | +| `--timeout ` | WiFi timeout | --- @@ -525,166 +588,91 @@ weevil config . --set-sdk ~/ftc-sdk ### How It Works 1. **Project Generation** - - Creates standalone Java project structure - - Generates Gradle build files that reference FTC SDK + - Creates standalone Java project + - Optionally overlays template (basic/testing) + - Generates build files referencing FTC SDK - Sets up deployment scripts - - Creates Android Studio run configurations + - Creates Android Studio integration 2. **Build Process** - - Runs `deployToSDK` Gradle task - - Copies your code to FTC SDK's `TeamCode` directory - - Builds APK using SDK's Android configuration - - Leaves your project directory clean + - Copies code to FTC SDK's TeamCode + - Builds APK using SDK + - Leaves project directory clean 3. **Deployment** - - Finds built APK in SDK - - Connects to Control Hub (USB or WiFi) - - Installs APK 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 + - 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: `my-robot/*.gradle.kts` -- FTC SDK: System-level installation -- IDE integration: Auto-generated, auto-upgraded +- Build infrastructure: `*.gradle.kts` +- FTC SDK: System installation +- Templates: Starting points **Benefits:** -- Test code without SDK complications -- Multiple projects per SDK installation -- SDK updates don't break your projects -- Proper version control (no massive SDK in repo) -- Industry-standard project structure -- Students use familiar tools (Android Studio) +- 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 -Weevil includes comprehensive tests: - ```bash -# Run all tests -cargo test - -# Run specific test suites -cargo test --test integration -cargo test --test project_lifecycle -cargo test --test proxy_integration -cargo test config_tests +cargo test # All tests +cargo test --test integration # Integration tests +cargo test --test template_tests # Template tests ``` -**Test Coverage:** -- ✅ Project creation and structure -- ✅ Configuration persistence -- ✅ SDK detection and validation -- ✅ Build script generation -- ✅ Upgrade workflow -- ✅ CLI commands -- ✅ Proxy configuration and network operations -- ✅ Environment setup and health checks +**Coverage:** +- ✅ Project creation +- ✅ Template extraction +- ✅ Configuration +- ✅ SDK detection +- ✅ Build scripts +- ✅ Proxy support +- ✅ 62 tests passing --- ## Troubleshooting ### "FTC SDK not found" - ```bash -# Check system health weevil doctor - -# Install SDK weevil setup - -# Or specify custom location -weevil new my-robot --ftc-sdk /custom/path/to/sdk ``` ### "adb: command not found" - -Install Android platform-tools: - -**Linux:** ```bash -# Weevil can install it for you -weevil setup - -# Or install manually -sudo apt install android-tools-adb +weevil setup # Installs Android SDK with adb ``` -**macOS:** -```bash -brew install android-platform-tools -``` - -**Windows:** -Download Android SDK Platform Tools from Google or run `weevil setup`. - ### "Build failed" - ```bash -# Clean and rebuild -cd my-robot ./gradlew clean ./build.sh - -# Check SDK path -weevil config . - -# Verify system health weevil doctor ``` ### "Deploy failed - No devices" +**USB:** `./deploy.sh --usb` +**WiFi:** `./deploy.sh -i 192.168.43.1` -**USB:** -1. Connect robot via USB -2. Run `adb devices` to verify connection -3. Try `./deploy.sh --usb` - -**WiFi:** -1. Connect to robot's WiFi network -2. Find Control Hub IP (usually 192.168.43.1 or 192.168.49.1) -3. Try `./deploy.sh -i ` - -### 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 -``` +### "Unknown run configuration type ShellScript" +Install Shell Script plugin in Android Studio (see [Android Studio Setup](#android-studio-setup)) --- ## Contributing -Contributions welcome! Please: - -1. Fork the repository -2. Create a feature branch -3. Write tests for new features -4. Ensure `cargo test` passes with zero warnings -5. Submit a pull request - -### Development Setup +Contributions welcome! ```bash git clone https://www.nxgit.dev/nexus-workshops/weevil.git @@ -693,7 +681,7 @@ cargo build cargo test # 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"?** -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:** -1. **Students first** - Minimize cognitive load for learners +1. **Students first** - Minimize cognitive load 2. **Industry practices** - Teach real software engineering -3. **Testability** - Enable TDD and proper testing workflows -4. **Simplicity** - One command should do one obvious thing -5. **Transparency** - Students should understand what's happening -6. **Tool compatibility** - Work with tools students already know +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) 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) -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. 🤖 @@ -736,24 +725,25 @@ Built with frustration at unnecessarily complex robotics frameworks, and hope th **Current Version:** 1.1.0 **What Works:** -- ✅ Project generation +- ✅ 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 (`weevil doctor`) +- ✅ System diagnostics - ✅ Selective uninstall -- ✅ Proxy support for corporate/air-gapped environments -- ✅ Android Studio integration with one-click deployment +- ✅ Proxy support +- ✅ Android Studio integration **Roadmap:** -- 📋 Package management for FTC libraries -- 📋 Template system for common robot configurations +- 📋 `weevil add` - Package management system (v1.2.0) +- 📋 Community package repository +- 📋 Additional templates (mecanum, vision) - 📋 VS Code integration - 📋 Team collaboration features -- 📋 Automated testing on robot hardware -- 📋 Multi-robot support (manage multiple Control Hubs) +- 📋 Multi-robot support --- diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 76be075..3294cff 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -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 ✅ **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) - Android SDK installation status and version - 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. -**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 ✅ @@ -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 -**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. - -**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 +**Implementation:** `weevil uninstall`, `weevil uninstall --dry-run`, `weevil uninstall --only ` --- @@ -88,20 +67,12 @@ Handle `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` environment variables and write a **Status:** ✅ Complete - Shipped in v1.1.0 -**Implementation:** `--proxy ` and `--no-proxy` global flags, automatic HTTPS_PROXY/HTTP_PROXY env var detection - -**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. - -**Pros:** -- Unlocks enterprise/school environments -- 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 +**Implementation:** +- `--proxy ` global flag +- `--no-proxy` global flag (bypass) +- Automatic HTTPS_PROXY/HTTP_PROXY env var detection +- git2/libgit2 proxy support +- Gradle wrapper respects proxy settings --- @@ -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. -**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:** -- 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 +### Template System ✅ **THE GAME CHANGER** -**Cons:** -- Android Studio project file format may change between versions -- Complex to test across different Android Studio versions -- May conflict with students' existing Android Studio customizations -- Requires Shell Script plugin (one-time setup) +**Feature:** Professional code templates for project creation + +**Description:** Transform Weevil from "empty project generator" to "start with professional code." Includes: + +**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 ` - Creates project with basic template +- `weevil new --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 -**Description:** Detailed, step-by-step instructions for manually installing every dependency when automation fails. This includes: -- 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 +**Description:** Detailed, step-by-step instructions for manually installing every dependency when automation fails. **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) 🔄 **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 -**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 ` - Remove installed package +- `weevil search ` - Search package registry +- `weevil list [--installed|--available]` - List packages +- `weevil info ` - 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 @@ -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 - Support both USB and WiFi debugging -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:** 🔄 Deferred to v1.3.0 - Advanced feature, build basic package system first -**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. - -**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 +**Priority:** MEDIUM-HIGH - Natural extension after package system --- @@ -274,21 +316,7 @@ Students should be able to: - Appears in "Programs and Features" for clean uninstall - Optionally creates desktop shortcut -**Status:** Planned for 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) +**Status:** 🔄 Deferred to v1.2.0 **Priority:** MEDIUM - Polish feature for Windows adoption @@ -298,21 +326,9 @@ Students should be able to: **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. - -**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 +**Priority:** MEDIUM - Pairs well with GUI development (v1.3.0+) --- @@ -320,28 +336,32 @@ Students should be able to: **Feature:** Support for Arch, Fedora, Slackware, and other distributions -**Description:** Adapt installation scripts to detect and use different package managers: -- Arch: pacman -- Fedora: dnf/yum -- Slackware: pkgtool -- Generic: compile from source instructions +**Status:** 🔄 Deferred - Low priority, most teams use Ubuntu/Debian or Windows -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:** -- Broader Linux support -- Community contributions likely (Arch users love AUR packages) -- Demonstrates technical depth +## Version 1.3.0 - Developer Experience -**Cons:** -- Significant testing burden across distros -- Each package manager has different quirks -- Low ROI - most teams use Ubuntu/Debian or Windows -- Maintenance overhead +**Theme:** Making Weevil an all-in-one development environment with advanced debugging and UX polish -**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 -**Description:** A graphical interface that wraps Weevil's functionality, allowing users to: -- Create new projects through forms/wizards -- Configure project settings visually -- Run builds and deployments with buttons -- View status and logs in a window -- Manage dependencies through checkboxes/dropdowns +**Description:** A graphical interface that wraps Weevil's functionality: +- Create projects through forms/wizards +- Visual project configuration +- Button-based builds and deployments +- Visual package browser and installer +- Status and logs in a window -**Technical Approaches:** -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) +**Technical Approach:** Tauri (Rust + web frontend) for native performance and small binary -**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:** -- 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. +**Priority:** MEDIUM-HIGH - Lowers barrier to entry significantly --- @@ -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 **Description:** Refactor Weevil's core functionality behind a REST API: -- API could run as a local server or be embedded -- CLI becomes a thin client to the API -- GUI uses the same API endpoints -- Enables future integrations (VS Code extension, web dashboard, etc.) +- CLI becomes thin client +- GUI uses same API endpoints +- Enables future integrations (VS Code extension, web dashboard) -Endpoints might include: -- `POST /project/create` - Create new project -- `GET /status` - System audit -- `POST /build` - Trigger build -- `GET /dependencies` - List installed dependencies -- etc. +**Status:** 🔄 Deferred - Only if building GUI -**Rationale:** Clean separation of concerns. Makes adding new interfaces (GUI, IDE plugins) easier. Enables potential future features like remote builds or team collaboration. - -**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). +**Priority:** MEDIUM - Clean architecture, but not essential unless building GUI --- -## 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: -- 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 +**Priority:** MEDIUM-HIGH - High value but complex --- @@ -508,29 +431,9 @@ Endpoints might include: **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: -- C++ project templates -- Build system integration (CMake? Gradle?) -- Android NDK integration -- Debugging support -- Mixed Java/C++ projects (JNI bridges) +**Status:** Research - Contingent on FTC officially supporting C++ -**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. - -**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++ +**Priority:** LOW - Wait for FTC announcement **Trigger:** FTC officially announces C++ support @@ -540,88 +443,9 @@ Endpoints might include: **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: -- Core: project structure, build orchestration, deployment -- Plugins: language-specific templates, build rules, dependencies +**Status:** Research - Only if supporting 3+ languages -This makes adding new languages easier and keeps core clean. - -**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. +**Priority:** LOW-MEDIUM --- @@ -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 -**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 -**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 -**Decision Point:** Wait for user requests. If teams need SOCKS support, prioritize accordingly. +**Decision Point:** Wait for user requests --- ### 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 @@ -684,7 +488,7 @@ This makes adding new languages easier and keeps core clean. ### 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 @@ -692,15 +496,15 @@ This makes adding new languages easier and keeps core clean. ### 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 -**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 @@ -720,11 +524,58 @@ The `weevil upgrade` command is designed to migrate projects forward across vers 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) - **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 -- **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. +**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* \ No newline at end of file +*Last Updated: February 2026* +*Current Release: v1.1.0* +*Next Release: v1.2.0 (Package Ecosystem) - Q2 2026* \ No newline at end of file diff --git a/docs/TEMPLATE-PACKAGE-SPEC.md b/docs/TEMPLATE-PACKAGE-SPEC.md index 0c71060..cf7c540 100644 --- a/docs/TEMPLATE-PACKAGE-SPEC.md +++ b/docs/TEMPLATE-PACKAGE-SPEC.md @@ -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 -**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: -1. **`weevil create` (v1.1.0)** - Project scaffolding with templates -2. **`weevil add` (v1.2.0)** - Package management system +1. **Template System (v1.1.0)** - ✅ **IMPLEMENTED** - Project scaffolding with professional code templates +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. --- -## 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 -**Priority:** HIGH - -### Command Syntax +### Implementation Summary +**Command Syntax:** ```bash -weevil create [OPTIONS] - -OPTIONS: - --template Template to use (default: "basic") - --path 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 +weevil new [--template ] [--list-templates] ``` -### 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:** -``` -my-robot/ -├── src/ -│ ├── main/java/robot/ -│ │ └── opmodes/ -│ │ └── BasicOpMode.java -│ └── test/java/robot/ -│ └── .gitkeep -├── build.gradle -├── settings.gradle -├── .weevil.toml -├── .gitignore -├── README.md -└── build.bat / build.sh -``` +**Key Features Delivered:** +- ✅ Template extraction and overlay system +- ✅ Variable substitution (`{{PROJECT_NAME}}`, etc.) +- ✅ Template validation with helpful errors +- ✅ `--list-templates` command +- ✅ Templates embedded in binary (no external files) +- ✅ Complete test coverage (62 tests passing) -**Files:** ~10 -**Code:** ~50 lines +### Template Variable Substitution -#### 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:** -- 3 subsystems (MotorCycler, WallApproach, TurnController) -- 6 hardware interfaces + FTC implementations -- 6 test mocks -- 45 passing tests -- Complete documentation (6 files) +### Testing Template Contents -**Files:** ~30 -**Code:** ~2,500 lines -**Tests:** 45 (< 2 sec runtime) +**Subsystems** (3): +- `MotorCycler.java` - State machine for motor cycling +- `WallApproach.java` - Sensor-based navigation +- `TurnController.java` - Gyro-based turning -**Documentation:** -- README.md -- DESIGN_AND_TEST_PLAN.md -- TESTING_GUIDE.md -- TESTING_SHOWCASE.md -- SOLUTION.md -- ARCHITECTURE.md +**Hardware Layer** (12 files): +- 3 interfaces (MotorController, DistanceSensor, GyroSensor) +- 3 FTC implementations +- 3 mock implementations +- 3 additional interfaces + +**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 ```bash -# Create minimal project -weevil create my-robot +# Create with default template +weevil new my-robot # Create with testing template -weevil create my-robot --template testing +weevil new my-robot --template testing -# Create in specific location -weevil create my-robot --template testing --path ~/ftc-projects +# List available templates +weevil new --list-templates -# Preview without creating -weevil create my-robot --template testing --dry-run +# Output from list: +# 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 | -|----------|-------------|---------| -| `{{PROJECT_NAME}}` | Project directory name | `my-robot` | -| `{{PACKAGE_NAME}}` | Java package name | `myrobot` | -| `{{CREATION_DATE}}` | ISO 8601 timestamp | `2026-02-02T10:30:00Z` | -| `{{WEEVIL_VERSION}}` | Weevil version | `1.1.0` | -| `{{TEMPLATE_NAME}}` | Template used | `testing` | - -**Example:** -```java -// File: src/main/java/robot/subsystems/Example.java -// Generated by Weevil {{WEEVIL_VERSION}} on {{CREATION_DATE}} -package robot.{{PACKAGE_NAME}}; +**Directory Structure:** +``` +weevil/ +├── templates/ +│ ├── basic/ +│ │ ├── .gitignore +│ │ ├── README.md.template +│ │ ├── settings.gradle +│ │ └── src/... (.gitkeep files) +│ └── testing/ +│ ├── .gitignore +│ ├── README.md.template +│ ├── 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: -```java -// Generated by Weevil 1.1.0 on 2026-02-02T10:30:00Z -package robot.myrobot; -``` +**Key Implementation Details:** +- Templates complement ProjectBuilder (don't replace it) +- ProjectBuilder creates infrastructure (.weevil.toml, build.gradle.kts, etc.) +- Templates overlay content (source code, docs) +- Files ending in `.template` get variable substitution +- Regular files copied as-is -### Success Output +### Success Metrics (Achieved) -``` -✓ Created FTC project 'my-robot' using template 'testing' +- ✅ 62 tests passing (zero warnings) +- ✅ 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: - cd my-robot - weevil test # Run 45 tests (< 2 seconds) - weevil build # Build APK - weevil deploy # Deploy to robot +### Lessons Learned -Documentation: - README.md - Project overview - DESIGN_AND_TEST_PLAN.md - System architecture - TESTING_GUIDE.md - Testing patterns -``` - -### Implementation Notes - -**Storage Location:** -``` -~/.weevil/templates/ -├── basic/ -│ ├── template.toml -│ └── files/ -└── testing/ - ├── template.toml - └── files/ -``` - -**Effort Estimate:** 2-3 days -**Complexity:** MEDIUM +1. **Don't fight ProjectBuilder** - Templates should complement, not replace infrastructure +2. **Embed in binary** - No external file dependencies +3. **Variable substitution** - Essential for project-specific values +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 --- -## 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 -**Purpose:** Add components to existing projects +**Purpose:** Add components to existing Weevil projects **Version:** v1.2.0 -**Priority:** MEDIUM-HIGH +**Priority:** HIGH +**Estimated Effort:** 2-3 weeks ### Command Syntax @@ -223,11 +240,11 @@ team1234/sensors/custom-lidar/core ```bash # Add complete package -weevil add nexus/hardware/dc-motor +weevil add nexus/hardware/dc-motor/complete # Add specific variant 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) weevil add nexus/subsystems/wall-approach/complete @@ -247,6 +264,12 @@ weevil add nexus/subsystems/turn-controller/core --interactive Packages declare dependencies in manifest: ```toml +[package] +name = "wall-approach" +scope = "nexus" +category = "subsystems" +version = "1.0.0" + [dependencies] "nexus/hardware/distance/core" = "^2.0.0" "nexus/hardware/dc-motor/core" = "^1.0.0" @@ -257,7 +280,9 @@ Packages declare dependencies in manifest: **Automatic Resolution:** ```bash -weevil add nexus/subsystems/wall-approach/complete +$ weevil add nexus/subsystems/wall-approach/complete + +Resolving dependencies... Installing: 1. nexus/hardware/distance/core (v2.1.0) - dependency @@ -287,7 +312,7 @@ Skipped: #### Force Mode ```bash -weevil add nexus/hardware/dc-motor/core --force +$ weevil add nexus/hardware/dc-motor/core --force ⚠ Warning: --force will overwrite 2 files Continue? [y/N]: y @@ -298,7 +323,7 @@ Continue? [y/N]: y #### Interactive Mode ```bash -weevil add nexus/hardware/dc-motor/core --interactive +$ weevil add nexus/hardware/dc-motor/core --interactive Conflict: MotorController.java @@ -415,7 +440,7 @@ dependencies = ["core", "mock", "example"] ### Package Repository -**Location:** https://packages.nxgit.dev +**Location:** https://packages.nxgit.dev (to be implemented) **Structure:** ``` @@ -433,21 +458,9 @@ packages.nxgit.dev/ └── 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` @@ -507,72 +520,45 @@ weevil update # 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 -### Phase 1: v1.1.0 (2-3 days) +### Phase 1: v1.1.0 ✅ COMPLETE -**`weevil create` command:** -- [ ] Template storage system -- [ ] Variable substitution -- [ ] Basic template -- [ ] Testing template -- [ ] Git initialization -- [ ] Success/error messages -- [ ] Documentation -- [ ] Tests +**Template System:** +- [x] Template storage system (embedded in binary) +- [x] Variable substitution engine +- [x] Basic template (minimal project) +- [x] Testing template (professional showcase) +- [x] `--list-templates` command +- [x] Template validation +- [x] Success/error messages +- [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:** -- [ ] Package registry setup -- [ ] Package manifest format -- [ ] Dependency resolver -- [ ] Conflict detection -- [ ] File installation -- [ ] Remove command -- [ ] Search command -- [ ] List command +### Phase 2: v1.2.0 📋 PLANNED (2-3 weeks) + +**`weevil add` Package System:** +- [ ] Package registry infrastructure +- [ ] Package manifest format (`package.toml`) +- [ ] Dependency resolver (semver) +- [ ] Conflict detection and resolution +- [ ] File installation system +- [ ] `weevil remove` command +- [ ] `weevil search` command +- [ ] `weevil list` command +- [ ] `weevil info` command +- [ ] `weevil update` command - [ ] 10+ launch packages - [ ] Documentation -- [ ] Tests +- [ ] Comprehensive tests --- @@ -601,7 +587,48 @@ weevil update # 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):** - ✅ Valid package.toml @@ -624,6 +651,21 @@ weevil update # 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 ### v1.3.0+ @@ -632,27 +674,14 @@ weevil update # Update specific - `weevil publish` command - Package mirrors - Offline mode +- Additional templates (mecanum, vision, etc.) ### v2.0.0+ - Binary packages - Pre-built libraries - Cloud builds - Team collaboration features - ---- - -## 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? +- VS Code integration --- @@ -666,102 +695,33 @@ weevil update # Update specific --- -## Appendix: Complete Examples +## Appendix: Comparison Matrix -### Example 1: Creating Project - -```bash -$ weevil create my-robot --template testing - -Creating FTC project 'my-robot'... - -✓ Created directory structure -✓ Generated source files (17 files) -✓ Generated test files (4 files) -✓ Created build configuration -✓ 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 -``` +| Feature | Templates (v1.1.0) | Packages (v1.2.0) | +|---------|-------------------|-------------------| +| **Purpose** | Start projects | Extend projects | +| **When** | Project creation | After creation | +| **Size** | Large (complete projects) | Small (components) | +| **Conflicts** | None (new project) | Possible (merging) | +| **Dependencies** | None | Yes (dependency tree) | +| **Variants** | 2 templates | Many per package | +| **Customization** | Fork template | Use as-is or modify | +| **Updates** | Manual (copy pattern) | `weevil update` | +| **Status** | ✅ Shipped | 📋 Planned | --- *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:** -1. Implement `weevil create` for v1.1.0-beta.3 -2. Use testing showcase as `testing` template -3. Plan v1.2.0 package system +1. ✅ Ship v1.1.0 with template system +2. Gather feedback on testing template +3. Begin v1.2.0 package system development +4. Create initial package set **Contact:** eric@intrepidfusion.com **Organization:** Nexus Workshops LLC \ No newline at end of file