Enum AgpmError 

pub enum AgpmError {
    GitCommandError {
        operation: String,
        stderr: String,
    },
    GitNotFound,
    GitRepoInvalid {
        path: String,
    },
    GitAuthenticationFailed {
        url: String,
    },
    GitCloneFailed {
        url: String,
        reason: String,
    },
    GitCheckoutFailed {
        reference: String,
        reason: String,
    },
    ConfigError {
        message: String,
    },
    ManifestNotFound,
    ManifestParseError {
        file: String,
        reason: String,
    },
    ManifestValidationError {
        reason: String,
    },
    LockfileParseError {
        file: String,
        reason: String,
    },
    InvalidLockfileError {
        file: String,
        reason: String,
        can_regenerate: bool,
    },
    ResourceNotFound {
        name: String,
    },
    ResourceFileNotFound {
        path: String,
        source_name: String,
    },
    SourceNotFound {
        name: String,
    },
    SourceUnreachable {
        name: String,
        url: String,
    },
    InvalidVersionConstraint {
        constraint: String,
    },
    VersionNotFound {
        resource: String,
        version: String,
    },
    AlreadyInstalled {
        name: String,
    },
    InvalidResourceType {
        resource_type: String,
    },
    InvalidResourceStructure {
        file: String,
        reason: String,
    },
    CircularDependency {
        chain: String,
    },
    DependencyResolutionFailed {
        reason: String,
    },
    DependencyResolutionMismatch {
        resource: String,
        declared_count: usize,
        resolved_count: usize,
        declared_deps: Vec<(String, String)>,
    },
    NetworkError {
        operation: String,
        reason: String,
    },
    FileSystemError {
        operation: String,
        path: String,
    },
    PermissionDenied {
        operation: String,
        path: String,
    },
    DirectoryNotEmpty {
        path: String,
    },
    InvalidDependency {
        name: String,
        reason: String,
    },
    InvalidResource {
        name: String,
        reason: String,
    },
    DependencyNotMet {
        name: String,
        required: String,
        found: String,
    },
    ConfigNotFound {
        path: String,
    },
    ChecksumMismatch {
        name: String,
        expected: String,
        actual: String,
    },
    PlatformNotSupported {
        operation: String,
    },
    IoError(Error),
    TomlError(Error),
    TomlSerError(Error),
    SemverError(Error),
    Other {
        message: String,
    },
}

The main error type for AGPM operations

This enum represents all possible errors that can occur during AGPM operations. Each variant is designed to provide specific context about the failure and enable appropriate error handling strategies.

Design Philosophy

• Specific Error Types: Each error variant represents a specific failure mode
• Rich Context: Errors include relevant details like file paths, URLs, and reasons
• User-Friendly: Error messages are written for end users, not just developers
• Actionable: Most errors provide clear guidance on how to resolve the issue

Error Categories

Git Operations

• GitNotFound - Git executable not available
• GitCommandError - Git command execution failed
• GitAuthenticationFailed - Git authentication problems
• GitCloneFailed - Repository cloning failed
• GitCheckoutFailed - Git checkout operation failed

File System Operations

• FileSystemError - General file system operations
• PermissionDenied - Insufficient permissions
• DirectoryNotEmpty - Directory contains files when empty expected
• IoError - Standard I/O errors from std::io::Error

Configuration and Parsing

• ManifestNotFound - agpm.toml file missing
• ManifestParseError - Invalid TOML syntax in manifest
• ManifestValidationError - Manifest content validation failed
• LockfileParseError - Invalid lockfile format
• InvalidLockfileError - Invalid lockfile that can be automatically regenerated
• ConfigError - Configuration file issues
• TomlError - TOML parsing errors from toml::de::Error
• TomlSerError - TOML serialization errors from toml::ser::Error

Resource Management

• ResourceNotFound - Named resource doesn’t exist
• ResourceFileNotFound - Resource file missing from repository
• InvalidResourceType - Unknown resource type specified
• InvalidResourceStructure - Resource content is malformed
• InvalidResource - Resource validation failed
• AlreadyInstalled - Resource already exists

Dependency Resolution

