Standardize error structures across presentation commands

[Copilot]

Error types between Create and Destroy commands used inconsistent patterns: tuple vs struct wrapping, missing actionable tips, and no logical grouping.

Changes

Error Structure Template (docs/contributing/error-handling.md)

• Added comprehensive template showing:
  • Error grouping with section comments
  • Struct-style variants with named fields
  • Actionable tips in error messages
  • .help() method implementation patterns

Create Command Errors

• Converted tuple-style to struct-style for context preservation:

  // Before
  ConfigValidationFailed(#[source] source)
  
  // After
  ConfigValidationFailed {
      #[source]
      source: CreateConfigError,
  }

• Added tips to all variants:
  • ConfigParsingFailed: "Validate JSON syntax with: jq . < {path}"
  • CommandFailed: "Check logs with --log-output file-and-stderr"
  • Others similarly enhanced
• Added section comments:
  • Configuration File Errors
  • Command Execution Errors
  • Template Generation Errors

Destroy Command Errors

• Added section comments for logical grouping (Validation → Repository → Operations)
• Reordered variants to match grouping

Updated Call Sites

• Updated error construction: Error(source) → Error { source }
• Updated pattern matching: Error(_) → Error { .. }
• Files: template.rs, environment.rs, config_loader.rs, tests/integration.rs

Result

All errors now follow uniform patterns:

• Named fields for better pattern matching
• Actionable tips in messages
• Logical grouping with section comments
• Consistent #[source] usage for error chains

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Improve Error Consistency Between Commands</issue_title>
<issue_description>Parent Issue: #63
Type: 🔨 Structural Improvement
Impact: 🟢🟢 Medium
Effort: 🔵🔵 Medium
Priority: P1

Problem

Error structures differ between commands without clear reason:

// Create errors
pub enum CreateSubcommandError {
    ConfigFileNotFound { path: PathBuf },
    InvalidJson { path: PathBuf, source: serde_json::Error },
    TemplateGenerationFailed(CreateConfigError),
}

// Destroy errors
pub enum DestroySubcommandError {
    InvalidEnvironmentName { name: String, source: ... },
    CommandExecutionFailed { source: ... },
    RepositoryAccessFailed { data_dir: String, reason: String },
}

Some use structured fields consistently, others mix approaches.

Proposed Solution

Establish consistent patterns:

1. Always include relevant context (paths, names, etc.)
2. Always use #[source] for error chains
3. Always include brief tips in error messages
4. Group related error types consistently

Example standardized structure:

#[derive(Debug, Error)]
pub enum CreateSubcommandError {
    // File-related errors
    #[error("Configuration file not found: {path}
Tip: Check that the file path is correct: ls -la {path}")]
    ConfigFileNotFound {
        path: PathBuf,
    },

    #[error("Failed to parse configuration file '{path}' as {format}: {source}
Tip: Validate JSON syntax with: jq . < {path}")]
    ConfigParsingFailed {
        path: PathBuf,
        format: String,
        #[source]
        source: serde_json::Error,
    },

    // Command execution errors
    #[error("Create command execution failed: {source}
Tip: Check logs for detailed error information")]
    CommandExecutionFailed {
        #[source]
        source: Box<dyn std::error::Error + Send + Sync>,
    },

    // ... more errors
}

Benefits

• ✅ Predictable error patterns across all commands
• ✅ Better error messages with actionable tips
• ✅ Proper error chain preservation with #[source]
• ✅ Easier to handle errors in tests and calling code

Implementation Checklist

Phase 1: Document standards

• Document error patterns in error handling guide
• Create error structure template
• Add examples of good vs bad error definitions

Phase 2: Standardize create errors

• Review all CreateSubcommandError variants
• Add missing context fields (paths, names, etc.)
• Add #[source] attributes where needed
• Add actionable tips to error messages
• Group related errors together

Phase 3: Standardize destroy errors

• Review all DestroySubcommandError variants
• Add missing context fields
• Add #[source] attributes where needed
• Add actionable tips to error messages
• Group related errors together

Phase 4: Validation

• Verify error messages are helpful and consistent
• Test error chain preservation
• Update tests that check error types
• Run all tests
• Run linter

Acceptance Criteria

• All error types use consistent structure
• All errors include relevant context fields
• All errors use #[source] for error chains
• All error messages include actionable tips
• Error patterns are documented
• All tests pass: cargo test presentation::commands
• Pre-commit checks pass: ./scripts/pre-commit.sh
• Code follows project conventions

Related Documentation

• Error Handling Guide
• Refactor Plan</issue_description>

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

• Fixes Improve Error Consistency Between Commands #71

---

💡 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]

ACK 25826e6