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

imap_agent_cli/mime.py

@@ -0,0 +1,319 @@
+from __future__ import annotations
+
+import hashlib
+import html
+import mimetypes
+import os
+import re
+import shutil
+from email import policy
+from email.headerregistry import Address
+from email.message import EmailMessage, Message
+from email.parser import BytesParser
+from email.utils import getaddresses, make_msgid
+from pathlib import Path
+from typing import Any, Iterable
+
+from .errors import AppError
+from .models import AttachmentInfo
+
+
+BODY_FORMATS = {"html", "markdown", "plain", "raw-html", "metadata"}
+
+
+def parse_message(raw: bytes) -> EmailMessage:
+    parsed = BytesParser(policy=policy.default).parsebytes(raw)
+    if not isinstance(parsed, EmailMessage):
+        raise AppError("server_error", "Parsed message was not an EmailMessage.")
+    return parsed
+
+
+def addresses(header_values: Iterable[str | None]) -> list[dict[str, str]]:
+    raw = [value for value in header_values if value]
+    return [{"name": name, "email": email} for name, email in getaddresses(raw)]
+
+
+def message_headers(message: Message) -> dict[str, Any]:
+    return {
+        "subject": str(message.get("subject", "")),
+        "from": addresses(message.get_all("from", [])),
+        "to": addresses(message.get_all("to", [])),
+        "cc": addresses(message.get_all("cc", [])),
+        "bcc": addresses(message.get_all("bcc", [])),
+        "reply_to": addresses(message.get_all("reply-to", [])),
+    }
+
+
+def _part_payload_text(part: Message) -> str:
+    payload = part.get_payload(decode=True)
+    if payload is None:
+        value = part.get_payload()
+        return value if isinstance(value, str) else ""
+    charset = part.get_content_charset() or "utf-8"
+    return payload.decode(charset, errors="replace")
+
+
+def _body_parts(message: EmailMessage) -> tuple[str | None, str | None]:
+    plain: str | None = None
+    html_body: str | None = None
+    if message.is_multipart():
+        for part in message.walk():
+            if part.is_multipart():
+                continue
+            disposition = (part.get_content_disposition() or "").lower()
+            if disposition == "attachment":
+                continue
+            ctype = part.get_content_type().lower()
+            if ctype == "text/plain" and plain is None:
+                plain = _part_payload_text(part)
+            elif ctype == "text/html" and html_body is None:
+                html_body = _part_payload_text(part)
+    else:
+        ctype = message.get_content_type().lower()
+        if ctype == "text/html":
+            html_body = _part_payload_text(message)
+        elif ctype == "text/plain":
+            plain = _part_payload_text(message)
+    return plain, html_body
+
+
+def sanitize_html(value: str) -> str:
+    try:
+        import bleach
+    except ImportError:
+        return html.escape(value)
+    allowed_tags = {
+        "a",
+        "abbr",
+        "b",
+        "blockquote",
+        "br",
+        "code",
+        "div",
+        "em",
+        "h1",
+        "h2",
+        "h3",
+        "h4",
+        "h5",
+        "h6",
+        "hr",
+        "i",
+        "li",
+        "ol",
+        "p",
+        "pre",
+        "span",
+        "strong",
+        "table",
+        "tbody",
+        "td",
+        "th",
+        "thead",
+        "tr",
+        "u",
+        "ul",
+    }
+    allowed_attrs = {
+        "a": ["href", "title"],
+        "abbr": ["title"],
+        "td": ["colspan", "rowspan"],
+        "th": ["colspan", "rowspan"],
+    }
+    cleaned = bleach.clean(
+        value,
+        tags=allowed_tags,
+        attributes=allowed_attrs,
+        protocols={"http", "https", "mailto"},
+        strip=True,
+    )
+    return bleach.linkify(cleaned)
+
+
+def html_to_plain(value: str) -> str:
+    try:
+        from bs4 import BeautifulSoup
+    except ImportError:
+        return re.sub(r"<[^>]+>", " ", value)
+    soup = BeautifulSoup(value, "html.parser")
+    for tag in soup(["script", "style", "iframe", "object"]):
+        tag.decompose()
+    return soup.get_text("\n", strip=True)
+
+
+def html_to_markdown(value: str) -> str:
+    try:
+        from markdownify import markdownify
+    except ImportError:
+        return html_to_plain(value)
+    return markdownify(sanitize_html(value), heading_style="ATX")
+
+
+def render_body(message: EmailMessage, body_format: str, max_chars: int) -> dict[str, Any]:
+    if body_format not in BODY_FORMATS:
+        raise AppError("invalid_request", f"unsupported body format '{body_format}'.")
+    if body_format == "metadata":
+        return {"format": "metadata", "content": "", "sanitized": False, "truncated": False, "max_chars": max_chars}
+    plain, html_body = _body_parts(message)
+    sanitized = False
+    if body_format == "html":
+        if html_body is not None:
+            content = sanitize_html(html_body)
+            sanitized = True
+        else:
+            content = plain or ""
+    elif body_format == "raw-html":
+        content = html_body if html_body is not None else (plain or "")
+    elif body_format == "markdown":
+        content = html_to_markdown(html_body) if html_body is not None else (plain or "")
+        sanitized = html_body is not None
+    else:
+        content = plain if plain is not None else html_to_plain(html_body or "")
+    truncated = len(content) > max_chars
+    if truncated:
+        content = content[:max_chars]
+    return {
+        "format": body_format,
+        "content": content,
+        "sanitized": sanitized,
+        "truncated": truncated,
+        "max_chars": max_chars,
+    }
+
+
+def attachment_infos(message: EmailMessage) -> list[AttachmentInfo]:
+    infos: list[AttachmentInfo] = []
+    index = 1
+    for part in message.walk():
+        if part.is_multipart():
+            continue
+        filename = part.get_filename()
+        disposition = (part.get_content_disposition() or "").lower()
+        content_id = part.get("content-id")
+        is_attachment = disposition == "attachment" or bool(filename)
+        is_inline = disposition == "inline"
+        if not is_attachment and not is_inline:
+            continue
+        payload = part.get_payload(decode=True) or b""
+        infos.append(
+            AttachmentInfo(
+                part_id=str(index),
+                filename=filename or f"part-{index}",
+                content_type=part.get_content_type(),
+                size_bytes=len(payload),
+                content_id=content_id.strip("<>") if content_id else None,
+                inline=is_inline,
+            )
+        )
+        index += 1
+    return infos
+
+
+def safe_filename(filename: str) -> str:
+    base = os.path.basename(filename).strip().replace("\x00", "")
+    base = re.sub(r"[^A-Za-z0-9._ -]+", "_", base)
+    base = base.strip(" .")
+    return base or "attachment"
+
+
+def save_attachments(
+    message: EmailMessage,
+    output_dir: Path,
+    *,
+    part_id: str | None = None,
+    all_parts: bool = False,
+    include_inline: bool = False,
+    overwrite: bool = False,
+) -> list[dict[str, Any]]:
+    output_dir.mkdir(parents=True, exist_ok=True)
+    saved: list[dict[str, Any]] = []
+    index = 1
+    for part in message.walk():
+        if part.is_multipart():
+            continue
+        filename = part.get_filename()
+        disposition = (part.get_content_disposition() or "").lower()
+        is_inline = disposition == "inline"
+        is_attachment = disposition == "attachment" or bool(filename)
+        if not is_attachment and not (include_inline and is_inline):
+            continue
+        current_id = str(index)
+        index += 1
+        if not all_parts and current_id != part_id:
+            continue
+        if is_inline and not include_inline:
+            continue
+        payload = part.get_payload(decode=True) or b""
+        target = output_dir / safe_filename(filename or f"part-{current_id}")
+        if target.exists() and not overwrite:
+            raise AppError("invalid_request", f"refusing to overwrite existing file: {target}")
+        target.write_bytes(payload)
+        saved.append(
+            {
+                "part_id": current_id,
+                "path": str(target.resolve()),
+                "filename": target.name,
+                "content_type": part.get_content_type(),
+                "size_bytes": len(payload),
+                "sha256": hashlib.sha256(payload).hexdigest(),
+                "inline": is_inline,
+            }
+        )
+    if not saved:
+        raise AppError("attachment_not_found", "no matching attachment was found.")
+    return saved
+
+
+def _set_addresses(message: EmailMessage, header: str, values: list[str]) -> None:
+    if values:
+        message[header] = ", ".join(values)
+
+
+def create_draft_message(
+    *,
+    sender: str,
+    to: list[str],
+    cc: list[str] | None,
+    bcc: list[str] | None,
+    subject: str,
+    body: str,
+    body_format: str,
+    attachments: list[Path] | None = None,
+    in_reply_to: str | None = None,
+    references: str | None = None,
+) -> EmailMessage:
+    message = EmailMessage()
+    message["Message-ID"] = make_msgid()
+    message["From"] = sender
+    _set_addresses(message, "To", to)
+    _set_addresses(message, "Cc", cc or [])
+    _set_addresses(message, "Bcc", bcc or [])
+    message["Subject"] = subject
+    if in_reply_to:
+        message["In-Reply-To"] = in_reply_to
+    if references:
+        message["References"] = references
+    if body_format == "html":
+        message.set_content(html_to_plain(body))
+        message.add_alternative(body, subtype="html")
+    elif body_format == "markdown":
+        message.set_content(body)
+    elif body_format == "plain":
+        message.set_content(body)
+    else:
+        raise AppError("invalid_request", "draft body format must be html, markdown, or plain.")
+    for attachment in attachments or []:
+        ctype, _ = mimetypes.guess_type(str(attachment))
+        maintype, subtype = (ctype or "application/octet-stream").split("/", 1)
+        message.add_attachment(
+            attachment.read_bytes(),
+            maintype=maintype,
+            subtype=subtype,
+            filename=attachment.name,
+        )
+    return message
+
+
+def copy_attachment(src: Path, dest: Path) -> None:
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copyfile(src, dest)

