ccswarm 0.5.0

use thiserror::Error;

/// Main error type for ccswarm with structured error handling
///
/// This enum provides comprehensive error types for all ccswarm operations,
/// with detailed context and proper error chaining using `thiserror`.
///
/// # Examples
///
/// ```rust
/// use ccswarm::error::CCSwarmError;
///
/// // Creating a configuration error
/// let config_error = CCSwarmError::Configuration {
///     message: "Invalid agent configuration".to_string(),
///     source: None,
/// };
/// ```
#[derive(Error, Debug)]
pub enum CCSwarmError {
    /// IO operation failed
    #[error("IO error: {0}")]
    Io(#[from] std::io::Error),

    /// JSON serialization/deserialization failed
    #[error("JSON error: {0}")]
    SerdeJson(#[from] serde_json::Error),

    /// Configuration related error
    #[error("Configuration error: {message}")]
    Configuration {
        message: String,
        #[source]
        source: Option<Box<dyn std::error::Error + Send + Sync>>,
    },

    /// Agent operation failed
    #[error("Agent error [{agent_id}]: {message}")]
    Agent {
        agent_id: String,
        message: String,
        #[source]
        source: Option<Box<dyn std::error::Error + Send + Sync>>,
    },

    /// Session management error
    #[error("Session error [{session_id}]: {message}")]
    Session {
        session_id: String,
        message: String,
        #[source]
        source: Option<Box<dyn std::error::Error + Send + Sync>>,
    },

    /// Task execution error
    #[error("Task error [{task_id}]: {message}")]
    Task {
        task_id: String,
        message: String,
        #[source]
        source: Option<Box<dyn std::error::Error + Send + Sync>>,
    },

    /// Network communication error
    #[error("Network error: {message}")]
    Network {
        message: String,
        #[source]
        source: Option<Box<dyn std::error::Error + Send + Sync>>,
    },

    /// Orchestrator coordination error
    #[error("Orchestrator error: {message}")]
    Orchestrator {
        message: String,
        task_id: Option<String>,
        #[source]
        source: Option<Box<dyn std::error::Error + Send + Sync>>,
    },

    /// Git operation error
    #[error("Git error: {message}")]
    Git {
        message: String,
        #[source]
        source: Option<Box<dyn std::error::Error + Send + Sync>>,
    },

    /// Template processing error
    #[error("Template error: {message}")]
    Template {
        message: String,
        template_name: Option<String>,
        #[source]
        source: Option<Box<dyn std::error::Error + Send + Sync>>,
    },

    /// Extension system error
    #[error("Extension error [{extension_id}]: {message}")]
    Extension {
        extension_id: String,
        message: String,
        #[source]
        source: Option<Box<dyn std::error::Error + Send + Sync>>,
    },

    /// Resource management error
    #[error("Resource error: {message}")]
    Resource {
        message: String,
        resource_type: Option<String>,
        #[source]
        source: Option<Box<dyn std::error::Error + Send + Sync>>,
    },

    /// Authentication/authorization error
    #[error("Authentication error: {message}")]
    Auth {
        message: String,
        #[source]
        source: Option<Box<dyn std::error::Error + Send + Sync>>,
    },

    /// User-facing error with helpful message
    #[error("{message}")]
    UserError {
        message: String,
        suggestion: Option<String>,
    },

    /// Generic error for cases not covered above
    #[error("{message}")]
    Other {
        message: String,
        #[source]
        source: Option<Box<dyn std::error::Error + Send + Sync>>,
    },
}

impl From<String> for CCSwarmError {
    fn from(error: String) -> Self {
        Self::Other {
            message: error,
            source: None,
        }
    }
}

impl From<&str> for CCSwarmError {
    fn from(error: &str) -> Self {
        Self::Other {
            message: error.to_string(),
            source: None,
        }
    }
}

/// Result type alias for ccswarm operations
pub type Result<T> = std::result::Result<T, CCSwarmError>;

/// Helper trait for creating structured errors
pub trait ErrorContext<T> {
    /// Add context to an error
    fn with_context<F>(self, f: F) -> Result<T>
    where
        F: FnOnce() -> String;

    /// Add context with error source
    fn with_context_and_source<F, E>(self, f: F, source: E) -> Result<T>
    where
        F: FnOnce() -> String,
        E: std::error::Error + Send + Sync + 'static;
}

impl<T, E> ErrorContext<T> for std::result::Result<T, E>
where
    E: std::error::Error + Send + Sync + 'static,
{
    fn with_context<F>(self, f: F) -> Result<T>
    where
        F: FnOnce() -> String,
    {
        self.map_err(|e| CCSwarmError::Other {
            message: f(),
            source: Some(Box::new(e)),
        })
    }

    fn with_context_and_source<F, S>(self, f: F, source: S) -> Result<T>
    where
        F: FnOnce() -> String,
        S: std::error::Error + Send + Sync + 'static,
    {
        self.map_err(|_| CCSwarmError::Other {
            message: f(),
            source: Some(Box::new(source)),
        })
    }
}

/// Convenience methods for creating specific error types
impl CCSwarmError {
    /// Create a configuration error
    pub fn config<S: Into<String>>(message: S) -> Self {
        Self::Configuration {
            message: message.into(),
            source: None,
        }
    }

    /// Create an agent error
    pub fn agent<S: Into<String>, I: Into<String>>(agent_id: I, message: S) -> Self {
        Self::Agent {
            agent_id: agent_id.into(),
            message: message.into(),
            source: None,
        }
    }

    /// Create a session error
    pub fn session<S: Into<String>, I: Into<String>>(session_id: I, message: S) -> Self {
        Self::Session {
            session_id: session_id.into(),
            message: message.into(),
            source: None,
        }
    }

    /// Create an orchestrator error
    pub fn orchestrator<S: Into<String>>(message: S, task_id: Option<String>) -> Self {
        Self::Orchestrator {
            message: message.into(),
            task_id,
            source: None,
        }
    }

    /// Create a task error
    pub fn task<S: Into<String>, I: Into<String>>(task_id: I, message: S) -> Self {
        Self::Task {
            task_id: task_id.into(),
            message: message.into(),
            source: None,
        }
    }

    /// Create a network error
    pub fn network<S: Into<String>>(message: S) -> Self {
        Self::Network {
            message: message.into(),
            source: None,
        }
    }

    /// Create a git error
    pub fn git<S: Into<String>>(message: S) -> Self {
        Self::Git {
            message: message.into(),
            source: None,
        }
    }

    /// Create a template error
    pub fn template<S: Into<String>>(message: S) -> Self {
        Self::Template {
            message: message.into(),
            template_name: None,
            source: None,
        }
    }

    /// Create a template error with template name
    pub fn template_with_name<S: Into<String>, N: Into<String>>(
        message: S,
        template_name: N,
    ) -> Self {
        Self::Template {
            message: message.into(),
            template_name: Some(template_name.into()),
            source: None,
        }
    }

    /// Create an extension error
    pub fn extension<S: Into<String>, I: Into<String>>(extension_id: I, message: S) -> Self {
        Self::Extension {
            extension_id: extension_id.into(),
            message: message.into(),
            source: None,
        }
    }

    /// Create a resource error
    pub fn resource<S: Into<String>>(message: S) -> Self {
        Self::Resource {
            message: message.into(),
            resource_type: None,
            source: None,
        }
    }

    /// Create a resource error with type
    pub fn resource_with_type<S: Into<String>, T: Into<String>>(
        message: S,
        resource_type: T,
    ) -> Self {
        Self::Resource {
            message: message.into(),
            resource_type: Some(resource_type.into()),
            source: None,
        }
    }

    /// Create an authentication error
    pub fn auth<S: Into<String>>(message: S) -> Self {
        Self::Auth {
            message: message.into(),
            source: None,
        }
    }

    /// Create a user-friendly error with suggestion
    pub fn user_error<S: Into<String>>(message: S) -> Self {
        Self::UserError {
            message: message.into(),
            suggestion: None,
        }
    }

    /// Create a user-friendly error with suggestion
    pub fn user_error_with_suggestion<S: Into<String>, T: Into<String>>(
        message: S,
        suggestion: T,
    ) -> Self {
        Self::UserError {
            message: message.into(),
            suggestion: Some(suggestion.into()),
        }
    }

    /// Add a source error to this error
    pub fn with_source<E>(mut self, source: E) -> Self
    where
        E: std::error::Error + Send + Sync + 'static,
    {
        match &mut self {
            Self::Configuration { source: s, .. }
            | Self::Agent { source: s, .. }
            | Self::Session { source: s, .. }
            | Self::Task { source: s, .. }
            | Self::Network { source: s, .. }
            | Self::Git { source: s, .. }
            | Self::Template { source: s, .. }
            | Self::Extension { source: s, .. }
            | Self::Resource { source: s, .. }
            | Self::Auth { source: s, .. }
            | Self::Other { source: s, .. } => {
                *s = Some(Box::new(source));
            }
            _ => {}
        }
        self
    }

    /// Check if this is a recoverable error
    pub fn is_recoverable(&self) -> bool {
        matches!(
            self,
            Self::Network { .. } | Self::Io(_) | Self::Task { .. } | Self::Resource { .. }
        )
    }

    /// Check if this error should be retried
    ///
    /// Returns true for transient errors that may succeed on retry:
    /// - Network errors (connection issues, timeouts)
    /// - Resource errors (temporary resource exhaustion)
    /// - Certain IO errors (connection reset, broken pipe, etc.)
    pub fn should_retry(&self) -> bool {
        match self {
            Self::Network { .. } | Self::Resource { .. } => true,
            Self::Io(io_err) => {
                // Retry transient IO errors
                matches!(
                    io_err.kind(),
                    std::io::ErrorKind::ConnectionReset
                        | std::io::ErrorKind::ConnectionAborted
                        | std::io::ErrorKind::BrokenPipe
                        | std::io::ErrorKind::TimedOut
                        | std::io::ErrorKind::Interrupted
                        | std::io::ErrorKind::WouldBlock
                )
            }
            _ => false,
        }
    }

    /// Get the suggested delay before retrying this error
    ///
    /// Returns a duration based on the error type:
    /// - Network errors: 1 second (allow network recovery)
    /// - Resource errors: 2 seconds (allow resource cleanup)
    /// - IO errors: 500ms (quick retry for transient issues)
    pub fn suggested_retry_delay(&self) -> std::time::Duration {
        match self {
            Self::Network { .. } => std::time::Duration::from_secs(1),
            Self::Resource { .. } => std::time::Duration::from_secs(2),
            Self::Io(_) => std::time::Duration::from_millis(500),
            _ => std::time::Duration::from_secs(1),
        }
    }

    /// Get the maximum number of retries recommended for this error
    ///
    /// Returns different limits based on error type:
    /// - Network errors: 3 retries
    /// - Resource errors: 5 retries (may need more time to recover)
    /// - IO errors: 2 retries
    /// - Non-retryable errors: 0 retries
    pub fn max_retries(&self) -> u32 {
        if !self.should_retry() {
            return 0;
        }
        match self {
            Self::Network { .. } => 3,
            Self::Resource { .. } => 5,
            Self::Io(_) => 2,
            _ => 0,
        }
    }

    /// Get error severity level
    pub fn severity(&self) -> ErrorSeverity {
        match self {
            Self::Auth { .. } | Self::Configuration { .. } => ErrorSeverity::Critical,
            Self::Agent { .. }
            | Self::Session { .. }
            | Self::Extension { .. }
            | Self::Orchestrator { .. } => ErrorSeverity::High,
            Self::Task { .. } | Self::Git { .. } | Self::Template { .. } => ErrorSeverity::Medium,
            Self::Network { .. } | Self::Resource { .. } => ErrorSeverity::Low,
            Self::Io(_) | Self::SerdeJson(_) => ErrorSeverity::Medium,
            Self::UserError { .. } => ErrorSeverity::Info,
            Self::Other { .. } => ErrorSeverity::Medium,
        }
    }
}

/// Error severity levels for monitoring and alerting
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum ErrorSeverity {
    /// Informational - no action needed
    Info,
    /// Low severity - monitoring recommended
    Low,
    /// Medium severity - investigation needed
    Medium,
    /// High severity - immediate attention required
    High,
    /// Critical severity - system failure
    Critical,
}

impl std::fmt::Display for ErrorSeverity {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Info => write!(f, "INFO"),
            Self::Low => write!(f, "LOW"),
            Self::Medium => write!(f, "MEDIUM"),
            Self::High => write!(f, "HIGH"),
            Self::Critical => write!(f, "CRITICAL"),
        }
    }
}

