feat(errors): add structured error handling

Author: Scott Kostolni

README.md

@@ -94,6 +94,14 @@ Notes: You can define multiple profiles (e.g., `[default]`, `[work]`) and select
 - `limitless export-markdown --limit 5` / `--date YYYY-MM-DD --combine` — print or write markdown exports.
 - `limitless export-csv --date 2025-11-01 --output /tmp/lifelogs.csv` — dump metadata (add `--include-markdown` to include body content).
 
+## Error handling & exit codes
+
+- Network failures (including timeouts) are retried when safe and surface as concise `ApiError` messages (`HTTP 429` with Retry-After hints, or `Request timed out …`).
+- Local persistence issues (e.g., unwritable data dir) become `StorageError`/`StateError` with the offending path in the context.
+- The CLI wraps those exceptions in friendly stderr output so you see a single `Error: …` line instead of a Python traceback; pass `-v/--verbose` to capture the stack trace in logs if needed.
+- Exit codes: `0` success, `1` operational/service errors, `2` validation/config problems (e.g., invalid timezone, missing `--date` when using `--combine`), `130` for `Ctrl+C` aborts.
+- Errors also drive JSON logging via `--verbose`, so CI logs include structured context without leaking secrets.
+
 ## Documentation
 
 - Usage guide: docs/USAGE.md

docs/TASKS.md

@@ -17,7 +17,7 @@ Status: living document; update as work progresses. Use TDD for every task.
 - Combined per‑date Markdown export (`export-markdown --date ... --write-dir ... --combine`)
 - Env integration in CLI: auto-load `.env` at startup
 - Structured JSON logging and log levels (`--verbose`)
-- Improved error messages for non-retryable 4xx/5xx
+- Centralized error handling: exception hierarchy, timeout-aware HTTP errors, and CLI exit codes with friendly stderr output
 - Timezone validation in CLI (IANA names) and documented behavior
 - Performance: tuned defaults; added `--batch-size`
 - User-scoped config file (TOML) with precedence: CLI flags > env > config; `--config`/`--profile`

docs/USAGE.md

@@ -115,6 +115,13 @@ python -m limitless_tools.cli.main search --query "Weekly Meeting" --fuzzy --fuz
 
 Regex searches accept `--regex` or the short form `-rg` and are case-insensitive; fuzzy search uses `rapidfuzz` when available (falls back to `difflib`) with `--fuzzy-threshold` defaulting to `80`.
 
+### Error handling & exit codes
+
+- The HTTP client retries `429/502/503/504` responses (respecting `Retry-After`) and wraps network failures/timeouts in `ApiError` so the CLI can surface a concise message such as `Error: Request timed out while fetching lifelogs.`
+- Storage/state operations raise `StorageError`/`StateError` with the problematic path in their context; services rewrap them as `ServiceError` for consistent CLI UX.
+- Exit codes: `0` success, `1` operational/service errors (HTTP/network/storage), `2` validation/config issues (e.g., invalid timezone, missing `--date` when using `--combine`), `130` when the user interrupts with `Ctrl+C`.
+- The CLI prints only a single `Error: …` line to stderr; pass `-v/--verbose` (or set `LIMITLESS_DEBUG=1`) to include full stack traces in the structured logs while keeping stdout clean for JSON piping.
+
 ### Configuration file (MVP)
 
 You can store defaults in a user config TOML and select profiles via `--profile`:

limitless_tools/cli/main.py

@@ -13,6 +13,7 @@
 from limitless_tools.config.env import load_env
 from limitless_tools.config.logging import setup_logging
 from limitless_tools.config.paths import default_data_dir, expand_path
+from limitless_tools.errors import LimitlessError, ValidationError
 from limitless_tools.services.lifelog_service import LifelogService, SaveReport
 
 
@@ -159,48 +160,34 @@ def _normalize_data_dir(value: str | None, *, base_dir: str | None = None) -> st
     return default_data_dir()
 
 