imap_agent_cli/models.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Defaults:
+    profile: str = "default"
+    format: str = "json"
+    default_folder: str = "INBOX"
+    max_results: int = 25
+    max_body_chars: int = 12000
+    connect_timeout_seconds: int = 15
+    read_timeout_seconds: int = 30
+    body_format: str = "html"
+    include_attachments: bool = False
+    exclude_special_folders_from_all: tuple[str, ...] = ("junk", "spam")
+
+
+@dataclass(frozen=True)
+class Profile:
+    name: str
+    host: str
+    port: int = 993
+    username: str = ""
+    password: str | None = None
+    password_env: str = "IMAP_AGENT_CLI_PASSWORD"
+    tls: bool = True
+    ssl_mode: str = "required"
+    drafts_folder: str = ""
+    connect_timeout_seconds: int = 15
+    read_timeout_seconds: int = 30
+
+
+@dataclass(frozen=True)
+class Config:
+    defaults: Defaults = field(default_factory=Defaults)
+    profiles: dict[str, Profile] = field(default_factory=dict)
+    path: Path | None = None
+
+
+@dataclass(frozen=True)
+class AttachmentInfo:
+    part_id: str
+    filename: str
+    content_type: str
+    size_bytes: int | None
+    content_id: str | None
+    inline: bool

