imap-agent-cli 0.1.4__tar.gz → 0.1.6__tar.gz

{imap_agent_cli-0.1.4 → imap_agent_cli-0.1.6}/.github/workflows/publish.yml

@@ -1,8 +1,9 @@
 name: Publish to PyPI
 
 on:
-  release:
-    types: [published]
+  push:
+    tags:
+      - "[0-9]*.[0-9]*.[0-9]*"
   workflow_dispatch:
 
 jobs:

{imap_agent_cli-0.1.4 → imap_agent_cli-0.1.6}/AGENTS.md

@@ -29,13 +29,16 @@ The core safety boundary is strict: never add support for sending email, deletin
 - Keep README and skill language platform-neutral and agent-tool-neutral. Avoid shell-specific syntax unless explicitly documenting a shell-specific example.
 - If changing installed-skill behavior or wording, update `src/imap_agent_cli/skill.py` and `tests/test_skill.py` together.
 - If changing MIME parsing, body rendering, draft creation, or search behavior, add focused tests for the contract being changed.
+- If changing search output, preserve metadata-first behavior; search should not fetch full message bodies.
 
 ## Safety-Sensitive Implementation Notes
 
 - Reads must avoid changing message state. Preserve no-seen fetch behavior.
+- `ssl_mode=required` and `ssl_mode=preferred` must never send credentials over plaintext. Plaintext login is allowed only with `ssl_mode=disabled`.
 - Draft creation is allowed only by appending a new MIME message to the detected or configured Drafts folder.
 - Reply drafts should preserve appropriate reply headers such as `In-Reply-To` and `References`.
 - Attachment downloads require explicit user/agent intent and an output directory.
+- Attachment downloads should preflight target filenames before writing, so a failed multi-attachment download does not partially write files.
 - Folder-wide or all-folder operations should remain bounded by defaults and overridable limits.
 - HTML email is untrusted input. Sanitize before returning HTML and keep Markdown conversion intentionally lossy but predictable.
 
@@ -63,6 +66,14 @@ uv run --extra test python -m unittest tests.test_pymap_integration -v
 
 Set `IMAP_AGENT_CLI_TEST_PYMAP=1` in the shell before running the integration test. The test starts `pymap dict --demo-data` locally and logs in with demo credentials.
 
+Run the optional live no-seen test only when intentionally validating a configured mailbox:
+
+```text
+python -m unittest tests.test_live_no_seen -v
+```
+
+Set `IMAP_AGENT_CLI_LIVE_TEST=1` first. The test reads one unread message and verifies flags do not change; it skips when no unread message is available.
+
 Build the package:
 
 ```text
@@ -73,6 +84,7 @@ uv build --no-sources
 
 - Package metadata lives in `pyproject.toml`.
 - The GitHub Actions publish workflow is `.github/workflows/publish.yml`.
+- Publishing runs when a version tag such as `0.1.4` is pushed, or when the workflow is manually dispatched.
 - PyPI Trusted Publishing uses:
   - Project: `imap-agent-cli`
   - Owner: `pseudosavant`

{imap_agent_cli-0.1.4 → imap_agent_cli-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: imap-agent-cli
-Version: 0.1.4
+Version: 0.1.6
 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
@@ -100,6 +100,7 @@ IMAP_AGENT_CLI_PORT=993
 IMAP_AGENT_CLI_USERNAME=me@example.com
 IMAP_AGENT_CLI_PASSWORD=your-password-or-app-password
 IMAP_AGENT_CLI_TLS=true
+IMAP_AGENT_CLI_SSL_MODE=required
 IMAP_AGENT_CLI_DRAFTS_FOLDER=Drafts
 ```
 
@@ -121,6 +122,12 @@ The config file is stored at:
 
 Keep secrets in environment variables. The config file should reference password environment variable names, not contain passwords.
 
+Validate setup without reading message bodies:
+
+```text
+imap-agent-cli config check
+```
+
 ### Agent Skill
 
 The installed skill teaches an agentic tool how to use `imap-agent-cli` safely and effectively.
