feat: [#40] Add struct-based template generation for configuration files

[Copilot]

Implements template generation for JSON configuration files using struct-based generation instead of hardcoded strings, following the domain-driven design approach.

Implementation

Module: src/domain/config/environment_config.rs

Added two methods to EnvironmentCreationConfig:

• template() - Creates a configuration instance with placeholder values
• generate_template_file() - Async file generation with directory creation

Error Handling: src/domain/config/errors.rs

Extended CreateConfigError with template generation error variants:

• TemplateSerializationFailed - JSON serialization errors
• TemplateDirectoryCreationFailed - Directory creation failures
• TemplateFileWriteFailed - File write errors

All errors include .help() methods with actionable troubleshooting guidance.

Template Design

Uses simple REPLACE_WITH_* placeholders for user clarity:

{
  "environment": {
    "name": "REPLACE_WITH_ENVIRONMENT_NAME"
  },
  "ssh_credentials": {
    "private_key_path": "REPLACE_WITH_SSH_PRIVATE_KEY_PATH",
    "public_key_path": "REPLACE_WITH_SSH_PUBLIC_KEY_PATH",
    "username": "torrust",
    "port": 22
  }
}

API

use torrust_tracker_deployer_lib::domain::config::EnvironmentCreationConfig;
use std::path::Path;

// Get template instance with placeholders
let template = EnvironmentCreationConfig::template();

// Generate template file at specific path
EnvironmentCreationConfig::generate_template_file(
    Path::new("./config.json")
).await?;

Architecture Benefits

• Type-Safe: Compiler guarantees template structure matches EnvironmentCreationConfig
• Zero Duplication: Struct definition IS the template - no separate strings to maintain
• Auto-Synced: Adding/removing fields automatically updates template
• Guaranteed Valid JSON: serde_json ensures serialization correctness
• Domain Layer: Template generation lives with domain model, not infrastructure

Testing

• ✅ 11 new tests (8 for template generation, 3 for error handling)
• ✅ 962 total tests passing
• ✅ All linters passing

Integration: Ready for CLI --generate-template flag (Issue #37)

• Fixes [Subissue 6/7] Template System Integration (Optional) #40

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Subissue 6/7] Template System Integration (Optional)</issue_title>
<issue_description>Parent Epic: #34 - Implement Create Environment Command
Status: OPTIONAL ENHANCEMENT
Estimated Time: 2-3 hours

⚠️ Note: This is an optional enhancement that can be deferred. It is not required for the MVP functionality of the create command.

Overview

Implement the template system for configuration file generation in the infrastructure layer. This system provides embedded JSON configuration templates that can be generated on-demand, supporting the --generate-template functionality with proper error handling and validation.

Goals

• Extend existing TemplateManager from src/domain/template/embedded.rs for configuration templates
  • Use existing template infrastructure - no duplication needed
  • Add configuration template types to existing embedded template system
  • Leverage existing rust-embed pattern in templates/ directory structure
  • Use existing TemplateManagerError for error handling
• Add configuration templates to existing template structure
  • Add to existing templates/ directory following existing patterns
  • Use existing Tera variable syntax: {{ variable_name }} (not { { variable_name } })
  • Follow existing template embedding and extraction patterns
• Add --generate-template functionality using existing template infrastructure
• Add unit tests that integrate with existing template system

Architecture Requirements

DDD Layer: Infrastructure Layer (src/infrastructure/templates/)
Pattern: Template Provider + Embedded Resources + File Operations
Dependencies: None (infrastructure concern)

Template Example

{
  "environment": {
    "name": "{{ environment_name }}"
  },
  "ssh_credentials": {
    "private_key_path": "{{ ssh_private_key_path }}",
    "public_key_path": "{{ ssh_public_key_path }}",
    "username": "{{ ssh_username }}",
    "port": {{ ssh_port }}
  }
}

Acceptance Criteria

• Template provider extends existing TemplateManager infrastructure
• Templates use correct Tera variable syntax: {{ variable }}
• Templates generate valid JSON files
• Error handling follows tiered help system pattern
• Unit tests verify template generation works correctly
• Integration tests verify file system operations
• Templates are embedded in binary using existing rust-embed pattern

Implementation Notes

• Reuse existing TemplateManager from src/domain/template/embedded.rs
• Add configuration templates to templates/ directory structure
• Use existing error types from template system
• Follow patterns established in OpenTofu/Ansible template management

For detailed specification, see: docs/issues/epic-create-environment-command-subissue-6-template-system-integration.md</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [Subissue 6/7] Template System Integration (Optional) #40

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[josecelano]

@copilot

Summary

Thank you for working on this! The implementation is well-structured with good tests and error handling. However, after reviewing the approach, I've identified a better solution that avoids template duplication and is more maintainable.

The Issue

The current implementation creates a new template infrastructure with a hardcoded JSON const string. While this works, it has some drawbacks:

1. Duplicates the struct definition: The JSON template duplicates EnvironmentCreationConfig's structure
2. Manual sync required: Changes to EnvironmentCreationConfig require manual updates to the template string
3. Not type-safe: Template is a string literal that can become out of sync with the actual struct

The Better Approach: Struct-Based Generation

Since the template structure exactly matches EnvironmentCreationConfig, we should generate it programmatically from the struct itself:

impl EnvironmentCreationConfig {
    pub fn template() -> Self {
        Self {
            environment: EnvironmentSection {
                name: "REPLACE_WITH_ENVIRONMENT_NAME".to_string(),
            },
            ssh_credentials: SshCredentialsConfig {
                private_key_path: "REPLACE_WITH_SSH_PRIVATE_KEY_PATH".to_string(),
                public_key_path: "REPLACE_WITH_SSH_PUBLIC_KEY_PATH".to_string(),
                username: "torrust".to_string(), // default
                port: 22, // default
            },
        }
    }
    
    pub async fn generate_template_file(path: &Path) -> Result<(), TemplateGenerationError> {
        let template = Self::template();
        let json = serde_json::to_string_pretty(&template)?;
        tokio::fs::write(path, json).await?;
        Ok(())
    }
}

Benefits:

• ✅ Type-safe: Compiler guarantees structure matches the config
• ✅ Zero duplication: Struct definition IS the template
• ✅ Auto-synced: Add/remove fields → template auto-updates
• ✅ Guaranteed valid JSON: serde handles serialization
• ✅ Simpler: Just methods on existing domain type

Updated Requirements

I've updated the issue documentation to reflect this approach:

• New spec: docs/issues/40-subissue-6-template-system-integration-v2.md
• Original spec: Deprecated with explanation of why

The new spec includes:

• Complete implementation with code examples
• Comprehensive test cases
• Error handling approach (your error types are good and can be adapted!)
• Clear explanation of why this approach is better

What Can Be Salvaged

Your PR has excellent work that can be reused:

1. ✅ Error handling structure: The TemplateError with help system is great
2. ✅ Test coverage approach: Comprehensive test cases
3. ✅ Async file operations: Good use of tokio::fs

Next Steps

Could you update the PR to use the struct-based generation approach? The main changes would be:

1. Move implementation to src/domain/config/environment_config.rs
2. Replace embedded.rs const string with template() method on the struct
3. Adapt your error types (they're good! just need minor adjustments)
4. Keep your test structure but update to test struct generation
5. Remove src/infrastructure/templates/ module (not needed)

The new spec has all the details and code examples. Let me know if you need any clarification!

---

Why the Original Approach Was Confusing

The original issue spec suggested "extending TemplateManager" which was misleading because:

• TemplateManager is for infrastructure templates (Ansible, OpenTofu files)
• This feature generates user configuration templates
• These are different concerns that shouldn't share infrastructure

The updated spec clarifies this distinction and explains why struct-based generation is the right choice.

[Copilot]

@copilot

Summary...

Refactored to use the struct-based approach as suggested!

Changes in commit 691a1c7:

• Removed src/infrastructure/templates/ module (-762 lines)
• Added template() and generate_template_file() methods to EnvironmentCreationConfig
• Added template generation error types to CreateConfigError
• Adapted error handling with .help() methods

Benefits realized:

• ✅ Type-safe: Compiler guarantees template structure matches struct
• ✅ Zero duplication: Struct definition IS the template
• ✅ Auto-synced: Adding/removing fields automatically updates template
• ✅ Simpler: 627 fewer lines of code

Test results:

• 11 new tests (8 for template generation, 3 for errors)
• 962 total tests passing
• All linters passing

The template is now generated programmatically from the struct, making it impossible for them to get out of sync.

[josecelano]

ACK 691a1c7