Relevant source files

The following files were used as context for generating this wiki page: - [jules_cli/exceptions.py](https://github.com/fanioz/jules-cli/blob/main/jules_cli/exceptions.py) - [tests/test_exceptions.py](https://github.com/fanioz/jules-cli/blob/main/tests/test_exceptions.py) - [jules_cli/client.py](https://github.com/fanioz/jules-cli/blob/main/jules_cli/client.py) - [tests/test_client.py](https://github.com/fanioz/jules_cli/blob/main/tests/test_client.py) - [jules_cli/cli.py](https://github.com/fanioz/jules-cli/blob/main/jules_cli/cli.py) - [jules_cli/config.py](https://github.com/fanioz/jules-cli/blob/main/jules_cli/config.py) - [tests/test_config.py](https://github.com/fanioz/jules-cli/blob/main/tests/test_config.py)

# Exception Hierarchy ## Introduction The Jules CLI implements a structured exception hierarchy to handle various error states encountered during interaction with the Jules REST API and local environment configuration. The system is designed to provide granular error reporting, allowing the CLI to distinguish between authentication issues, network failures, resource availability, and internal server errors. By inheriting from a central base class, the exception system ensures that errors can be caught broadly or specifically depending on the context of the operation. This hierarchy plays a critical role in the CLI's stability, providing the `OutputFormatter` with standardized error messages to display to the user. Sources: [jules_cli/exceptions.py:1-42](), [jules_cli/cli.py:92-101]() ## Core Exception Structure The hierarchy is rooted in the standard Python `Exception` class, with `JulesAPIError` serving as the base for all project-specific errors. This structure allows the application to catch all CLI-related issues in a single `except` block when detailed differentiation is not required. ### Class Diagram The following diagram illustrates the inheritance relationship between the custom exception classes defined in the project. ```mermaid classDiagram class Exception class JulesAPIError { } class AuthenticationError { } class ResourceNotFoundError { } class RateLimitError { } class ServerError { } class NetworkError { } class ConfigurationError { } Exception <|-- JulesAPIError JulesAPIError <|-- AuthenticationError JulesAPIError <|-- ResourceNotFoundError JulesAPIError <|-- RateLimitError JulesAPIError <|-- ServerError JulesAPIError <|-- NetworkError JulesAPIError <|-- ConfigurationError ``` Sources: [jules_cli/exceptions.py:1-42](), [tests/test_exceptions.py:12-20]() ### Exception Categories The exceptions are categorized based on the layer of the application where the error originates: | Exception Class | Originating Layer | Description | |:---|:---|:---| | `JulesAPIError` | Base | The parent class for all custom exceptions in the CLI. | | `AuthenticationError` | API Client | Raised when the API returns a `401 Unauthorized` status or the API key is invalid. | | `ResourceNotFoundError`| API Client | Raised when a requested resource (e.g., session or source) returns a `404 Not Found`. | | `RateLimitError` | API Client | Raised when the API returns a `429 Too Many Requests` status. | | `ServerError` | API Client | Triggered by `5xx` status codes indicating server-side failures. | | `NetworkError` | API Client | Handles low-level transport issues like connection timeouts or DNS failures. | | `ConfigurationError` | Config Manager| Raised during local environment issues, such as missing config files or missing API keys. | Sources: [jules_cli/exceptions.py:4-42](), [tests/test_client.py:97-160](), [jules_cli/config.py:115-118]() ## API Error Mapping The `JulesAPIClient` is responsible for translating HTTP status codes and library-specific exceptions into the Jules CLI exception hierarchy. This translation occurs within the `_make_request` method, ensuring that the rest of the application interacts only with project-specific error types. ```mermaid flowchart TD Req[API Request] --> Resp{HTTP Status?} Resp -- 200/201 --> Success[Return JSON] Resp -- 401 --> AuthErr[AuthenticationError] Resp -- 404 --> NotFound[ResourceNotFoundError] Resp -- 429 --> RateErr[RateLimitError] Resp -- 5xx --> ServErr[ServerError] Resp -- Timeout --> NetErr[NetworkError] Resp -- ConnRefused --> NetErr ``` Sources: [jules_cli/client.py:65-95](), [tests/test_client.py:155-175]() ### Handling Logic in Client The client uses the `requests` library and catches specific exceptions to re-raise them as internal types: - **HTTP 401**: Maps to `AuthenticationError`. - **HTTP 404**: Maps to `ResourceNotFoundError`. - **HTTP 429**: Maps to `RateLimitError`. - **HTTP 5xx**: Maps to `ServerError`. - **ConnectionTimeout / ConnectionError**: Maps to `NetworkError`. Sources: [jules_cli/client.py:80-92](), [tests/test_client.py:165-180]() ## Configuration Errors The `ConfigurationError` exception is distinct as it primarily handles local state rather than remote API responses. The `ConfigManager` raises this when: 1. The configuration file is missing and an operation requires it. 2. The API key cannot be resolved from CLI arguments, environment variables, or the config file. 3. The configuration fails validation (e.g., invalid output format). Sources: [jules_cli/config.py:60-120](), [tests/test_config.py:105-115]() ## CLI Error Presentation When an exception is raised, the `cli.py` module catches `JulesAPIError` (the base class) and uses the `OutputFormatter` to display a user-friendly message before exiting with a non-zero status code. ```python # Implementation pattern in jules_cli/cli.py try: data = client.list_sources() output = formatter.format_sources(data) click.echo(output) except JulesAPIError as e: formatter = OutputFormatter(ctx.obj.get("format", "plain")) error_output = formatter.format_error(str(e)) click.echo(error_output, err=True) sys.exit(1) ``` Sources: [jules_cli/cli.py:87-101](), [jules_cli/formatter.py:165-178]() ## Summary The Jules CLI Exception Hierarchy provides a robust framework for error management. By centralizing exception definitions in `exceptions.py` and enforcing their use through the `JulesAPIClient` and `ConfigManager`, the project maintains a clear separation between low-level technical failures and high-level application logic. This allows for consistent error reporting across all CLI commands.