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

Use user_friendly_error to convert any error into a user-friendly format with contextual suggestions.

Examples

Basic Error Handling

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

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 = user_friendly_error(anyhow::Error::from(e));
        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, user_friendly_error};
use anyhow::Context;

fn install_dependency(name: &str) -> anyhow::Result<()> {
    // Try installation
    perform_installation(name)
        .with_context(|| format!("Failed to install dependency '{}'", name))
        .map_err(|e| {
            // Convert to user-friendly error for CLI display
            let friendly = user_friendly_error(e);
            friendly.display();
            anyhow::anyhow!("Installation failed")
        })
}

fn perform_installation(_name: &str) -> anyhow::Result<()> {
    // 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

Functions

user_friendly_error

Convert any error to a user-friendly ErrorContext with actionable suggestions