@@ -176,7 +183,10 @@ These examples are mostly useful for validating configuration or debugging what
 ```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 search --folder INBOX --from "Justin" --to "me@example.com" --max-results 10
+imap-agent-cli search --folder INBOX --has-attachments --max-results 10 --max-scan 100
+imap-agent-cli read --folder INBOX --uid 12345 --body-format html --include-attachments none
+imap-agent-cli thread --folder INBOX --uid 12345 --include-body latest --body-format plain
 imap-agent-cli attachments --folder INBOX --uid 12345
 imap-agent-cli attachments download --folder INBOX --uid 12345 --part-id 2 --output-dir ./email-attachments
 imap-agent-cli draft create --to person@example.com --subject "Hello" --body "Draft only."
@@ -219,6 +229,14 @@ 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`.
 
+Run the opt-in live IMAP no-seen test only when you intentionally want to validate the configured mailbox:
+
+```text
+python -m unittest tests.test_live_no_seen -v
+```
+
+Set `IMAP_AGENT_CLI_LIVE_TEST=1` in your shell first. The test reads one unread message with no-seen fetch behavior and verifies the flags do not change. If no unread message exists, it skips.
+
 ### Project Status
 
 This repo is under active development. The behavior target is defined in [`spec.md`](./spec.md).
@@ -227,6 +245,8 @@ This repo is under active development. The behavior target is defined in [`spec.
 
 The GitHub Actions workflow is `.github/workflows/publish.yml`.
 
+Publishing runs when a version tag such as `0.1.4` is pushed. The workflow can also be run manually.
+
 PyPI Trusted Publishing values:
 
 ```text

{imap_agent_cli-0.1.4 → imap_agent_cli-0.1.6}/README.md

@@ -67,6 +67,7 @@ IMAP_AGENT_CLI_PORT=993
 IMAP_AGENT_CLI_USERNAME=me@example.com
 IMAP_AGENT_CLI_PASSWORD=your-password-or-app-password
 IMAP_AGENT_CLI_TLS=true
+IMAP_AGENT_CLI_SSL_MODE=required
 IMAP_AGENT_CLI_DRAFTS_FOLDER=Drafts
 ```
 
@@ -88,6 +89,12 @@ The config file is stored at:
 
 Keep secrets in environment variables. The config file should reference password environment variable names, not contain passwords.
 
+Validate setup without reading message bodies:
+
+```text
+imap-agent-cli config check
+```
+
 ### Agent Skill
 
 The installed skill teaches an agentic tool how to use `imap-agent-cli` safely and effectively.
@@ -143,7 +150,10 @@ These examples are mostly useful for validating configuration or debugging what
 ```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 search --folder INBOX --from "Justin" --to "me@example.com" --max-results 10
+imap-agent-cli search --folder INBOX --has-attachments --max-results 10 --max-scan 100
+imap-agent-cli read --folder INBOX --uid 12345 --body-format html --include-attachments none
+imap-agent-cli thread --folder INBOX --uid 12345 --include-body latest --body-format plain
 imap-agent-cli attachments --folder INBOX --uid 12345
 imap-agent-cli attachments download --folder INBOX --uid 12345 --part-id 2 --output-dir ./email-attachments
 imap-agent-cli draft create --to person@example.com --subject "Hello" --body "Draft only."
@@ -186,6 +196,14 @@ 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`.
 
+Run the opt-in live IMAP no-seen test only when you intentionally want to validate the configured mailbox:
+
+```text
+python -m unittest tests.test_live_no_seen -v
+```
+
+Set `IMAP_AGENT_CLI_LIVE_TEST=1` in your shell first. The test reads one unread message with no-seen fetch behavior and verifies the flags do not change. If no unread message exists, it skips.
+
 ### Project Status
 
 This repo is under active development. The behavior target is defined in [`spec.md`](./spec.md).
@@ -194,6 +212,8 @@ This repo is under active development. The behavior target is defined in [`spec.
 
 The GitHub Actions workflow is `.github/workflows/publish.yml`.
 
+Publishing runs when a version tag such as `0.1.4` is pushed. The workflow can also be run manually.
+
 PyPI Trusted Publishing values:
 
 ```text

{imap_agent_cli-0.1.4 → imap_agent_cli-0.1.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "imap-agent-cli"
-version = "0.1.4"
+version = "0.1.6"
 description = "Agent-first IMAP CLI for safe email search, read, attachment download, and draft creation"
 readme = "README.md"
 license = "MIT"

{imap_agent_cli-0.1.4 → imap_agent_cli-0.1.6}/src/imap_agent_cli/__init__.py

@@ -1,3 +1,3 @@
 """Agent-first IMAP CLI."""
 
-__version__ = "0.1.4"
+__version__ = "0.1.6"

{imap_agent_cli-0.1.4 → imap_agent_cli-0.1.6}/src/imap_agent_cli/cli.py

@@ -31,12 +31,15 @@ Setup:
     IMAP_AGENT_CLI_USERNAME
     IMAP_AGENT_CLI_PASSWORD
     IMAP_AGENT_CLI_TLS
+    IMAP_AGENT_CLI_SSL_MODE
 
 Common workflows:
   imap-agent-cli folders
   imap-agent-cli search --folder INBOX --from "Justin" --max-results 10
+  imap-agent-cli search --folder INBOX --to "me@example.com" --has-attachments --max-results 10
   imap-agent-cli read --folder INBOX --uid 12345 --body-format metadata
-  imap-agent-cli read --folder INBOX --uid 12345 --body-format html --max-body-chars 12000
+  imap-agent-cli read --folder INBOX --uid 12345 --body-format html --include-attachments none --max-body-chars 12000
+  imap-agent-cli thread --folder INBOX --uid 12345 --include-body latest
   imap-agent-cli attachments --folder INBOX --uid 12345
   imap-agent-cli attachments download --folder INBOX --uid 12345 --part-id 2 --output-dir ./email-attachments
   imap-agent-cli draft create --to person@example.com --subject "Subject" --body-file ./draft.txt
@@ -54,6 +57,7 @@ Commands:
   folders         list folders
   search          search messages
   read            read a message by folder and UID
+  thread          inspect bounded thread context
   attachments     list or download attachments
   draft           create new or reply drafts
 
@@ -131,6 +135,21 @@ def _max_body_chars(args: argparse.Namespace, payload: dict[str, Any] | None = N
     return load_config().defaults.max_body_chars
 
 
+def _include_attachments(value: Any) -> str:
+    text = str(value or "metadata").strip().lower()
+    if text in {"false", "none", "no", "0"}:
+        return "none"
+    if text in {"true", "metadata", "yes", "1"}:
+        return "metadata"
+    raise AppError("invalid_request", "--include-attachments must be none or metadata.")
+
+
+def _check_item(name: str, ok: bool, **details: Any) -> dict[str, Any]:
+    item: dict[str, Any] = {"name": name, "ok": ok}
+    item.update(details)
+    return item
+
+
 def _body_from_args(args: argparse.Namespace, payload: dict[str, Any]) -> str:
     if getattr(args, "body", None) is not None:
         return args.body
@@ -168,6 +187,56 @@ def cmd_config(args: argparse.Namespace) -> int:
         path = init_config(from_env=args.from_env)
         write_json({"created": True, "path": str(path)})
         return 0
+    if args.config_command == "check":
+        checks: list[dict[str, Any]] = []
+        report: dict[str, Any] = {"ok": False, "checks": checks}
+        try:
+            config = load_config()
+            checks.append(_check_item("config_loaded", True, path=str(config.path)))
+            profile = resolve_profile(
+                config,
+                getattr(args, "profile", None),
+                host=getattr(args, "host", None),
+                port=getattr(args, "port", None),
+                username=getattr(args, "username", None),
+                password=_read_password(args),
+                tls=getattr(args, "tls", None),
+                ssl_mode=getattr(args, "ssl_mode", None),
+            )
+            report["profile"] = {
+                "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,
+            }
+            checks.append(_check_item("profile_resolved", True))
+            checks.append(_check_item("password_available", bool(profile.password), password_env=profile.password_env))
+            with ImapSession(profile, config.defaults) as session:
+                checks.append(_check_item("login", True, security=session.security))
+                capabilities = session.capabilities()
+                checks.append(_check_item("capabilities", True, values=capabilities))
+                folders = session.folders()["folders"]
+                checks.append(_check_item("folders", True, count=len(folders)))
+                default_folder = config.defaults.default_folder
+                selectable = {str(folder["name"]) for folder in folders if folder.get("selectable")}
+                default_ok = default_folder in selectable
+                checks.append(_check_item("default_folder", default_ok, folder=default_folder))
+                if default_ok:
+                    session._select(default_folder, readonly=True)
+                try:
+                    drafts_folder = session.resolve_drafts_folder()
+                    checks.append(_check_item("drafts_folder", True, folder=drafts_folder))
+                except AppError as exc:
+                    checks.append(_check_item("drafts_folder", False, error=exc.message))
+        except AppError as exc:
+            checks.append(_check_item(exc.code, False, error=exc.message))
+        report["ok"] = all(item["ok"] for item in checks)
+        write_json(report)
+        return 0 if report["ok"] else 1
     if args.config_command == "show":
         write_json(config_status(load_config()))
         return 0
@@ -223,6 +292,7 @@ def cmd_search(args: argparse.Namespace) -> int:
     folder = args.folder or payload.get("folder") or config.defaults.default_folder
     scope = payload.get("scope") or ("all" if args.all_folders else "recursive" if args.recursive else "folder")
     max_results = int(args.max_results or payload.get("max_results") or config.defaults.max_results)
+    max_scan = int(args.max_scan or payload.get("max_scan") or config.defaults.max_scan)
     with _session(args) as session:
         write_json(
             session.search(
@@ -230,9 +300,22 @@ def cmd_search(args: argparse.Namespace) -> int:
                 scope=str(scope),
                 subject=args.subject or payload.get("subject"),
                 sender=args.sender or payload.get("from"),
+                recipient=args.recipient or payload.get("to"),
+                message_id=args.message_id or payload.get("message_id"),
+                text=args.text or payload.get("text"),
                 since=args.since or payload.get("since"),
                 before=args.before or payload.get("before"),
+                unseen=bool(args.unseen or payload.get("unseen", False)),
+                seen=bool(args.seen or payload.get("seen", False)),
+                answered=bool(args.answered or payload.get("answered", False)),
+                flagged=bool(args.flagged or payload.get("flagged", False)),
+                larger=args.larger or payload.get("larger"),
+                smaller=args.smaller or payload.get("smaller"),
+                has_attachments=bool(args.has_attachments or payload.get("has_attachments", False)),
                 max_results=max_results,
+                max_scan=max_scan,
+                sort=str(args.sort or payload.get("sort") or "uid"),
+                order=str(args.order or payload.get("order") or "desc"),
             )
         )
     return 0
@@ -247,8 +330,38 @@ def cmd_read(args: argparse.Namespace) -> int:
     config = load_config()
     body_format = args.body_format or payload.get("body_format") or config.defaults.body_format
     max_body_chars = int(args.max_body_chars or payload.get("max_body_chars") or config.defaults.max_body_chars)
+    include_attachments = _include_attachments(args.include_attachments or payload.get("include_attachments") or "metadata")
+    with _session(args) as session:
+        write_json(
+            session.read(
+                folder=str(folder),
+                uid=int(uid),
+                body_format=str(body_format),
+                max_body_chars=max_body_chars,
+                include_attachments=include_attachments,
+            )
+        )
+    return 0
+
+
+def cmd_thread(args: argparse.Namespace) -> int:
+    if not args.folder or args.uid is None:
+        raise AppError("invalid_request", "thread requires --folder and --uid.")
+    config = load_config()
+    max_body_chars = int(args.max_body_chars or config.defaults.max_body_chars)
+    max_scan = int(args.max_scan or config.defaults.max_scan)
     with _session(args) as session:
-        write_json(session.read(folder=str(folder), uid=int(uid), body_format=str(body_format), max_body_chars=max_body_chars))
+        write_json(
+            session.thread(
+                folder=args.folder,
+                uid=args.uid,
+                max_messages=args.max_messages,
+                max_scan=max_scan,
+                include_body=args.include_body,
+                body_format=args.body_format,
+                max_body_chars=max_body_chars,
+            )
+        )
     return 0
 
 
@@ -362,6 +475,9 @@ def build_parser() -> argparse.ArgumentParser:
     config_init = config_sub.add_parser("init", help="create a starter config file")
     config_init.add_argument("--from-env", action="store_true")
     config_init.set_defaults(func=cmd_config)
+    config_check = config_sub.add_parser("check", help="validate profile configuration and IMAP connectivity")
+    _common_profile_args(config_check)
+    config_check.set_defaults(func=cmd_config)
     config_show = config_sub.add_parser("show", help="show resolved config metadata without secrets")
     config_show.set_defaults(func=cmd_config)
     config_default = config_sub.add_parser("set-default-profile", help="set the default profile")
@@ -406,9 +522,22 @@ def build_parser() -> argparse.ArgumentParser:
     search.add_argument("--all-folders", action="store_true")
     search.add_argument("--subject")
     search.add_argument("--from", dest="sender")
+    search.add_argument("--to", dest="recipient")
+    search.add_argument("--message-id")
+    search.add_argument("--text")
     search.add_argument("--since")
     search.add_argument("--before")
+    search.add_argument("--unseen", action="store_true")
+    search.add_argument("--seen", action="store_true")
+    search.add_argument("--answered", action="store_true")
+    search.add_argument("--flagged", action="store_true")
+    search.add_argument("--larger", type=int)
+    search.add_argument("--smaller", type=int)
+    search.add_argument("--has-attachments", action="store_true")
     search.add_argument("--max-results", type=int)
+    search.add_argument("--max-scan", type=int)
+    search.add_argument("--sort", choices=["uid", "date"], default=None)
+    search.add_argument("--order", choices=["asc", "desc"], default=None)
     search.set_defaults(func=cmd_search)
 
     read = sub.add_parser("read", help="read a message by folder and UID without marking it read")
@@ -418,8 +547,20 @@ def build_parser() -> argparse.ArgumentParser:
     read.add_argument("--uid", type=int)
     read.add_argument("--body-format", choices=["html", "markdown", "plain", "raw-html", "metadata"])
     read.add_argument("--max-body-chars", type=int)
+    read.add_argument("--include-attachments", choices=["none", "metadata", "false", "true"])
     read.set_defaults(func=cmd_read)
 
+    thread = sub.add_parser("thread", help="inspect bounded thread context for a message")
+    _common_profile_args(thread)
+    thread.add_argument("--folder", required=True)
+    thread.add_argument("--uid", required=True, type=int)
+    thread.add_argument("--max-messages", type=int, default=5)
+    thread.add_argument("--max-scan", type=int)
+    thread.add_argument("--include-body", choices=["none", "latest", "all"], default="none")
+    thread.add_argument("--body-format", choices=["html", "markdown", "plain", "raw-html", "metadata"], default="metadata")
+    thread.add_argument("--max-body-chars", type=int)
+    thread.set_defaults(func=cmd_thread)
+
     attachments = sub.add_parser("attachments", help="list attachment metadata for a message")
     _common_profile_args(attachments)
     attachments.add_argument("--folder")

{imap_agent_cli-0.1.4 → imap_agent_cli-0.1.6}/src/imap_agent_cli/config.py

@@ -67,6 +67,7 @@ def _env_profile() -> Profile | None:
         return None
     defaults = Defaults(
         max_results=_env_int(f"{ENV_PREFIX}MAX_RESULTS", 25),
+        max_scan=_env_int(f"{ENV_PREFIX}MAX_SCAN", 250),
         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),
@@ -229,6 +230,7 @@ profile = "default"
 format = "json"
 default_folder = "INBOX"
 max_results = 25
+max_scan = 250
 max_body_chars = 12000
 connect_timeout_seconds = 15
 read_timeout_seconds = 30
@@ -288,6 +290,7 @@ def add_profile(
     raw["defaults"].setdefault("format", "json")
     raw["defaults"].setdefault("default_folder", "INBOX")
     raw["defaults"].setdefault("max_results", 25)
+    raw["defaults"].setdefault("max_scan", 250)
     raw["defaults"].setdefault("max_body_chars", 12000)
     raw["defaults"].setdefault("connect_timeout_seconds", 15)
     raw["defaults"].setdefault("read_timeout_seconds", 30)