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:**
```bash
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

```bash
# 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

```bash
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

```bash
# 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:

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

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

**Automatic Resolution:**
```bash
$ 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

```bash
$ 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

```bash
$ 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`):**

```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

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

### `weevil search`

Search package registry

```bash
weevil search <query>

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

### `weevil list`

List packages

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

### `weevil info`

Show package details

```bash
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

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

---

## Implementation Roadmap

### Phase 1: v1.1.0 ✅ COMPLETE

**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

**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
- [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
- ✅ 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