• CircularDependency - Dependency cycle detected
• DependencyResolutionFailed - Cannot resolve dependencies
• DependencyNotMet - Version constraint not satisfied
• InvalidDependency - Malformed dependency specification
• InvalidVersionConstraint - Invalid version format
• VersionNotFound - Requested version doesn’t exist
• SemverError - Semantic version parsing from semver::Error

Source Management

• SourceNotFound - Named source not defined
• SourceUnreachable - Cannot connect to source repository

Platform and Network

• NetworkError - Network connectivity issues
• PlatformNotSupported - Operation not supported on current platform
• ChecksumMismatch - File integrity verification failed

Examples

Pattern Matching on Errors

use agpm_cli::core::AgpmError;

fn handle_error(error: AgpmError) {
    match error {
        AgpmError::GitNotFound => {
            eprintln!("Please install git to use AGPM");
            std::process::exit(1);
        }
        AgpmError::ManifestNotFound => {
            eprintln!("Run 'agpm init' to create a manifest file");
        }
        AgpmError::NetworkError { operation, .. } => {
            eprintln!("Network error during {}: check your connection", operation);
        }
        _ => {
            eprintln!("Unexpected error: {}", error);
        }
    }
}

Creating Specific Errors

use agpm_cli::core::AgpmError;

// Create a git command error with context
let error = AgpmError::GitCommandError {
    operation: "clone".to_string(),
    stderr: "repository not found".to_string(),
};

// Create a resource not found error
let error = AgpmError::ResourceNotFound {
    name: "my-agent".to_string(),
};

// Create a version constraint error
let error = AgpmError::InvalidVersionConstraint {
    constraint: "~1.x.y".to_string(),
};

Variants

GitCommandError

Git operation failed during execution

This error occurs when a git command returns a non-zero exit code. Common causes include network issues, authentication problems, or invalid git repository states.

Fields

• operation: The git operation that failed (e.g., “clone”, “fetch”, “checkout”)
• stderr: The error output from the git command

Fields

operation: String

The git operation that failed (e.g., “clone”, “fetch”, “checkout”)

stderr: String

The error output from the git command

GitNotFound

Git executable not found in PATH

This error occurs when AGPM cannot locate the git command in the system PATH. AGPM requires git to be installed and available for repository operations.

Common solutions:

• Install git from https://git-scm.com/
• Use a package manager: brew install git, apt install git, etc.
• Ensure git is in your PATH environment variable

GitRepoInvalid

Git repository is invalid or corrupted

This error occurs when a directory exists but doesn’t contain a valid git repository structure (missing .git directory or corrupted).

Fields

• path: The path that was expected to contain a git repository

Fields

path: String

The path that was expected to contain a git repository

GitAuthenticationFailed

Git authentication failed for repository access

This error occurs when git cannot authenticate with a remote repository. Common for private repositories or when credentials are missing/expired.

Fields

• url: The repository URL that failed authentication

Fields

url: String

The repository URL that failed authentication

GitCloneFailed

Git repository clone failed

Fields

url: String

The repository URL that failed to clone

reason: String

The reason for the clone failure

GitCheckoutFailed

Git checkout failed

Fields

reference: String

The git reference (branch, tag, or commit) that failed to checkout

reason: String

The reason for the checkout failure

ConfigError

Configuration error

Fields

message: String

Description of the configuration error

ManifestNotFound

Manifest file (agpm.toml) not found

This error occurs when AGPM cannot locate a agpm.toml file in the current directory or any parent directory up to the filesystem root.

AGPM searches for agpm.toml starting from the current working directory and walking up the directory tree, similar to how git searches for .git.

ManifestParseError

Manifest parsing error

Fields

file: String

Path to the manifest file that failed to parse

reason: String

Specific reason for the parsing failure

ManifestValidationError

Manifest validation error

Fields

reason: String

Reason why manifest validation failed

LockfileParseError

Lockfile parsing error

Fields

file: String

Path to the lockfile that failed to parse

reason: String

Specific reason for the parsing failure

InvalidLockfileError

Invalid lockfile that can be automatically regenerated

Fields

file: String

Path to the invalid lockfile

reason: String

