weevil/docs/TEMPLATE-PACKAGE-SPEC.md

Weevil Template & Package System - Specification

Version: 1.1
Date: February 2, 2026
Status: Template system ✅ COMPLETE | Package system 📋 Planned for v1.2.0

---

Executive Summary

This document specifies two complementary features for Weevil:

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: Template System ✅ IMPLEMENTED in v1.1.0

Status: COMPLETE

The template system has been fully implemented and shipped in v1.1.0.

Implementation Summary

Command Syntax:

weevil new <project-name> [--template <name>] [--list-templates]

Delivered Templates:

1. basic (default) - Minimal FTC project

   • 8 files, ~50 lines of code
   • Clean starting point
   • Example OpMode placeholder

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

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)

Template Variable Substitution

Implemented variables:

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

Testing Template Contents

Subsystems (3):

• MotorCycler.java - State machine for motor cycling
• WallApproach.java - Sensor-based navigation
• TurnController.java - Gyro-based turning

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

# Create with default template
weevil new my-robot

# Create with testing template
weevil new my-robot --template testing

# List available templates
weevil new --list-templates

# 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

Implementation Architecture

Storage: Templates embedded in binary using include_dir! macro

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)

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 Metrics (Achieved)

• ✅ 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

Lessons Learned

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 - 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 Weevil projects

Version: v1.2.0
Priority: HIGH
Estimated Effort: 2-3 weeks

Command Syntax

weevil add <package> [OPTIONS]

OPTIONS:
  --force          Overwrite conflicting files
  --merge          Attempt to merge conflicts (experimental)
  --interactive    Prompt for each conflict
  --dry-run        Preview without adding
  --no-deps        Don't install dependencies
  --dev            Add as dev dependency

Package Naming

Hierarchical structure: scope/category/name/variant

Examples:

nexus/hardware/dc-motor/core
nexus/hardware/dc-motor/mock
nexus/hardware/dc-motor/example
nexus/hardware/dc-motor/complete

nexus/subsystems/wall-approach/complete
nexus/examples/autonomous/simple-auto

team1234/sensors/custom-lidar/core

Components:

• scope: Publisher (nexus, team1234, etc.)
• category: Type (hardware, subsystems, examples, testing)
• name: Component name (dc-motor, wall-approach)
• variant: Implementation (core, mock, example, complete)

Standard Variants

Variant	Contents	Dependencies
core	Interface + FTC wrapper	None
mock	Test double	Requires core
example	Example OpMode	Requires core
complete	All of above	Includes all variants

Usage Examples

# Add complete package
weevil add nexus/hardware/dc-motor/complete

# Add specific variant
weevil add nexus/hardware/dc-motor/core
weevil add nexus/hardware/dc-motor/mock --dev

# Add subsystem (auto-installs dependencies)
weevil add nexus/subsystems/wall-approach/complete

# Preview
weevil add nexus/hardware/servo/core --dry-run

# Force overwrite
weevil add nexus/hardware/gyro/complete --force

# Interactive resolution
weevil add nexus/subsystems/turn-controller/core --interactive

Dependency Resolution

Packages declare dependencies in manifest:

[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"

[dev-dependencies]
"nexus/testing/mock-base" = "^1.0.0"

Automatic Resolution:

$ weevil add nexus/subsystems/wall-approach/complete

Resolving dependencies...

Installing:
  1. nexus/hardware/distance/core (v2.1.0) - dependency
  2. nexus/hardware/dc-motor/core (v1.2.0) - dependency
  3. nexus/subsystems/wall-approach/complete (v1.0.0)

✓ Added 3 packages (15 files)

Conflict Handling

Default (Skip)

⚠ File conflicts detected:
  src/main/java/robot/hardware/MotorController.java (exists)

Resolution: Skipping conflicting files

Added:
  ✓ src/main/java/robot/hardware/FtcMotorController.java

Skipped:
  ⊗ MotorController.java (already exists)

Force Mode

$ weevil add nexus/hardware/dc-motor/core --force

⚠ Warning: --force will overwrite 2 files
Continue? [y/N]: y

✓ Overwrote 2 files, added 3 files

Interactive Mode

$ weevil add nexus/hardware/dc-motor/core --interactive

Conflict: MotorController.java

Options:
  [s] Skip (keep your file)
  [o] Overwrite (use package file)
  [d] Show diff
  [a] Abort

Choice [s]: d

Diff:
  --- Existing
  +++ Package
  @@ -5,3 +5,5 @@
   public interface MotorController {
       void setPower(double power);
       double getPower();
  +    void setMode(RunMode mode);
  +    RunMode getMode();
   }

Choice [s]:

Package Categories

hardware/*

Physical hardware abstractions

Subcategories:

• hardware/motors/* - Motor controllers
• hardware/sensors/* - Sensor interfaces
• hardware/servos/* - Servo controllers
• hardware/vision/* - Camera systems
• hardware/imu/* - Gyroscopes

Standard Variants: core, mock, example, complete

subsystems/*

Robot subsystems built on hardware

Examples:

• subsystems/drivetrain/*
• subsystems/arm/*
• subsystems/intake/*

Standard Variants: core, mock, example, complete

examples/*

Complete working examples

Subcategories:

• examples/autonomous/*
• examples/teleop/*
• examples/vision/*

Variants: Usually standalone (no variants)

testing/*

Testing utilities and patterns

Examples:

• testing/mock-hardware - Mock collection
• testing/test-patterns - Reusable patterns
• testing/assertions - Custom assertions

utilities/*

Helper utilities

Examples:

• utilities/math/*
• utilities/telemetry/*
• utilities/logging/*

Package Manifest

Example (package.toml):

[package]
name = "dc-motor"
scope = "nexus"
category = "hardware"
version = "1.2.0"
description = "DC motor controller interface and FTC implementation"
license = "MIT"
authors = ["Nexus Workshops <info@nxgit.dev>"]

[variants]
available = ["core", "mock", "example", "complete"]
default = "complete"

[dependencies]
# Empty for base hardware

[files.core]
include = [
    "src/main/java/robot/hardware/MotorController.java",
    "src/main/java/robot/hardware/FtcMotorController.java"
]

[files.mock]
include = ["src/test/java/robot/hardware/MockMotorController.java"]
dependencies = ["core"]

[files.example]
include = ["src/main/java/robot/opmodes/examples/MotorExample.java"]
dependencies = ["core"]

[files.complete]
dependencies = ["core", "mock", "example"]

Package Repository

Location: https://packages.nxgit.dev (to be implemented)

Structure:

packages.nxgit.dev/
├── index.json
├── nexus/
│   ├── hardware/
│   │   ├── dc-motor/
│   │   │   ├── package.toml
│   │   │   ├── core.tar.gz
│   │   │   ├── mock.tar.gz
│   │   │   └── complete.tar.gz
│   │   └── distance/...
│   └── subsystems/...
└── team1234/...

---

Supporting Commands (v1.2.0)

weevil remove

Remove installed package

weevil remove <package> [--prune] [--force]

weevil search

Search package registry

weevil search <query>

Output:
  nexus/hardware/mecanum-drive/complete
    Mecanum drive system with holonomic control
    ★★★★★ (342 downloads)

weevil list

List packages

weevil list --installed        # Show installed
weevil list --available        # Show all available

weevil info

Show package details

weevil info nexus/hardware/dc-motor/complete

Package: nexus/hardware/dc-motor/complete
Version: 1.2.0
Downloads: 1,523
License: MIT

Description:
  DC motor controller with interface, FTC implementation,
  test mocks, and examples.

weevil update

Update packages to latest versions

weevil update                  # Update all
weevil update <package>        # Update specific

---

Implementation Roadmap

Phase 1: v1.1.0 ✅ COMPLETE

Template System:

• Template storage system (embedded in binary)
• Variable substitution engine
• Basic template (minimal project)
• Testing template (professional showcase)
• --list-templates command
• Template validation
• Success/error messages
• Documentation (README, DESIGN_AND_TEST_PLAN, etc.)
• Comprehensive tests (62 tests passing)
• Cross-platform support

Delivered:

• Template system fully functional
• Two high-quality templates
• Professional documentation
• 100% test coverage
• Zero warnings in cargo test

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
• Comprehensive tests

---

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

---

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

• Template system implemented
• Testing template includes 45 passing tests
• Professional documentation delivered
• 62 tests passing, zero warnings
• 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
• ✅ License specified
• ✅ README included
• ✅ Compiles without errors

Recommended (Verified Badge):

• ✅ Tests included
• ✅ Comprehensive docs
• ✅ Interface-based design
• ✅ No hardcoded values
• ✅ Follows naming conventions

Nexus Verified:

• All required + recommended
• Professional code quality
• Full test coverage
• Maintained and supported

---

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+

• Package signing (GPG)
• Private registries
• 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
• VS Code integration

---

References

• npm - Node package manager (scopes, registry)
• Cargo - Rust package manager (semver, crates.io)
• FreeBSD Ports - Package system inspiration
• Maven Central - Java repository patterns
• Homebrew - macOS package management

---

Appendix: Comparison Matrix

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:

• ✅ Part 1 (Templates): COMPLETE in v1.1.0
• 📋 Part 2 (Packages): PLANNED for v1.2.0

Next Steps:

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