imap_agent_cli/render.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import json
+import sys
+from dataclasses import asdict, is_dataclass
+from datetime import date, datetime
+from pathlib import Path
+from typing import Any
+
+from .errors import AppError
+
+
+def _default(value: Any) -> Any:
+    if is_dataclass(value):
+        return asdict(value)
+    if isinstance(value, (datetime, date)):
+        return value.isoformat()
+    if isinstance(value, Path):
+        return str(value)
+    if isinstance(value, bytes):
+        return value.decode("utf-8", errors="replace")
+    raise TypeError(f"{type(value).__name__} is not JSON serializable")
+
+
+def write_json(payload: Any) -> None:
+    sys.stdout.write(json.dumps(payload, default=_default, ensure_ascii=False, indent=2))
+    sys.stdout.write("\n")
+
+
+def write_error(error: AppError) -> None:
+    payload = {
+        "error": {
+            "code": error.code,
+            "message": error.message,
+            "retryable": error.retryable,
+        }
+    }
+    sys.stderr.write(json.dumps(payload, ensure_ascii=False))
+    sys.stderr.write("\n")

imap_agent_cli/search.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from datetime import date
+from typing import Any
+
+from .errors import AppError
+
+
+def parse_date(value: str | None, name: str) -> date | None:
+    if not value:
+        return None
+    try:
+        return date.fromisoformat(value)
+    except ValueError as exc:
+        raise AppError("invalid_request", f"{name} must be YYYY-MM-DD.") from exc
+
+
+def build_criteria(*, subject: str | None, sender: str | None, since: str | None, before: str | None) -> list[Any]:
+    criteria: list[Any] = []
+    if subject:
+        criteria.extend(["SUBJECT", subject])
+    if sender:
+        criteria.extend(["FROM", sender])
+    since_date = parse_date(since, "--since")
+    before_date = parse_date(before, "--before")
+    if since_date:
+        criteria.extend(["SINCE", since_date])
+    if before_date:
+        criteria.extend(["BEFORE", before_date])
+    return criteria or ["ALL"]