Specific reason why the lockfile is invalid

can_regenerate: bool

Whether automatic regeneration is offered

ResourceNotFound

Resource not found

Fields

name: String

Name of the resource that could not be found

ResourceFileNotFound

Resource file not found in repository

Fields

path: String

Path to the resource file within the source repository

source_name: String

Name of the source repository where the file was expected

SourceNotFound

Source repository not found

Fields

name: String

Name of the source repository that is not defined

SourceUnreachable

Source repository unreachable

Fields

name: String

Name of the source repository

url: String

URL of the unreachable repository

InvalidVersionConstraint

Invalid version constraint

Fields

constraint: String

The invalid version constraint string

VersionNotFound

Version not found

Fields

resource: String

Name of the resource for which the version was not found

version: String

The version string that could not be found

AlreadyInstalled

Resource already installed

Fields

name: String

Name of the resource that is already installed

InvalidResourceType

Invalid resource type

Fields

resource_type: String

The invalid resource type that was specified

InvalidResourceStructure

Invalid resource structure

Fields

file: String

Path to the file with invalid resource structure

reason: String

Reason why the resource structure is invalid

CircularDependency

Circular dependency detected in dependency graph

This error occurs when resources depend on each other in a cycle, making it impossible to determine installation order.

Example: A depends on B, B depends on C, C depends on A

Fields

• chain: The dependency chain showing the circular reference

Fields

chain: String

String representation of the circular dependency chain

DependencyResolutionFailed

Dependency resolution failed

Fields

reason: String

Reason why dependency resolution failed

DependencyResolutionMismatch

Dependency resolution mismatch between declared and resolved dependencies

This error occurs when a resource declares N dependencies in its frontmatter but only M dependencies (where M < N) were successfully resolved. This indicates a bug in the dependency resolution process, likely due to path normalization issues.

Fields

• resource: Name of the resource with the mismatch
• declared_count: Number of dependencies declared in frontmatter
• resolved_count: Number of dependencies actually resolved
• declared_deps: List of (resource_type, path) for declared dependencies

Fields

resource: String

Name of the resource with the dependency mismatch

declared_count: usize

Number of dependencies declared in frontmatter

resolved_count: usize

Number of dependencies actually resolved

declared_deps: Vec<(String, String)>

List of declared dependencies as (resource_type, path) tuples

NetworkError

Network error

Fields

operation: String

The network operation that failed

reason: String

Reason for the network failure

FileSystemError

File system error

Fields

operation: String

The file system operation that failed

path: String

Path where the file system error occurred

PermissionDenied

Permission denied

Fields

operation: String

The operation that was denied due to insufficient permissions

path: String

Path where permission was denied

DirectoryNotEmpty

Directory not empty

Fields

path: String

Path to the directory that is not empty

InvalidDependency

Invalid dependency specification

Fields

name: String

Name of the invalid dependency

reason: String

Reason why the dependency specification is invalid

InvalidResource

Invalid resource content

Fields

name: String

Name of the invalid resource

reason: String

Reason why the resource content is invalid

DependencyNotMet

Dependency not met

Fields

name: String

Name of the dependency that is not satisfied

required: String

The required version constraint

found: String

The version that was actually found

ConfigNotFound

Config file not found

Fields

path: String

Path to the configuration file that was not found

ChecksumMismatch

Checksum mismatch

Fields

name: String

Name of the resource with checksum mismatch

expected: String

The expected checksum value

actual: String

The actual checksum that was computed

PlatformNotSupported

Platform not supported

Fields

operation: String

The operation that is not supported on this platform

IoError(Error)

IO error

TomlError(Error)

TOML parsing error

TomlSerError(Error)

TOML serialization error

SemverError(Error)

Semver parsing error

Other

Other error

Fields

message: String

Generic error message

Trait Implementations

impl Debug for AgpmError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for AgpmError

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for AgpmError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0: use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0: replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<Error> for AgpmError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for AgpmError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for AgpmError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for AgpmError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl IntoAnyhowWithContext for AgpmError

fn into_anyhow_with_context(self, context: ErrorContext) -> Error

Convert the error to an anyhow::Error with the provided context