Module error 

Error handling for AGPM

This module provides comprehensive error types and user-friendly error reporting for the AGPM package manager. The error system is designed around two core principles:

1. Strongly-typed errors for precise error handling in code
2. User-friendly messages with actionable suggestions for CLI users

Architecture

The error system consists of two main types:

• AgpmError - Enumerated error types for all failure cases in AGPM
• ErrorContext - Wrapper that adds user-friendly messages and suggestions

Error Categories

AGPM errors are organized into several categories:

• Git Operations: AgpmError::GitNotFound, AgpmError::GitCommandError, etc.
• File System: AgpmError::FileSystemError, AgpmError::PermissionDenied, etc.
• Configuration: AgpmError::ManifestNotFound, AgpmError::ManifestParseError, etc.
• Dependencies: AgpmError::CircularDependency, AgpmError::DependencyNotMet, etc.
• Resources: AgpmError::ResourceNotFound, AgpmError::InvalidResource, etc.

Error Conversion and Context

Common standard library errors are automatically converted to AGPM errors:

• std::io::Error → AgpmError::IoError
• toml::de::Error → AgpmError::TomlError
• semver::Error → AgpmError::SemverError

Convert errors into user-friendly format with contextual suggestions.

Examples

Basic Error Handling

use agpm_cli::core::{AgpmError, ErrorContext};

fn handle_git_operation() -> Result<(), AgpmError> {
    // Simulate a git operation failure
    Err(AgpmError::GitNotFound)
}

match handle_git_operation() {
    Ok(_) => println!("Success!"),
    Err(e) => {
        let ctx = ErrorContext::new(e)
            .with_suggestion("Install git from https://git-scm.com/")
            .with_details("AGPM requires git for repository operations");
        ctx.display(); // Shows colored error with suggestions
    }
}

Creating Error Context Manually

use agpm_cli::core::{AgpmError, ErrorContext};

let error = AgpmError::ManifestNotFound;
let context = ErrorContext::new(error)
    .with_suggestion("Create a agpm.toml file in your project directory")
    .with_details("AGPM searches for agpm.toml in current and parent directories");

// Display with colors in terminal
context.display();

// Or get as string for logging
let message = format!("{}", context);

Error Recovery Patterns

use agpm_cli::core::{AgpmError, ErrorContext};

fn install_dependency(name: &str) -> Result<(), AgpmError> {
    // Try installation
    match perform_installation(name) {
        Ok(()) => Ok(()),
        Err(e) => {
            // Convert to user-friendly error for CLI display
            let friendly = ErrorContext::new(e)
                .with_suggestion(format!("Check the dependency name '{}' and try again", name))
                .with_details("AGPM will attempt to install the dependency and its requirements");
            friendly.display(); // Shows colored error with suggestions
            Err(AgpmError::Other { message: "Installation failed".to_string() })
        }
    }
}

fn perform_installation(_name: &str) -> Result<(), AgpmError> {
    // Implementation would go here
    Ok(())
}

Structs

ErrorContext

Error context wrapper that provides user-friendly error information

Enums

AgpmError

The main error type for AGPM operations

Traits

IntoAnyhowWithContext

Extension trait for converting AgpmError to anyhow::Error with context