weevil/docs/TEMPLATE-PACKAGE-SPEC.md

# Weevil Template & Package System - Complete Specification

**Version:** 1.0  
**Date:** February 2, 2026  
**Status:** Ready for implementation

---

## Executive Summary

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

Together, these enable teams to start with professional code and extend projects with community-shared components.

---

## Part 1: `weevil create` Command

### Overview

**Purpose:** Generate complete FTC robot projects from templates

**Version:** v1.1.0-beta.3  
**Priority:** HIGH

### Command Syntax

```bash
weevil create <project-name> [OPTIONS]

OPTIONS:
  --template <name>    Template to use (default: "basic")
  --path <directory>   Where to create project (default: current dir)
  --force              Overwrite existing directory
  --no-init            Don't initialize git repository
  --dry-run            Show what would be created
```

### Templates (v1.1.0)

#### Template 1: `basic` (Default)

**Purpose:** Minimal starting point

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

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

#### Template 2: `testing` (Showcase)

**Purpose:** Professional testing demonstration

**Includes:**
- 3 subsystems (MotorCycler, WallApproach, TurnController)
- 6 hardware interfaces + FTC implementations
- 6 test mocks
- 45 passing tests
- Complete documentation (6 files)

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

**Documentation:**
- README.md
- DESIGN_AND_TEST_PLAN.md
- TESTING_GUIDE.md
- TESTING_SHOWCASE.md
- SOLUTION.md
- ARCHITECTURE.md

### Usage Examples

```bash
# Create minimal project
weevil create my-robot

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

# Create in specific location
weevil create my-robot --template testing --path ~/ftc-projects

# Preview without creating
weevil create my-robot --template testing --dry-run
```

### Variable Substitution

Templates support variables:

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

Becomes:
```java
// Generated by Weevil 1.1.0 on 2026-02-02T10:30:00Z
package robot.myrobot;
```

### Success Output

```
✓ Created FTC project 'my-robot' using template 'testing'

Next steps:
  cd my-robot
  weevil test        # Run 45 tests (< 2 seconds)
  weevil build       # Build APK
  weevil deploy      # Deploy to robot

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

---

## Part 2: `weevil add` Command

### Overview

**Purpose:** Add components to existing projects

**Version:** v1.2.0  
**Priority:** MEDIUM-HIGH

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

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

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

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

**Structure:**
```
packages.nxgit.dev/
├── index.json
├── nexus/
│   ├── hardware/
│   │   ├── dc-motor/
│   │   │   ├── package.toml
│   │   │   ├── core.tar.gz
│   │   │   ├── mock.tar.gz
│   │   │   └── complete.tar.gz
│   │   └── distance/...
│   └── subsystems/...
└── 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

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

---

## 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)

**`weevil create` command:**
- [ ] Template storage system
- [ ] Variable substitution
- [ ] Basic template
- [ ] Testing template
- [ ] Git initialization
- [ ] Success/error messages
- [ ] Documentation
- [ ] Tests

### Phase 2: v1.2.0 (2-3 weeks)

**`weevil add` command:**
- [ ] Package registry setup
- [ ] Package manifest format
- [ ] Dependency resolver
- [ ] Conflict detection
- [ ] File installation
- [ ] Remove command
- [ ] Search command
- [ ] List command
- [ ] 10+ launch packages
- [ ] Documentation
- [ ] 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

---

## Package Quality Standards

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

---

## Future Enhancements

### v1.3.0+
- Package signing (GPG)
- Private registries
- `weevil publish` command
- Package mirrors
- Offline mode

### 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?

---

## 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: Complete Examples

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

---

*End of Specification*

**Status:** Ready for Implementation  
**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

**Contact:** eric@intrepidfusion.com  
**Organization:** Nexus Workshops LLC