// ============================================================================
// FatalError Trait - Inspired by Zellij's error classification pattern
// ============================================================================

/// Trait for classifying errors as fatal or non-fatal.
///
/// Fatal errors indicate unrecoverable conditions that should cause the
/// operation to abort completely. Non-fatal errors can be handled gracefully
/// with fallback behavior.
///
/// # Example
/// ```rust
/// use ccswarm::error::{FatalError, ClassifiedError};
///
/// fn process() -> Result<(), ClassifiedError<std::io::Error>> {
///     // Mark an error as fatal
///     std::fs::read("critical_config.json")
///         .map_err(|e| ClassifiedError::fatal(e))?;
///     Ok(())
/// }
/// ```
pub trait FatalError: Sized {
    /// Mark this error as fatal (unrecoverable)
    fn fatal(self) -> ClassifiedError<Self>;

    /// Mark this error as non-fatal (recoverable)
    fn non_fatal(self) -> ClassifiedError<Self>;
}

/// An error wrapper that classifies the error as fatal or non-fatal.
///
/// This enables graceful degradation by allowing callers to handle
/// non-fatal errors differently from fatal ones.
#[derive(Debug)]
pub struct ClassifiedError<E> {
    /// The underlying error
    pub error: E,
    /// Whether this error is fatal
    pub is_fatal: bool,
}

