imap-agent-cli 0.1.0__py3-none-any.whl

imap_agent_cli/config.py

@@ -0,0 +1,310 @@
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import asdict
+from pathlib import Path
+from typing import Any
+
+from .errors import ConfigError
+from .models import Config, Defaults, Profile
+
+
+ENV_PREFIX = "IMAP_AGENT_CLI_"
+CONFIG_DIR = Path.home() / ".imap-agent-cli"
+CONFIG_PATH = CONFIG_DIR / "config.toml"
+
+
+def _env_bool(name: str, default: bool) -> bool:
+    value = os.environ.get(name)
+    if value is None or value == "":
+        return default
+    return value.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _env_int(name: str, default: int) -> int:
+    value = os.environ.get(name)
+    if value is None or value == "":
+        return default
+    try:
+        return int(value)
+    except ValueError as exc:
+        raise ConfigError(f"{name} must be an integer.") from exc
+
+
+def _coerce_defaults(data: dict[str, Any]) -> Defaults:
+    allowed = set(Defaults.__dataclass_fields__)
+    values = {key: value for key, value in data.items() if key in allowed}
+    if "exclude_special_folders_from_all" in values:
+        values["exclude_special_folders_from_all"] = tuple(values["exclude_special_folders_from_all"])
+    return Defaults(**values)
+
+
+def _coerce_profile(name: str, data: dict[str, Any], defaults: Defaults) -> Profile:
+    if not data.get("host"):
+        raise ConfigError(f"profile '{name}' is missing host.")
+    port = int(data.get("port", 993))
+    password_env = str(data.get("password_env") or f"{ENV_PREFIX}PASSWORD")
+    password = os.environ.get(password_env)
+    return Profile(
+        name=name,
+        host=str(data["host"]),
+        port=port,
+        username=str(data.get("username", "")),
+        password=password,
+        password_env=password_env,
+        tls=bool(data.get("tls", True)),
+        ssl_mode=str(data.get("ssl_mode", "required")),
+        drafts_folder=str(data.get("drafts_folder", "")),
+        connect_timeout_seconds=int(data.get("connect_timeout_seconds", defaults.connect_timeout_seconds)),
+        read_timeout_seconds=int(data.get("read_timeout_seconds", defaults.read_timeout_seconds)),
+    )
+
+
+def _env_profile() -> Profile | None:
+    host = os.environ.get(f"{ENV_PREFIX}HOST")
+    if not host:
+        return None
+    defaults = Defaults(
+        max_results=_env_int(f"{ENV_PREFIX}MAX_RESULTS", 25),
+        max_body_chars=_env_int(f"{ENV_PREFIX}MAX_BODY_CHARS", 12000),
+        connect_timeout_seconds=_env_int(f"{ENV_PREFIX}CONNECT_TIMEOUT_SECONDS", 15),
+        read_timeout_seconds=_env_int(f"{ENV_PREFIX}READ_TIMEOUT_SECONDS", 30),
+    )
+    return Profile(
+        name="default",
+        host=host,
+        port=_env_int(f"{ENV_PREFIX}PORT", 993),
+        username=os.environ.get(f"{ENV_PREFIX}USERNAME", ""),
+        password=os.environ.get(f"{ENV_PREFIX}PASSWORD"),
+        password_env=f"{ENV_PREFIX}PASSWORD",
+        tls=_env_bool(f"{ENV_PREFIX}TLS", True),
+        ssl_mode=os.environ.get(f"{ENV_PREFIX}SSL_MODE", "required"),
+        drafts_folder=os.environ.get(f"{ENV_PREFIX}DRAFTS_FOLDER", ""),
+        connect_timeout_seconds=defaults.connect_timeout_seconds,
+        read_timeout_seconds=defaults.read_timeout_seconds,
+    )
+
+
+def load_config(path: Path | None = None) -> Config:
+    path = path or CONFIG_PATH
+    defaults = Defaults()
+    profiles: dict[str, Profile] = {}
+
+    if path.exists():
+        try:
+            raw = tomllib.loads(path.read_text(encoding="utf-8"))
+        except tomllib.TOMLDecodeError as exc:
+            raise ConfigError(f"invalid TOML in {path}: {exc}") from exc
+        defaults = _coerce_defaults(raw.get("defaults", {}))
+        raw_profiles = raw.get("profiles", {})
+        if not isinstance(raw_profiles, dict):
+            raise ConfigError("[profiles] must be a TOML table.")
+        profiles = {
+            name: _coerce_profile(name, profile_data, defaults)
+            for name, profile_data in raw_profiles.items()
+            if isinstance(profile_data, dict)
+        }
+
+    env_profile = _env_profile()
+    if env_profile and "default" not in profiles:
+        profiles["default"] = env_profile
+
+    return Config(defaults=defaults, profiles=profiles, path=path)
+
+
+def _load_raw(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {"defaults": {}, "profiles": {}}
+    try:
+        raw = tomllib.loads(path.read_text(encoding="utf-8"))
+    except tomllib.TOMLDecodeError as exc:
+        raise ConfigError(f"invalid TOML in {path}: {exc}") from exc
+    raw.setdefault("defaults", {})
+    raw.setdefault("profiles", {})
+    if not isinstance(raw["defaults"], dict) or not isinstance(raw["profiles"], dict):
+        raise ConfigError("config must contain [defaults] and [profiles] tables.")
+    return raw
+
+
+def _toml_value(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, (list, tuple)):
+        return "[" + ", ".join(_toml_value(item) for item in value) + "]"
+    escaped = str(value).replace("\\", "\\\\").replace('"', '\\"')
+    return f'"{escaped}"'
+
+
+def _write_raw(path: Path, raw: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    lines: list[str] = []
+    defaults = raw.get("defaults", {})
+    lines.append("[defaults]")
+    for key, value in defaults.items():
+        lines.append(f"{key} = {_toml_value(value)}")
+    lines.append("")
+    profiles = raw.get("profiles", {})
+    for name, profile in profiles.items():
+        lines.append(f"[profiles.{name}]")
+        for key, value in profile.items():
+            lines.append(f"{key} = {_toml_value(value)}")
+        lines.append("")
+    path.write_text("\n".join(lines).rstrip() + "\n", encoding="utf-8")
+
+
+def resolve_profile(
+    config: Config,
+    name: str | None,
+    *,
+    host: str | None = None,
+    port: int | None = None,
+    username: str | None = None,
+    password: str | None = None,
+    tls: bool | None = None,
+    ssl_mode: str | None = None,
+) -> Profile:
+    profile_name = name or config.defaults.profile
+    base = config.profiles.get(profile_name)
+    if base is None and not host:
+        raise ConfigError(
+            f"profile '{profile_name}' was not found. Set IMAP_AGENT_CLI_HOST or run 'imap-agent-cli config init'."
+        )
+    if base is None:
+        base = Profile(name=profile_name, host=host or "", username=username or "")
+    values = asdict(base)
+    if host is not None:
+        values["host"] = host
+    if port is not None:
+        values["port"] = port
+    if username is not None:
+        values["username"] = username
+    if password is not None:
+        values["password"] = password
+    if tls is not None:
+        values["tls"] = tls
+    if ssl_mode is not None:
+        values["ssl_mode"] = ssl_mode
+    if not values["host"]:
+        raise ConfigError(f"profile '{profile_name}' is missing host.")
+    if not values["username"]:
+        raise ConfigError(f"profile '{profile_name}' is missing username.")
+    return Profile(**values)
+
+
+def config_status(config: Config) -> dict[str, Any]:
+    return {
+        "path": str(config.path or CONFIG_PATH),
+        "defaults": asdict(config.defaults),
+        "profiles": [
+            {
+                "name": profile.name,
+                "host": profile.host,
+                "port": profile.port,
+                "username": profile.username,
+                "password_env": profile.password_env,
+                "has_password": bool(profile.password),
+                "tls": profile.tls,
+                "ssl_mode": profile.ssl_mode,
+                "drafts_folder": profile.drafts_folder,
+                "complete": bool(profile.host and profile.username and profile.password),
+            }
+            for profile in config.profiles.values()
+        ],
+    }
+
+
+def init_config(path: Path | None = None, *, from_env: bool = False) -> Path:
+    path = path or CONFIG_PATH
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if path.exists():
+        return path
+    host = os.environ.get(f"{ENV_PREFIX}HOST", "imap.example.com") if from_env else "imap.example.com"
+    port = os.environ.get(f"{ENV_PREFIX}PORT", "993") if from_env else "993"
+    username = os.environ.get(f"{ENV_PREFIX}USERNAME", "me@example.com") if from_env else "me@example.com"
+    content = f"""[defaults]
+profile = "default"
+format = "json"
+default_folder = "INBOX"
+max_results = 25
+max_body_chars = 12000
+connect_timeout_seconds = 15
+read_timeout_seconds = 30
+body_format = "html"
+include_attachments = false
+exclude_special_folders_from_all = ["junk", "spam"]
+
+[profiles.default]
+host = "{host}"
+port = {port}
+username = "{username}"
+password_env = "IMAP_AGENT_CLI_PASSWORD"
+tls = true
+ssl_mode = "required"
+drafts_folder = ""
+"""
+    path.write_text(content, encoding="utf-8")
+    return path
+
+
+def set_default_profile(name: str, path: Path | None = None) -> Path:
+    path = path or CONFIG_PATH
+    raw = _load_raw(path)
+    if name not in raw["profiles"]:
+        raise ConfigError(f"profile '{name}' does not exist.")
+    raw["defaults"]["profile"] = name
+    _write_raw(path, raw)
+    return path
+
+
+def add_profile(
+    name: str,
+    *,
+    host: str,
+    port: int = 993,
+    username: str,
+    password_env: str,
+    tls: bool = True,
+    ssl_mode: str = "required",
+    drafts_folder: str = "",
+    path: Path | None = None,
+) -> Path:
+    path = path or CONFIG_PATH
+    raw = _load_raw(path)
+    raw.setdefault("defaults", {})
+    raw.setdefault("profiles", {})
+    raw["profiles"][name] = {
+        "host": host,
+        "port": port,
+        "username": username,
+        "password_env": password_env,
+        "tls": tls,
+        "ssl_mode": ssl_mode,
+        "drafts_folder": drafts_folder,
+    }
+    raw["defaults"].setdefault("profile", name)
+    raw["defaults"].setdefault("format", "json")
+    raw["defaults"].setdefault("default_folder", "INBOX")
+    raw["defaults"].setdefault("max_results", 25)
+    raw["defaults"].setdefault("max_body_chars", 12000)
+    raw["defaults"].setdefault("connect_timeout_seconds", 15)
+    raw["defaults"].setdefault("read_timeout_seconds", 30)
+    raw["defaults"].setdefault("body_format", "html")
+    raw["defaults"].setdefault("include_attachments", False)
+    raw["defaults"].setdefault("exclude_special_folders_from_all", ["junk", "spam"])
+    _write_raw(path, raw)
+    return path
+
+
+def remove_profile(name: str, path: Path | None = None) -> Path:
+    path = path or CONFIG_PATH
+    raw = _load_raw(path)
+    if name not in raw["profiles"]:
+        raise ConfigError(f"profile '{name}' does not exist.")
+    del raw["profiles"][name]
+    if raw["defaults"].get("profile") == name:
+        raw["defaults"]["profile"] = next(iter(raw["profiles"]), "default")
+    _write_raw(path, raw)
+    return path

imap_agent_cli/errors.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+
+class AppError(Exception):
+    """Known user-facing error."""
+
+    def __init__(self, code: str, message: str, *, retryable: bool = False, exit_code: int = 1) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.retryable = retryable
+        self.exit_code = exit_code
+
+
+class ConfigError(AppError):
+    def __init__(self, message: str) -> None:
+        super().__init__("config_invalid", message)
+

imap_agent_cli/imap_client.py

@@ -0,0 +1,303 @@
+from __future__ import annotations
+
+from contextlib import AbstractContextManager
+from email.message import EmailMessage
+from pathlib import Path
+from typing import Any
+
+from .errors import AppError
+from .mime import attachment_infos, message_headers, parse_message, render_body, save_attachments
+from .models import Defaults, Profile
+from .search import build_criteria
+
+
+SPECIAL_USE_MAP = {
+    "\\Inbox": "inbox",
+    "\\Sent": "sent",
+    "\\Drafts": "drafts",
+    "\\Trash": "trash",
+    "\\Junk": "junk",
+    "\\Archive": "archive",
+}
+
+
+class ImapSession(AbstractContextManager["ImapSession"]):
+    def __init__(self, profile: Profile, defaults: Defaults) -> None:
+        self.profile = profile
+        self.defaults = defaults
+        self.server: Any = None
+
+    def __enter__(self) -> "ImapSession":
+        try:
+            from imapclient import IMAPClient
+        except ImportError as exc:
+            raise AppError(
+                "config_invalid",
+                "IMAPClient is not installed. Run with 'uv run' or install imap-agent-cli with dependencies.",
+            ) from exc
+        if not self.profile.password:
+            raise AppError("auth_failed", f"missing password for profile '{self.profile.name}'.")
+        try:
+            self.server = IMAPClient(
+                self.profile.host,
+                port=self.profile.port,
+                ssl=self.profile.tls,
+                timeout=self.profile.connect_timeout_seconds,
+            )
+            self.server.login(self.profile.username, self.profile.password)
+        except Exception as exc:
+            raise AppError("connection_failed", f"failed to connect or authenticate: {exc}") from exc
+        return self
+
+    def __exit__(self, exc_type: object, exc: object, tb: object) -> None:
+        if self.server is None:
+            return
+        try:
+            self.server.logout()
+        except Exception:
+            pass
+
+    def _select(self, folder: str, *, readonly: bool = True) -> None:
+        # SELECT does not mutate message state; no-seen behavior is enforced by
+        # BODY.PEEK[] fetches. Some servers, including pymap on Windows, hang on
+        # the IMAPClient EXAMINE/read-only path.
+        try:
+            self.server.select_folder(folder, readonly=False)
+        except Exception as exc:
+            raise AppError("folder_not_found", f"folder '{folder}' could not be selected: {exc}") from exc
+
+    def folders(self) -> dict[str, Any]:
+        folders = []
+        for flags, delimiter, name in self.server.list_folders():
+            flag_values = [flag.decode() if isinstance(flag, bytes) else str(flag) for flag in flags]
+            special = None
+            for flag in flag_values:
+                special = SPECIAL_USE_MAP.get(flag, special)
+            selectable = "\\Noselect" not in flag_values
+            total = None
+            unread = None
+            if selectable:
+                try:
+                    status = self.server.folder_status(name, ["MESSAGES", "UNSEEN"])
+                    total = _lookup_status(status, "MESSAGES")
+                    unread = _lookup_status(status, "UNSEEN")
+                except Exception:
+                    pass
+            folders.append(
+                {
+                    "name": name,
+                    "delimiter": delimiter,
+                    "selectable": selectable,
+                    "special_use": special,
+                    "flags": flag_values,
+                    "total": total,
+                    "unread": unread,
+                    "children": [],
+                }
+            )
+        return {"profile": self.profile.name, "folders": folders}
+
+    def _folder_names_for_scope(self, folder: str, scope: str) -> list[str]:
+        if scope == "folder":
+            return [folder]
+        all_folders = self.folders()["folders"]
+        selectable = [item for item in all_folders if item["selectable"]]
+        if scope == "recursive":
+            return [item["name"] for item in selectable if item["name"] == folder or item["name"].startswith(folder)]
+        if scope == "all":
+            excluded = set(self.defaults.exclude_special_folders_from_all)
+            return [item["name"] for item in selectable if item.get("special_use") not in excluded]
+        raise AppError("invalid_request", f"unsupported folder scope '{scope}'.")
+
+    def search(
+        self,
+        *,
+        folder: str,
+        scope: str,
+        subject: str | None,
+        sender: str | None,
+        since: str | None,
+        before: str | None,
+        max_results: int,
+    ) -> dict[str, Any]:
+        criteria = build_criteria(subject=subject, sender=sender, since=since, before=before)
+        results: list[dict[str, Any]] = []
+        for current_folder in self._folder_names_for_scope(folder, scope):
+            self._select(current_folder, readonly=True)
+            try:
+                uids = list(self.server.search(criteria))
+            except Exception as exc:
+                raise AppError("server_error", f"search failed in folder '{current_folder}': {exc}") from exc
+            for uid in reversed(uids):
+                if len(results) >= max_results:
+                    break
+                results.append(self._summary(current_folder, int(uid)))
+            if len(results) >= max_results:
+                break
+        return {
+            "profile": self.profile.name,
+            "query": {
+                "folder": folder,
+                "scope": scope,
+                "subject": subject,
+                "from": sender,
+                "since": since,
+                "before": before,
+                "max_results": max_results,
+            },
+            "results": results,
+            "truncated": len(results) >= max_results,
+        }
+
+    def _fetch_raw(self, folder: str, uid: int) -> bytes:
+        self._select(folder, readonly=True)
+        try:
+            data = self.server.fetch([uid], ["BODY.PEEK[]"])
+        except Exception as exc:
+            raise AppError("message_not_found", f"message UID {uid} could not be fetched from '{folder}'.") from exc
+        entry = data.get(uid) or data.get(str(uid)) or data.get(bytes(str(uid), "ascii"))
+        if not entry:
+            raise AppError("message_not_found", f"message UID {uid} was not found in '{folder}'.")
+        for key, value in entry.items():
+            key_text = key.decode() if isinstance(key, bytes) else str(key)
+            if "BODY" in key_text.upper():
+                return value
+        raise AppError("server_error", f"server did not return message body for UID {uid}.")
+
+    def _summary(self, folder: str, uid: int) -> dict[str, Any]:
+        raw = self._fetch_raw(folder, uid)
+        message = parse_message(raw)
+        headers = message_headers(message)
+        attachments = attachment_infos(message)
+        return {
+            "folder": folder,
+            "uid": uid,
+            "message_id": str(message.get("message-id", "")),
+            "date": str(message.get("date", "")),
+            "from": headers["from"],
+            "to": headers["to"],
+            "cc": headers["cc"],
+            "subject": headers["subject"],
+            "has_attachments": bool(attachments),
+            "attachment_count": len(attachments),
+            "size_bytes": len(raw),
+        }
+
+    def read(self, *, folder: str, uid: int, body_format: str, max_body_chars: int) -> dict[str, Any]:
+        raw = self._fetch_raw(folder, uid)
+        message = parse_message(raw)
+        return message_payload(
+            profile=self.profile.name,
+            folder=folder,
+            uid=uid,
+            message=message,
+            body_format=body_format,
+            max_body_chars=max_body_chars,
+        )
+
+    def attachments(self, *, folder: str, uid: int) -> dict[str, Any]:
+        raw = self._fetch_raw(folder, uid)
+        message = parse_message(raw)
+        return {
+            "profile": self.profile.name,
+            "folder": folder,
+            "uid": uid,
+            "attachments": [info for info in attachment_infos(message)],
+        }
+
+    def download_attachments(
+        self,
+        *,
+        folder: str,
+        uid: int,
+        output_dir: Path,
+        part_id: str | None,
+        all_parts: bool,
+        include_inline: bool,
+        overwrite: bool,
+    ) -> dict[str, Any]:
+        raw = self._fetch_raw(folder, uid)
+        message = parse_message(raw)
+        return {
+            "profile": self.profile.name,
+            "folder": folder,
+            "uid": uid,
+            "saved": save_attachments(
+                message,
+                output_dir,
+                part_id=part_id,
+                all_parts=all_parts,
+                include_inline=include_inline,
+                overwrite=overwrite,
+            ),
+        }
+
+    def resolve_drafts_folder(self, override: str | None = None) -> str:
+        if override:
+            return override
+        if self.profile.drafts_folder:
+            return self.profile.drafts_folder
+        folders = self.folders()["folders"]
+        for item in folders:
+            if item.get("special_use") == "drafts":
+                return str(item["name"])
+        names = {str(item["name"]).lower(): str(item["name"]) for item in folders}
+        for candidate in ("drafts", "inbox.drafts", "[gmail]/drafts"):
+            if candidate in names:
+                return names[candidate]
+        raise AppError("drafts_folder_not_found", "could not auto-detect Drafts folder; configure drafts_folder.")
+
+    def append_draft(self, message: EmailMessage, *, drafts_folder: str | None = None) -> dict[str, Any]:
+        folder = self.resolve_drafts_folder(drafts_folder)
+        raw = message.as_bytes(policy=message.policy)
+        try:
+            result = self.server.append(folder, raw)
+        except Exception as exc:
+            raise AppError("server_error", f"failed to append draft to '{folder}': {exc}") from exc
+        return {
+            "profile": self.profile.name,
+            "drafts_folder": folder,
+            "created": True,
+            "append_uid": _extract_append_uid(result),
+            "message_id": str(message.get("message-id", "")),
+            "subject": str(message.get("subject", "")),
+            "to": message.get("to", ""),
+            "attachment_count": len(list(message.iter_attachments())),
+        }
+
+
+def _lookup_status(status: dict[Any, Any], name: str) -> int | None:
+    for key, value in status.items():
+        key_text = key.decode() if isinstance(key, bytes) else str(key)
+        if key_text.upper() == name:
+            return int(value)
+    return None
+
+
+def _extract_append_uid(result: Any) -> int | None:
+    if isinstance(result, (list, tuple)):
+        for item in result:
+            if isinstance(item, int):
+                return item
+    return None
+
+
+def message_payload(
+    *,
+    profile: str,
+    folder: str,
+    uid: int,
+    message: EmailMessage,
+    body_format: str,
+    max_body_chars: int,
+) -> dict[str, Any]:
+    return {
+        "profile": profile,
+        "folder": folder,
+        "uid": uid,
+        "message_id": str(message.get("message-id", "")),
+        "date": str(message.get("date", "")),
+        "headers": message_headers(message),
+        "body": render_body(message, body_format, max_body_chars),
+        "attachments": [info for info in attachment_infos(message)],
+    }