# Project Log: Rostyr

## Date: 2026-03-08

## Context
- **Original project**: styr (https://gitea.rowanbrook.net/jakob/styr) - Shell scripts for configuring FreeBSD workstations, servers, VMs, and jails
- **Rewrite target**: rostyr (https://gitea.rowanbrook.net/jakob/rostyr) - Rust rewrite

## Requirements Decided

| Requirement | Decision | Rationale |
|-------------|----------|-----------|
| Scope | Minimal first, then expand | User preference - start lean, add incrementally |
| Platform | FreeBSD-focused | Keep aligned with styr's FreeBSD focus |
| Config format | TOML | Structured config vs shell scripts |
| Idempotency | All commands re-runnable | Critical requirement - run anytime without side effects |
| Testing | Snapshot-based | User preference - run apply twice, verify no changes second time |
| Test infrastructure | VMs | User preference - bhyve VMs for testing |
| Rollback | Automatic ZFS snapshots | User preference - prominent ZFS usage |
| apply command | Actually applies | User preference - not dry-run by default |

## Architecture

### Platform Strategy
- **Hosts**: FreeBSD only
- **Jails**: Primary service isolation (FreeBSD-native)
- **bhyve VMs**: For Linux-incompatible services
- **ZFS**: Snapshot-based backup/rollback (prominent usage)

### CLI Commands
```
rostyr init <hostname>     # Scaffold new host config
rostyr validate           # Validate all TOML configs
rostyr diff [--host H]   # Show pending changes (dry-run)
rostyr check [--host H]  # Detect current system state
rostyr apply [--host H]  # Apply changes (creates ZFS snapshot first)
rostyr rollback          # Revert to last ZFS snapshot
```

### Idempotency Strategy
1. **Detect** current state (jails, VMs, ZFS, users, packages)
2. **Diff** desired vs actual state
3. **Plan** minimal changes needed
4. **Execute** only when state differs
5. **Snapshot** ZFS before any apply

### Testing Strategy
- **Unit tests**: Config parsing, state detection, diff logic
- **Integration tests**: CLI commands against isolated test VMs
- **Idempotency tests**: Run apply twice, verify no changes on second run (snapshot comparison)
- **VMs for testing**: All tests run in isolated bhyve VMs before production deployment

## Project Created

### Branch
- `draft/initial-setup` (created from main)

### Files
- `README.md` - Project documentation with overview, architecture, roadmap
- `Cargo.toml` - Rust dependencies: clap, toml, serde, thiserror, tracing, anyhow
- `src/main.rs` - CLI with 6 commands scaffolded
- `src/lib.rs` - Module declarations
- `src/{config,state,planner,executor,jail,vm,zfs,commands}/mod.rs` - Placeholder modules

### Directory Structure
```
rostyr/
├── README.md
├── Cargo.toml
├── configs/
│   ├── hosts/
│   ├── users/
│   └── services/
├── src/
│   ├── main.rs
│   ├── lib.rs
│   ├── config/
│   ├── state/
│   ├── planner/
│   ├── executor/
│   ├── jail/
│   ├── vm/
│   ├── zfs/
│   └── commands/
└── tests/
    ├── unit/
    ├── integration/
    └── idempotency/
```

### Status
- Project compiles successfully
- Ready for review/merge to main

## Phased Roadmap

### Phase 1 - Core Foundation
- Project scaffolding (Rust, CLI framework)
- Config parsing (TOML)
- Basic state detection (host info, ZFS)
- init, validate commands

### Phase 2 - Idempotent Apply
- Diff/planner logic
- Apply command with ZFS snapshot
- Rollback command
- check command

### Phase 3 - Jails
- Jail creation/management
- Basic service jail templates
- User management inside jails

### Phase 4 - bhyve VMs
- VM lifecycle management
- Linux VM templates
- Service deployment to VMs

### Phase 5+ - Services
- Individual service implementations (from styr)
- Full port of styr functionality

## styr Reference (for porting)

### Structure (from API)
- `Core/` - Core initialization scripts (freebsd.zsh, init/*.sh, functions.zsh, settings.zsh)
- `Host/` - Host configurations: borgen, london, madrid, rackett, template
- `User/` - User configurations: elisabet, jakob, root, stefan
- `Service/` - Service definitions: arr, bhyve, bitcoind, fah, gitea, iocage, iperf, joinmarket, mariadb, matrix, nfs, specter, tor, transmission, zab
- `Scripts/` - Helper scripts: jmc.zsh, vml, vms

### Description (from repo)
"Set of scripts to configure workstations, servers, virtual machines, and jails"