imap_agent_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: imap-agent-cli
+Version: 0.1.0
+Summary: Agent-first IMAP CLI for safe email search, read, attachment download, and draft creation
+Project-URL: Homepage, https://github.com/pseudosavant/imap-agent-cli
+Project-URL: Repository, https://github.com/pseudosavant/imap-agent-cli
+Project-URL: Issues, https://github.com/pseudosavant/imap-agent-cli/issues
+Author: Paul
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,cli,drafts,email,imap
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Communications :: Email :: Post-Office :: IMAP
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: beautifulsoup4>=4.12.0
+Requires-Dist: bleach>=6.2.0
+Requires-Dist: imapclient>=3.0.0
+Requires-Dist: markdownify>=0.14.0
+Provides-Extra: test
+Requires-Dist: pymap>=0.36.0; extra == 'test'
+Requires-Dist: pytest>=8.0.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# imap-agent-cli
+
+`imap-agent-cli` is an agent-first IMAP CLI for safe email search, read, attachment download, and draft creation.
+
+It can inspect mailboxes and append messages to Drafts. It cannot send email, delete messages, move messages, archive messages, change labels, alter flags, or mark messages read/unread.
+
+## Status
+
+This repo is under active development. The behavior target is defined in [`spec.md`](./spec.md).
+
+## Quick Start
+
+Single-profile env-var setup:
+
+```text
+IMAP_AGENT_CLI_HOST=imap.example.com
+IMAP_AGENT_CLI_PORT=993
+IMAP_AGENT_CLI_USERNAME=me@example.com
+IMAP_AGENT_CLI_PASSWORD=...
+IMAP_AGENT_CLI_TLS=true
+```
+
+Local development:
+
+```text
+uv run ./imap_agent_cli.py --help
+uv run ./imap_agent_cli.py folders
+uv run ./imap_agent_cli.py search --subject invoice
+```
+
+Packaged execution:
+
+```text
+uvx imap-agent-cli --help
+```
+
+## Examples
+
+```text
+imap-agent-cli folders
+imap-agent-cli search --folder INBOX --subject "invoice" --max-results 10
+imap-agent-cli read --folder INBOX --uid 12345 --body-format html
+imap-agent-cli attachments --folder INBOX --uid 12345
+imap-agent-cli attachments download --folder INBOX --uid 12345 --part-id 2 --output-dir C:\tmp\email-attachments
+imap-agent-cli draft create --to person@example.com --subject "Hello" --body "Draft only."
+imap-agent-cli draft reply --folder INBOX --uid 12345 --body "Thanks. I will review this."
+```
+
+All command payloads are JSON on stdout. Diagnostics and errors go to stderr.
+
+## Config
+
+Create a starter config:
+
+```text
+imap-agent-cli config init
+```
+
+Add a named profile:
+
+```text
+imap-agent-cli config add-profile work --host imap.example.com --port 993 --username me@example.com --password-env IMAP_AGENT_CLI_WORK_PASSWORD
+imap-agent-cli config set-default-profile work
+```
+
+Config path:
+
+```text
+~/.imap-agent-cli/config.toml
+```
+
+Secrets should stay in environment variables, not the config file.
+
+## Safety Boundary
+
+Allowed:
+
+- list folders
+- search messages
+- read messages with no-seen fetch behavior
+- list/download attachments only when requested
+- append new messages to Drafts
+
+Not allowed:
+
+- send
+- delete
+- move
+- archive
+- flag/star
+- mark read/unread
+- create/delete/rename folders
+
+## Testing
+
+No-network unit tests:
+
+```text
+python -m unittest discover -v
+```
+
+Package build:
+
+```text
+uv build --no-sources
+```
+
+The spec targets `pymap` for future local IMAP integration tests on Windows without Docker.
+
+Opt-in local IMAP integration test:
+
+```text
+$env:IMAP_AGENT_CLI_TEST_PYMAP = "1"
+uv run --extra test python -m unittest tests.test_pymap_integration -v
+```
+
+The integration test starts `pymap dict --demo-data` locally and logs in with `demouser` / `demopass`.
+
+## Publishing
+
+The GitHub Actions workflow is `.github/workflows/publish.yml`.
+
+PyPI Trusted Publishing values:
+
+```text
+Project: imap-agent-cli
+Owner: pseudosavant
+Repository: imap-agent-cli
+Workflow: publish.yml
+Environment: pypi
+```