-def main(argv: list[str] | None = None) -> int:
-    # Ensure .env and related environment variables are loaded before parsing
-    load_env()
-    parser = _build_parser()
-    args = parser.parse_args(args=argv)
-    setup_logging(verbose=bool(getattr(args, "verbose", False)))
-
-    log = logging.getLogger("limitless_tools.cli")
-    log.info("cli_start", extra={"event": "cli_start", "command": args.command})
-    if getattr(args, "verbose", False):
-        # Emit a debug message for tests/diagnostics (avoid reserved LogRecord keys)
-        log.debug("parsed_args", extra={"cli_args": vars(args)})
-
-    # Load config and resolve profile
-    # Allow env var overrides for config path and profile
-    config_path_arg = args.config or os.getenv("LIMITLESS_CONFIG")
-    resolved_config_path = expand_path(config_path_arg) or default_config_path()
-    profile_name = args.profile or os.getenv("LIMITLESS_PROFILE") or "default"
-
-    cfg = load_config(resolved_config_path)
-    prof = get_profile(cfg, profile_name)
-    config_base_dir = str(Path(resolved_config_path).expanduser().parent)
-
-    # Precedence: CLI flags > environment variables > config > defaults
-    argv_list = argv or []
-
+def _coerce_timeout_value(value: object, log: logging.Logger) -> float | None:
+    if isinstance(value, (int, float)):
+        return float(value)
+    if isinstance(value, str):
+        stripped = value.strip()
+        if not stripped:
+            return None
+        try:
+            return float(stripped)
+        except ValueError:
+            log.debug("Invalid http_timeout config value: %s", value)
+    return None
+
+
+def _execute_command(
+    *,
+    args: argparse.Namespace,
+    argv_list: list[str],
+    prof: dict,
+    config_base_dir: str,
+    parser: argparse.ArgumentParser,
+    log: logging.Logger,
+    resolved_config_path: str,
+    profile_name: str,
+) -> int:
     def _provided(opt: str) -> bool:
         return opt in argv_list
 
-    def _coerce_timeout_value(value: object) -> float | None:
-        if isinstance(value, (int, float)):
-            return float(value)
-        if isinstance(value, str):
-            stripped = value.strip()
-            if not stripped:
-                return None
-            try:
-                return float(stripped)
-            except ValueError:
-                log.debug("Invalid http_timeout config value: %s", value)
-        return None
-
     # data_dir precedence
     data_dir_from_config = False
     if not _provided("--data-dir") and not os.getenv("LIMITLESS_DATA_DIR"):
@@ -223,7 +210,7 @@ def _coerce_timeout_value(value: object) -> float | None:
     resolved_api_url = os.getenv("LIMITLESS_API_URL") or (prof.get("api_url") if isinstance(prof.get("api_url"), str) else None)
     resolved_http_timeout: float | None = None
     if not os.getenv("LIMITLESS_HTTP_TIMEOUT"):