impl<E> ClassifiedError<E> {
    /// Create a fatal error
    pub fn fatal(error: E) -> Self {
        Self {
            error,
            is_fatal: true,
        }
    }

    /// Create a non-fatal error
    pub fn non_fatal(error: E) -> Self {
        Self {
            error,
            is_fatal: false,
        }
    }

    /// Check if this error is fatal
    pub fn is_fatal(&self) -> bool {
        self.is_fatal
    }

    /// Get the underlying error
    pub fn into_inner(self) -> E {
        self.error
    }

    /// Map the error to a different type
    pub fn map<F, O>(self, f: F) -> ClassifiedError<O>
    where
        F: FnOnce(E) -> O,
    {
        ClassifiedError {
            error: f(self.error),
            is_fatal: self.is_fatal,
        }
    }
}

impl<E: std::fmt::Display> std::fmt::Display for ClassifiedError<E> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        if self.is_fatal {
            write!(f, "[FATAL] {}", self.error)
        } else {
            write!(f, "{}", self.error)
        }
    }
}

impl<E: std::error::Error + 'static> std::error::Error for ClassifiedError<E> {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        Some(&self.error)
    }
}

/// Implement FatalError for any error type
impl<E> FatalError for E {
    fn fatal(self) -> ClassifiedError<Self> {
        ClassifiedError::fatal(self)
    }

