torrust-tracker-deployer 0.1.0

# Torrust Tracker Deployer - Packages

This directory contains reusable Rust workspace packages that support the Torrust Tracker Deployer project. These packages are designed to be modular, maintainable, and potentially reusable across other Torrust projects.

## 📦 Available Packages

### [`dependency-installer/`](./dependency-installer/)

**Purpose**: Dependency detection and installation utilities for development environments

**Key Features**:

- Detects if required development tools are installed (OpenTofu, Ansible, LXD, cargo-machete)
- Installs missing dependencies automatically
- Provides CLI for manual and automated use
- Designed for CI/CD pipelines and automated workflows
- Uses structured logging (tracing) for observability
- Exit-code based success/failure indication for automation

**Use Cases**:

- Setting up development environments for humans and AI agents
- Pre-flight checks in E2E test suites
- CI/CD pipeline dependency validation
- Automated development environment provisioning

**Documentation**: See [packages/dependency-installer/README.md](./dependency-installer/README.md)

### [`deployer-types/`](./deployer-types/)

**Purpose**: Shared value objects and traits for the Torrust Tracker Deployer ecosystem

**Key Features**:

- Validated value objects: `DomainName`, `Email`, `Username`, `EnvironmentName`, `ServiceEndpoint`
- Secret wrappers: `ApiToken` / `PlainApiToken`, `Password` / `PlainPassword` (via `secrecy`)
- Time abstraction: `Clock` trait + `SystemClock` implementation for testability
- Error infrastructure: `ErrorKind` enum + `Traceable` trait
- Minimal dependencies (no tokio, no infrastructure)
- Both the root crate and the SDK crate depend on this package

**Use Cases**:

- Canonical source of cross-cutting value objects shared across workspace packages
- Enables SDK consumers to import foundational types without depending on the full root crate
- Supports independent versioning and future publishing

**Documentation**: See [packages/deployer-types/README.md](./deployer-types/README.md)

### [`sdk/`](./sdk/)

**Purpose**: Programmatic Rust SDK for deploying and managing Torrust Tracker instances

**Key Features**:

- Typed `Deployer` facade with builder pattern for configuration
- Full lifecycle support: create, provision, configure, release, run, test, destroy, purge
- Config validation and environment inspection (`list`, `show`, `exists`)
- Load environment config from JSON files
- Re-exports all domain types consumers need (`EnvironmentCreationConfig`, `EnvironmentName`, etc.)
- Structured error types for programmatic error handling
- Extension point: `CommandProgressListener` for progress callbacks

**Use Cases**:

- Programmatic deployer access without the CLI
- Integration testing of deployment workflows
- Building higher-level tools on top of the deployer
- External consumers that want to depend only on the SDK without CLI modules

**Documentation**: See [packages/sdk/README.md](./sdk/README.md)

## 🏗️ Package Architecture

All packages in this directory:

- Are part of a Cargo workspace (defined in root `Cargo.toml`)
- Can be used independently or as library crates
- Follow the project's development principles (observability, testability, user-friendliness)
- Provide both CLI binaries and programmatic APIs
- Use structured logging via the `tracing` crate
- Follow consistent error handling patterns

## 🚀 Using Packages

### As Library Crates

```rust
// Add to your Cargo.toml
[dependencies]
torrust-tracker-deployer-types = { path = "packages/deployer-types" }
torrust-tracker-deployer-dependency-installer = { path = "packages/dependency-installer" }
torrust-tracker-deployer-sdk = { path = "packages/sdk" }
```

### As CLI Binaries

```bash
# Run the linter
cargo run --bin linter all

# Run the dependency installer
cargo run --bin dependency-installer check
cargo run --bin dependency-installer install
```

### SDK Examples

```bash
cargo run --example sdk_basic_usage -p torrust-tracker-deployer-sdk
cargo run --example sdk_full_deployment -p torrust-tracker-deployer-sdk
cargo run --example sdk_error_handling -p torrust-tracker-deployer-sdk
cargo run --example sdk_create_from_json_file -p torrust-tracker-deployer-sdk
cargo run --example sdk_validate_config -p torrust-tracker-deployer-sdk
```

## 🎯 Package Design Principles

### Automation-First Design

Packages prioritize **automation and CI/CD workflows**:

- **Exit codes** indicate success/failure (0 = success, non-zero = failure)
- **Structured logging** provides rich context without parsing output
- **Flags for verbosity** (`--verbose`, `--log-level`) control output detail
- **Minimal output** by default, detailed only when needed

### Type Safety

- Use strongly-typed enums and structs
- Leverage Rust's type system for compile-time guarantees
- Avoid stringly-typed APIs

### Error Handling

- Clear, actionable error messages
- Preserve error context with source chains
- Use thiserror for structured error types

### Extensibility

- Easy to add new functionality (linters, dependencies)
- Plugin-like architecture where appropriate
- Trait-based abstractions for flexibility

## 📋 Adding New Packages

When creating new packages:

1. **Create package directory** under `packages/`
2. **Add to workspace** in root `Cargo.toml`:

   ```toml
   [workspace]
   members = [
       "packages/your-new-package",
       # ...
   ]
   ```

3. **Create package README** documenting purpose and usage
4. **Update this file** to include the new package in the list above
5. **Follow conventions**:
   - Use `tracing` for logging
   - Provide both CLI and library interfaces
   - Follow project development principles
   - Add comprehensive tests

## 🔗 Related Documentation

- [Development Principles](../docs/development-principles.md) - Core principles guiding all packages
- [Error Handling Guide](../docs/contributing/error-handling.md) - Error handling patterns
- [Testing Conventions](../docs/contributing/testing/) - Testing standards
- [E2E Testing Guide](../docs/e2e-testing/) - How packages integrate with E2E tests

## 💡 Future Packages

Potential future packages that could be added:

- **Configuration Management**: Reusable config loading and validation
- **Template Engine**: Tera template rendering utilities
- **SSH Client**: SSH operations and connectivity checking
- **Infrastructure Clients**: OpenTofu, Ansible, LXD client abstractions
- **Test Utilities**: Common test helpers and fixtures

These packages would further modularize the codebase and improve reusability across the Torrust ecosystem.