# FTC Project Generator 1.0.0-beta

Clean, testable FTC robot projects with shared SDK architecture.

## Version 1.0.0-beta

This is the beta release focusing on stability, testing, and upgrade capabilities.

## Features

- ✓ Clean project structure separate from FTC SDK
- ✓ Instant testing on PC (no robot required)
- ✓ Shared SDK across multiple projects
- ✓ Linux and Windows support
- ✓ Project upgrade capabilities
- ✓ Comprehensive unit and system tests
- ✓ Template-based file generation

## Quick Start

### Linux/macOS
```bash
# Create new project
./ftc-new-project my-robot

# Upgrade existing project
./ftc-new-project my-robot --upgrade

# Enter and test
cd my-robot
./gradlew test --continuous
```

### Windows
```batch
REM Create new project
ftc-new-project.bat my-robot

REM Upgrade existing project
ftc-new-project.bat my-robot --upgrade

REM Enter and test
cd my-robot
gradlew test --continuous
```

## Installation

### Linux/macOS
```bash
# Option 1: Add to PATH
echo 'export PATH=$PATH:/path/to/ftc-project-gen' >> ~/.bashrc
source ~/.bashrc

# Option 2: Symlink
sudo ln -s /path/to/ftc-project-gen/ftc-new-project /usr/local/bin/

# Option 3: Use directly
./ftc-new-project my-robot
```

### Windows
```batch
REM Add directory to PATH or use directly
ftc-new-project.bat my-robot
```

## Project Structure

```
ftc-project-gen-1.0.0-beta/
├── ftc-new-project              # Linux main script
├── ftc-new-project.bat          # Windows main script
├── linux/                       # Linux-specific support files
│   ├── templates/              # File templates
│   │   ├── Pose2d.java
│   │   ├── Drive.java
│   │   ├── DriveTest.java
│   │   ├── MecanumDrive.java
│   │   ├── TeleOp.java
│   │   ├── build.gradle.kts
│   │   ├── settings.gradle.kts.template
│   │   ├── gitignore.template
│   │   ├── README.md.template
│   │   ├── build.sh
│   │   └── deploy-to-robot.sh
│   └── lib.sh                  # Shared functions
├── windows/                    # Windows-specific support files
│   ├── templates/              # File templates
│   │   └── (mirrors linux templates)
│   └── lib.bat                 # Shared functions
├── tests/                      # Test suite
│   ├── unit/                   # Unit tests
│   └── system/                 # System/integration tests
├── VERSION                     # Version file
└── README.md
```

## Development

### Running Tests
```bash
# Run all tests
./tests/run-tests.sh

# Run specific test suite
./tests/run-tests.sh unit
./tests/run-tests.sh system

# Run specific test
./tests/run-tests.sh unit test_template_rendering
```

### Testing Philosophy
- **Unit tests**: Test individual functions and template rendering
- **System tests**: Test end-to-end project creation, building, and upgrading
- **Regression tests**: Ensure generated projects build and pass their own tests

## Upgrading

### What Gets Updated
When you run with `--upgrade`:
- ✓ Build configuration files (build.gradle.kts, settings.gradle.kts)
- ✓ Helper scripts (build.sh, deploy-to-robot.sh)
- ✓ .gitignore
- ✗ Your source code (never touched)
- ✗ Your tests (never touched)

### Upgrade Process
```bash
# Backup recommended but not required (git protects you)
cd my-robot
git status  # Make sure you've committed your work

# Run upgrade
ftc-new-project my-robot --upgrade

# Review changes
git diff

# Test
./gradlew test
```

## Architecture

### Template System
Files are stored as templates in `templates/` directories. Templates can contain placeholders:
- `{{PROJECT_NAME}}` - Replaced with project name
- `{{SDK_DIR}}` - Replaced with SDK directory path
- `{{FTC_VERSION}}` - Replaced with FTC SDK version

### Upgrade System
Projects track their generator version in `.ftc-generator-version`. During upgrade:
1. Check if project exists
2. Verify it's a generator project
3. Update only infrastructure files
4. Preserve user code
5. Update version marker

### Cross-Platform Support
- Linux: Bash scripts with POSIX compliance
- Windows: Batch scripts with delayed expansion
- Shared logic where possible
- Platform-specific implementations in separate directories

## Contributing

### Adding New Templates
1. Create template file in `linux/templates/` and `windows/templates/`
2. Use placeholders for variable content
3. Update `lib.sh`/`lib.bat` to include new template
4. Add tests for the new template
5. Update documentation

### Running Tests Before Commit
```bash
./tests/run-tests.sh
```

All tests must pass before submitting changes.

## License

MIT License - See individual project files for details.

Copyright (c) 2026 Nexus Workshops LLC