    fn non_fatal(self) -> ClassifiedError<Self> {
        ClassifiedError::non_fatal(self)
    }
}

/// Extension trait for Result types to easily classify errors
pub trait ResultFatalExt<T, E> {
    /// Mark the error as fatal if Result is Err
    fn fatal_on_err(self) -> std::result::Result<T, ClassifiedError<E>>;

    /// Mark the error as non-fatal if Result is Err
    fn non_fatal_on_err(self) -> std::result::Result<T, ClassifiedError<E>>;
}

impl<T, E> ResultFatalExt<T, E> for std::result::Result<T, E> {
    fn fatal_on_err(self) -> std::result::Result<T, ClassifiedError<E>> {
        self.map_err(ClassifiedError::fatal)
    }

    fn non_fatal_on_err(self) -> std::result::Result<T, ClassifiedError<E>> {
        self.map_err(ClassifiedError::non_fatal)
    }
}

/// Convert CCSwarmError to user-friendly error messages with suggestions
impl CCSwarmError {
    /// Convert this error to a user-friendly error with actionable suggestions
    pub fn to_user_error(&self) -> crate::utils::user_error::UserError {
        use crate::utils::user_error::UserError;

        match self {
            Self::Configuration { message, .. } => {
                UserError::new("Configuration Error", message.as_str())
                    .with_suggestion("Check your ccswarm.json file. Run 'ccswarm doctor' to diagnose configuration issues.")
            }
            Self::Agent { agent_id, message, .. } => {
                UserError::new(format!("Agent Error [{}]", agent_id), message.as_str())
                    .with_suggestion(format!(
                        "Check agent '{}' status with 'ccswarm status --agent {}'. Try 'ccswarm doctor --fix' to resolve common issues.",
                        agent_id, agent_id
                    ))
            }
            Self::Session { session_id, message, .. } => {
                UserError::new(format!("Session Error [{}]", session_id), message.as_str())
                    .with_suggestion("Run 'ccswarm session list' to check active sessions. Try restarting with 'ccswarm stop && ccswarm start'.")
            }
            Self::Task { task_id, message, .. } => {
                UserError::new(format!("Task Error [{}]", task_id), message.as_str())
                    .with_suggestion(format!(
                        "Check task status with 'ccswarm task list'. Retry with 'ccswarm task retry {}'.",
                        task_id
                    ))
            }
            Self::Network { message, .. } => {
                UserError::new("Network Error", message.as_str())
                    .with_suggestion("Check your network connection and API keys. Run 'ccswarm doctor --check-api' to test connectivity.")
            }
            Self::Git { message, .. } => {
                UserError::new("Git Error", message.as_str())
                    .with_suggestion("Ensure you're in a Git repository. Run 'git status' to check, or 'ccswarm doctor' for diagnostics.")
            }
            Self::Auth { message, .. } => {
                UserError::new("Authentication Error", message.as_str())
                    .with_suggestion("Verify your API key is set: ANTHROPIC_API_KEY for Claude. Run 'ccswarm doctor --check-api'.")
            }
            Self::Orchestrator { message, .. } => {
                UserError::new("Orchestrator Error", message.as_str())
                    .with_suggestion("Try restarting the orchestrator: 'ccswarm stop && ccswarm start'.")
            }
            Self::Resource { message, resource_type, .. } => {
                let detail = resource_type.as_deref().unwrap_or("unknown");
                UserError::new(format!("Resource Error ({})", detail), message.as_str())
                    .with_suggestion("Check system resources with 'ccswarm health --resources'. Close unnecessary processes and retry.")
            }
            Self::Io(io_err) => {
                UserError::new("I/O Error", &io_err.to_string())
                    .with_suggestion("Check file permissions and disk space. Ensure the target path exists.")
            }
            Self::SerdeJson(json_err) => {
                UserError::new("JSON Parse Error", &json_err.to_string())
                    .with_suggestion("Check your configuration file for syntax errors. Use a JSON validator to find issues.")
            }
            Self::UserError { message, suggestion } => {
                let err = UserError::new("Error", message.as_str());
                if let Some(s) = suggestion {
                    err.with_suggestion(s.clone())
                } else {
                    err
                }
            }
            Self::Template { message, template_name, .. } => {
                let title = match template_name {
                    Some(name) => format!("Template Error [{}]", name),
                    None => "Template Error".to_string(),
                };
                UserError::new(title, message.as_str())
                    .with_suggestion("Check available templates with 'ccswarm template list'.")
            }
            Self::Extension { extension_id, message, .. } => {
                UserError::new(format!("Extension Error [{}]", extension_id), message.as_str())
                    .with_suggestion("Run 'ccswarm extend list' to check extension status.")
            }
            Self::Other { message, .. } => {
                UserError::new("Error", message.as_str())
                    .with_suggestion("Run 'ccswarm doctor' for diagnostics. Use '--verbose' for more details.")
            }
        }
    }
}

/// Determine if a CCSwarmError should be treated as fatal
impl CCSwarmError {
    /// Check if this error should be treated as fatal
    ///
    /// Fatal errors are those that indicate system-level failures
    /// that cannot be recovered from:
    /// - Authentication failures
    /// - Critical configuration errors
    /// - Orchestrator failures
    pub fn is_fatal(&self) -> bool {
        matches!(
            self,
            Self::Auth { .. } | Self::Configuration { .. } | Self::Orchestrator { .. }
        )
    }

    /// Convert to a ClassifiedError based on error type
    pub fn classify(self) -> ClassifiedError<Self> {
        if self.is_fatal() {
            ClassifiedError::fatal(self)
        } else {
            ClassifiedError::non_fatal(self)
        }
    }
}