-        resolved_http_timeout = _coerce_timeout_value(prof.get("http_timeout"))
+        resolved_http_timeout = _coerce_timeout_value(prof.get("http_timeout"), log)
 
     args.data_dir = _normalize_data_dir(
         getattr(args, "data_dir", None),
@@ -273,11 +260,12 @@ def _coerce_timeout_value(value: object) -> float | None:
         if args.timezone:
             try:
                 _ = ZoneInfo(args.timezone)
-            except Exception:
-                sys.stderr.write(
-                    f"Invalid timezone: {args.timezone}. Use an IANA name like 'America/Los_Angeles' or 'UTC'.\n"
-                )
-                return 2
+            except Exception as exc:
+                raise ValidationError(
+                    f"Invalid timezone: {args.timezone}. Use an IANA name like 'America/Los_Angeles' or 'UTC'.",
+                    cause=exc,
+                    context={"timezone": args.timezone},
+                ) from exc
         service = LifelogService(
             api_key=resolved_api_key,
             api_url=resolved_api_url,
@@ -367,8 +355,10 @@ def _coerce_timeout_value(value: object) -> float | None:
             )
             eff_write_dir = args.write_dir or cfg_output_dir
             if not args.date or not eff_write_dir:
-                sys.stderr.write("--combine requires --date and a write directory (provide --write-dir or set output_dir in config)\n")
-                return 2
+                raise ValidationError(
+                    "--combine requires --date and a write directory (provide --write-dir or set output_dir in config)",
+                    context={"command": "export-markdown"},
+                )
             text = service.export_markdown_by_date(date=args.date, frontmatter=args.frontmatter)
             from pathlib import Path as _Path
             outdir = _Path(eff_write_dir)
@@ -464,5 +454,62 @@ def _coerce_timeout_value(value: object) -> float | None:
     return 2
 
 
+def main(argv: list[str] | None = None) -> int:
+    # Ensure .env and related environment variables are loaded before parsing
+    load_env()
+    parser = _build_parser()
+    args = parser.parse_args(args=argv)
+    setup_logging(verbose=bool(getattr(args, "verbose", False)))
+
+    log = logging.getLogger("limitless_tools.cli")
+    log.info("cli_start", extra={"event": "cli_start", "command": args.command})
+    if getattr(args, "verbose", False):
+        # Emit a debug message for tests/diagnostics (avoid reserved LogRecord keys)
+        log.debug("parsed_args", extra={"cli_args": vars(args)})
+
+    # Load config and resolve profile
+    # Allow env var overrides for config path and profile
+    config_path_arg = args.config or os.getenv("LIMITLESS_CONFIG")
+    resolved_config_path = expand_path(config_path_arg) or default_config_path()
+    profile_name = args.profile or os.getenv("LIMITLESS_PROFILE") or "default"
+
+    cfg = load_config(resolved_config_path)
+    prof = get_profile(cfg, profile_name)
+    config_base_dir = str(Path(resolved_config_path).expanduser().parent)
+
+    argv_list = argv or []
+    verbose = bool(getattr(args, "verbose", False))
+
+    try:
+        return _execute_command(
+            args=args,
+            argv_list=argv_list,
+            prof=prof,
+            config_base_dir=config_base_dir,
+            parser=parser,
+            log=log,
+            resolved_config_path=resolved_config_path,
+            profile_name=profile_name,
+        )
+    except ValidationError as exc:
+        _stderr_line(f"Error: {exc}")
+        return 2
+    except LimitlessError as exc:
+        log_args = {"context": getattr(exc, "context", {})}
+        if verbose:
+            log.exception("limitless_error", extra=log_args)
+        else:
+            log.error("limitless_error", extra={**log_args, "error": str(exc)})
+        _stderr_line(f"Error: {exc}")
+        return 1
+    except KeyboardInterrupt:
+        _stderr_line("Aborted by user.")
+        return 130
+    except Exception:  # pragma: no cover - final safeguard
+        log.exception("unhandled_exception")
+        _stderr_line("Unexpected error occurred. Re-run with --verbose for stack trace.")
+        return 1
+
+
 if __name__ == "__main__":  # pragma: no cover
     raise SystemExit(main())

limitless_tools/errors.py

@@ -0,0 +1,60 @@
+"""Shared exception hierarchy for the Limitless Tools CLI."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(slots=True)
+class LimitlessError(Exception):
+    """Base class for all domain-specific errors."""
+
+    message: str
+    cause: Exception | None = None
+    context: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if self.cause is not None and not isinstance(self.cause, BaseException):
+            raise TypeError("cause must be an exception instance")
+
+    def __str__(self) -> str:  # pragma: no cover - trivial method
+        return self.message
+
+
+@dataclass(slots=True)
+class ConfigurationError(LimitlessError):
+    """Raised when configuration or environment setup is invalid."""
+
+
+@dataclass(slots=True)
+class ValidationError(LimitlessError):
+    """Raised when user input fails validation (e.g., invalid CLI args)."""
+
+
+@dataclass(slots=True)
+class ApiError(LimitlessError):
+    """Raised when the remote API responds with an error or network failure."""
+
+    status_code: int | None = None
+
+
+@dataclass(slots=True)
+class StorageError(LimitlessError):
+    """Raised when local storage operations fail."""
+
+
+@dataclass(slots=True)
+class StateError(LimitlessError):
+    """Raised for sync state read/write issues."""
+
+
+@dataclass(slots=True)
+class OutputError(LimitlessError):
+    """Raised when export/write targets cannot be written."""
+
+
+@dataclass(slots=True)
+class ServiceError(LimitlessError):
+    """Raised by services when orchestration fails."""
+

limitless_tools/http/client.py

@@ -5,6 +5,8 @@
 from collections.abc import Callable
 from typing import Any
 
+from limitless_tools.errors import ApiError, ConfigurationError
+
 try:
     import requests
 except ImportError:  # pragma: no cover - requests should be present in dev
@@ -82,7 +84,7 @@ def _enforce_base_url_allowlist(self) -> None:
         extra_hosts = {h.strip() for h in extra.split(",") if h.strip()}
         allowed = default_allowed | extra_hosts
         if host not in allowed:
-            raise ValueError(f"Base URL host not allowed: {host}")
+            raise ConfigurationError(f"Base URL host not allowed: {host}")
 
     def get_lifelogs(
         self,
@@ -152,7 +154,28 @@ def get_lifelogs(
                         req_kwargs["timeout"] = self.timeout
                 except (AttributeError, ValueError, TypeError) as exc:
                     log.debug("Session.get signature missing timeout: %s", exc)
-                resp = self.session.get(url, headers=self._headers(), params=params, **req_kwargs)  # type: ignore[union-attr]
+                try:
+                    resp = self.session.get(  # type: ignore[union-attr]
+                        url,
+                        headers=self._headers(),
+                        params=params,
+                        **req_kwargs,
+                    )
+                except Exception as exc:
+                    if attempt < self.max_retries:
+                        attempt += 1
+                        delay = self.backoff_factor * (2 ** (attempt - 1))
+                        self.sleep_fn(delay)
+                        continue
+                    msg = self._network_error_message(exc)
+                    raise ApiError(
+                        msg,
+                        cause=exc,
+                        context={
+                            "url": url,
+                            "params": {k: params.get(k) for k in ("cursor", "limit", "date") if params.get(k)},
+                        },
+                    ) from exc
                 if getattr(resp, "ok", False):
                     break
                 status = getattr(resp, "status_code", None)
@@ -185,7 +208,11 @@ def get_lifelogs(
                     continue
                 # Build informative error message for non-retryable errors
                 detail = self._error_detail(resp)
-                raise RuntimeError(f"HTTP {status} error fetching lifelogs: {detail}")
+                raise ApiError(
+                    f"HTTP {status} error fetching lifelogs: {detail}",
+                    status_code=status,
+                    context={"url": url, "params": {"cursor": params.get("cursor")}},
+                )
 
             body = resp.json()
             page_items: list[dict[str, Any]] = body.get("data", {}).get("lifelogs", []) or []
@@ -236,3 +263,18 @@ def _error_detail(self, resp: Any) -> str:
         if isinstance(text, str) and text.strip():
             return text.strip()
         return "Unknown error"
+
+    def _network_error_message(self, exc: Exception) -> str:
+        text = str(exc).strip().lower()
+        if self._looks_like_timeout(exc, text):
+            return "Request timed out while fetching lifelogs."
+        return "Network error while fetching lifelogs."
+
+    @staticmethod
+    def _looks_like_timeout(exc: Exception, text: str) -> bool:
+        if isinstance(exc, TimeoutError):  # noqa: F821 - built-in in >=3.10
+            return True
+        if "timeout" in text:
+            return True
+        timeout_cls = getattr(requests, "Timeout", None) if requests is not None else None
+        return timeout_cls is not None and isinstance(exc, timeout_cls)