"""
Module: errors
Description: Typed exceptions for the Huitzo CLI.

Implements:
    - docs/cli/reference.md#error-handling
    - docs/architecture/dev-sessions.md#error-classification

See Also:
    - docs/sdk/errors.md (for SDK error patterns)
"""


class HuitzoCliError(Exception):
    """Base exception for all Huitzo CLI errors."""

    def __init__(self, message: str, user_message: str | None = None) -> None:
        super().__init__(message)
        self.user_message = user_message or message


class AuthenticationError(HuitzoCliError):
    """401, expired token, invalid credentials."""


class NetworkError(HuitzoCliError):
    """Connection refused, timeout, DNS failure."""


class ServerError(HuitzoCliError):
    """5xx responses from the backend."""


class CommandValidationError(HuitzoCliError):
    """422 — command arguments failed validation."""

    def __init__(self, detail: str) -> None:
        super().__init__(detail, user_message=detail)
        self.detail = detail


class CommandNotFoundError(HuitzoCliError):
    """404 — command not found in sandbox."""

    def __init__(self, command_name: str) -> None:
        super().__init__(f"Command not found: {command_name}")
        self.command_name = command_name


class SandboxCommandError(HuitzoCliError):
    """Structured error from sandbox command execution."""

    def __init__(
        self,
        *,
        error_type: str,
        message: str,
        command: str,
        code: str | None = None,
    ) -> None:
        super().__init__(message, user_message=message)
        self.error_type = error_type
        self.command = command
        self.code = code