imap_agent_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+imap_agent_cli/__init__.py,sha256=3CKD-Oy1m7buiht67UbWXl63n91U5jgvgb-b653pJpE,51
+imap_agent_cli/cli.py,sha256=gu10GIZn7XbnIH1TsdHdvg4vvQnFBv8969n-ZVucIJE,16868
+imap_agent_cli/config.py,sha256=_dj1CBeHCWxahXhtM0ws_mPzt-_tA5zLw-FIEFCTTxE,10747
+imap_agent_cli/errors.py,sha256=PPdOcHz3oMjFXFMOYrOeHxcOmX25TrBvlu_Q13D8x1c,495
+imap_agent_cli/imap_client.py,sha256=p7zPcYMXuZfQ7KZrgi-BwFNCql2x8yJ6Vyhiz13qvak,11380
+imap_agent_cli/mime.py,sha256=7fxlG-JquVPV3TWOtVf-ThDigw5GF53XUPgF6pEQgIg,10116
+imap_agent_cli/models.py,sha256=o68emsugmRNsqImYjmxntJ-XHlYAcRno2kt5KLqaP4I,1216
+imap_agent_cli/render.py,sha256=8KxUNbDvNj6xir9hOrmD-w48zAyINhSD2fy6aTNs7uM,1058
+imap_agent_cli/search.py,sha256=6sbVviu2nLdgIiC8ONViVy1c6T6RSC-E-zxtwbXlMSM,905
+imap_agent_cli-0.1.0.dist-info/METADATA,sha256=1_N0uyUsvLn7U4nr2uqSYpw5H9uB8yzcAqicxgxGX40,4270
+imap_agent_cli-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+imap_agent_cli-0.1.0.dist-info/entry_points.txt,sha256=5KCl2yztf4gYsXa4VeKlJcKOZkoZ4feSlDfqBsKQgMo,59
+imap_agent_cli-0.1.0.dist-info/licenses/LICENSE,sha256=zGoYTIMLHXHfn4BCncvY2ibPNStrFU_8Vyw8XpcMUiE,1061
+imap_agent_cli-0.1.0.dist-info/RECORD,,

imap_agent_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

imap_agent_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+imap-agent-cli = imap_agent_cli.cli:main

imap_agent_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paul
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.