email-cli-tool 0.2.0__tar.gz → 0.3.0__tar.gz

{email_cli_tool-0.2.0 → email_cli_tool-0.3.0}/.github/workflows/publish.yml

@@ -3,6 +3,7 @@ name: Publish to PyPI
 on:
   release:
     types: [published]
+  workflow_dispatch:
 
 jobs:
   publish:
@@ -11,9 +12,9 @@ jobs:
       id-token: write
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6.0.3
 
-      - uses: astral-sh/setup-uv@v5
+      - uses: astral-sh/setup-uv@v8.2.0
         with:
           version: "latest"
 

{email_cli_tool-0.2.0 → email_cli_tool-0.3.0}/.github/workflows/test.yml

@@ -14,9 +14,9 @@ jobs:
         python-version: ["3.10", "3.11", "3.12", "3.13"]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6.0.3
 
-      - uses: astral-sh/setup-uv@v5
+      - uses: astral-sh/setup-uv@v8.2.0
         with:
           version: "latest"
 

{email_cli_tool-0.2.0 → email_cli_tool-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: email-cli-tool
-Version: 0.2.0
+Version: 0.3.0
 Summary: A simple CLI tool for sending emails with plain text, HTML, and file attachments
 Project-URL: Homepage, https://github.com/ClaymanTwinkle/email-cli-tool
 Project-URL: Repository, https://github.com/ClaymanTwinkle/email-cli-tool
@@ -38,17 +38,27 @@ Description-Content-Type: text/markdown
 - Direct SMTP connection (SSL / STARTTLS)
 - Interactive configuration wizard
 - Read body content from stdin
+- Wait for the next incoming email (IMAP) and download its attachments
 
 ## Installation
 
 ```bash
-# From PyPI
+# From PyPI (latest)
 pip install email-cli-tool
 
+# Install a specific version
+pip install email-cli-tool==0.2.0
+
+# Upgrade an existing install
+pip install --upgrade email-cli-tool
+
 # Or with uv
-uv tool install email-cli-tool
+uv tool install email-cli-tool          # latest
+uv tool install email-cli-tool==0.2.0   # specific version
 ```
 
+> The `emailcli skill install` command requires version **0.2.0** or newer.
+
 ## Quick Start
 
 ### 1. Initialize Configuration
@@ -99,6 +109,18 @@ echo "Content" | emailcli send \
   --to user@example.com --subject "Piped" --body -
 ```
 
+### 3. Wait for Incoming Email
+
+```bash
+# Block until the next email arrives, print it, then exit
+emailcli watch
+
+# Wait up to 5 minutes and save attachments
+emailcli watch --timeout 300 --save-attachments ./downloads
+```
+
+Requires IMAP settings — `emailcli init` asks for them, or add an `imap` section to the config (see below).
+
 ## Command Reference
 
 ### `emailcli send`
@@ -115,6 +137,17 @@ echo "Content" | emailcli send \
 
 > At least one of `--body`, `--html`, or `--html-file` is required.
 
+### `emailcli watch`
+
+Wait for the next incoming email (via IMAP polling), print headers and body to stdout, then exit. Only emails arriving **after** the command starts are matched; the received email is marked as read.
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--timeout` | `0` (wait forever) | Max seconds to wait; exits with code `2` on timeout |
+| `--poll-interval` | `10` | Seconds between mailbox checks |
+| `--save-attachments` | | Directory to save attachments into |
+| `--mailbox` | `INBOX` | Mailbox to watch |
+
 ### `emailcli init`
 
 Interactively create the configuration file at `~/.emailcli/config.yaml`.
@@ -150,6 +183,13 @@ smtp:
   username: yourname@gmail.com
   password: your-app-password
   encryption: ssl  # ssl | starttls | none
+
+# Optional, only needed for `emailcli watch`
+imap:
+  host: imap.gmail.com
+  port: 993        # default: 993
+  encryption: ssl  # default: ssl
+  # username/password default to the smtp values
 ```
 
 ## Development

{email_cli_tool-0.2.0 → email_cli_tool-0.3.0}/README.md

@@ -12,17 +12,27 @@
 - Direct SMTP connection (SSL / STARTTLS)
 - Interactive configuration wizard
 - Read body content from stdin
+- Wait for the next incoming email (IMAP) and download its attachments
 
 ## Installation
 
 ```bash
-# From PyPI
+# From PyPI (latest)
 pip install email-cli-tool
 
+# Install a specific version
+pip install email-cli-tool==0.2.0
+
+# Upgrade an existing install
+pip install --upgrade email-cli-tool
+
 # Or with uv
-uv tool install email-cli-tool
+uv tool install email-cli-tool          # latest
+uv tool install email-cli-tool==0.2.0   # specific version
 ```
 
+> The `emailcli skill install` command requires version **0.2.0** or newer.
+
 ## Quick Start
 
 ### 1. Initialize Configuration
@@ -73,6 +83,18 @@ echo "Content" | emailcli send \
   --to user@example.com --subject "Piped" --body -
 ```
 
+### 3. Wait for Incoming Email
+
+```bash
+# Block until the next email arrives, print it, then exit
+emailcli watch
+
+# Wait up to 5 minutes and save attachments
+emailcli watch --timeout 300 --save-attachments ./downloads
+```
+
+Requires IMAP settings — `emailcli init` asks for them, or add an `imap` section to the config (see below).
+
 ## Command Reference
 
 ### `emailcli send`
@@ -89,6 +111,17 @@ echo "Content" | emailcli send \
 
 > At least one of `--body`, `--html`, or `--html-file` is required.
 
+### `emailcli watch`
+
+Wait for the next incoming email (via IMAP polling), print headers and body to stdout, then exit. Only emails arriving **after** the command starts are matched; the received email is marked as read.
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--timeout` | `0` (wait forever) | Max seconds to wait; exits with code `2` on timeout |
+| `--poll-interval` | `10` | Seconds between mailbox checks |
+| `--save-attachments` | | Directory to save attachments into |
+| `--mailbox` | `INBOX` | Mailbox to watch |
+
 ### `emailcli init`
 
 Interactively create the configuration file at `~/.emailcli/config.yaml`.
@@ -124,6 +157,13 @@ smtp:
   username: yourname@gmail.com
   password: your-app-password
   encryption: ssl  # ssl | starttls | none
+
+# Optional, only needed for `emailcli watch`
+imap:
+  host: imap.gmail.com
+  port: 993        # default: 993
+  encryption: ssl  # default: ssl
+  # username/password default to the smtp values
 ```
 
 ## Development

{email_cli_tool-0.2.0 → email_cli_tool-0.3.0}/README_CN.md

@@ -12,17 +12,27 @@
 - SMTP 直连（支持 SSL / STARTTLS）
 - 交互式配置向导
 - 从 stdin 读取正文内容
+- 等待下一封新邮件（IMAP）并下载附件
 
 ## 安装
 
 ```bash
-# 从 PyPI 安装
+# 从 PyPI 安装（最新版）
 pip install email-cli-tool
 
+# 安装指定版本
+pip install email-cli-tool==0.2.0
+
+# 升级已安装的版本
+pip install --upgrade email-cli-tool
+
 # 或使用 uv
-uv tool install email-cli-tool
+uv tool install email-cli-tool          # 最新版
+uv tool install email-cli-tool==0.2.0   # 指定版本
 ```
 
+> `emailcli skill install` 命令需要 **0.2.0** 或更高版本。
+
 ## 快速开始
 
 ### 1. 初始化配置
@@ -73,6 +83,18 @@ echo "邮件内容" | emailcli send \
   --to user@example.com --subject "Piped" --body -
 ```
 
+### 3. 等待新邮件
+
+```bash
+# 阻塞等待下一封新邮件，打印内容后退出
+emailcli watch
+
+# 最多等 5 分钟，并保存附件
+emailcli watch --timeout 300 --save-attachments ./downloads
+```
+
+需要 IMAP 配置 —— `emailcli init` 会询问，也可以手动在配置文件中加 `imap` 段（见下文）。
+
 ## 命令参考
 
 ### `emailcli send`
@@ -89,6 +111,17 @@ echo "邮件内容" | emailcli send \
 
 > `--body` 和 `--html` / `--html-file` 至少提供一个。
 
+### `emailcli watch`
+
+通过 IMAP 轮询等待下一封新邮件，把邮件头和正文打印到 stdout 后退出。只匹配命令启动**之后**到达的邮件；收到的邮件会被标记为已读。
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| `--timeout` | `0`（一直等） | 最长等待秒数，超时退出码为 `2` |
+| `--poll-interval` | `10` | 轮询间隔（秒） |
+| `--save-attachments` | | 附件保存目录 |
+| `--mailbox` | `INBOX` | 监听的邮箱文件夹 |
+
 ### `emailcli init`
 
 交互式创建配置文件 `~/.emailcli/config.yaml`。
@@ -124,6 +157,13 @@ smtp:
   username: yourname@163.com
   password: your-auth-code
   encryption: ssl  # ssl | starttls | none
+
+# 可选，仅 `emailcli watch` 需要
+imap:
+  host: imap.163.com
+  port: 993        # 默认 993
+  encryption: ssl  # 默认 ssl
+  # username/password 默认复用 smtp 的值
 ```
 
 ## 开发

{email_cli_tool-0.2.0 → email_cli_tool-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "email-cli-tool"
-version = "0.2.0"
+version = "0.3.0"
 description = "A simple CLI tool for sending emails with plain text, HTML, and file attachments"
 readme = "README.md"
 license = "MIT"

{email_cli_tool-0.2.0 → email_cli_tool-0.3.0}/src/emailcli/cli.py

@@ -6,11 +6,13 @@ import click
 from emailcli.config import load_config
 from emailcli.exceptions import EmailCliError
 from emailcli.message import build_message
+from emailcli.receiver import ImapReceiver, extract_body, save_attachments
 from emailcli.sender import SmtpSender
 from emailcli import skill_install
 
 
 @click.group()
+@click.version_option(package_name="email-cli-tool")
 def cli():
     """CLI tool for sending emails with attachments."""
 
@@ -73,6 +75,71 @@ def send(to_addrs, subject, body, html_content, html_file_path, attachments, fro
         raise SystemExit(1)
 
 
+@cli.command()
+@click.option("--timeout", default=0.0, type=float, help="Max seconds to wait for a new email (0 = wait forever).")
+@click.option("--poll-interval", default=10.0, type=float, show_default=True, help="Seconds between mailbox checks.")
+@click.option("--save-attachments", "attachments_dir", default=None, type=click.Path(file_okay=False), help="Directory to save attachments into.")
+@click.option("--mailbox", default="INBOX", show_default=True, help="Mailbox to watch.")
+@click.option("--config-dir", default=None, type=click.Path(), hidden=True, help="Config directory (for testing).")
+def watch(timeout, poll_interval, attachments_dir, mailbox, config_dir):
+    """Wait for the next incoming email, print it, then exit.
+
+    Only emails arriving after the command starts are matched. Exits with
+    code 0 when an email was received, 2 on timeout.
+    """
+    try:
+        cfg_dir = Path(config_dir) if config_dir else None
+        config = load_config(cfg_dir)
+
+        if config.imap is None:
+            raise EmailCliError(
+                "No IMAP settings in config. Re-run 'emailcli init' "
+                "or add an 'imap' section to config.yaml."
+            )
+
+        receiver = ImapReceiver(
+            host=config.imap.host,
+            port=config.imap.port,
+            username=config.imap.username,
+            password=config.imap.password,
+            encryption=config.imap.encryption,
+        )
+
+        click.echo(f"Waiting for new email in {mailbox}... (Ctrl-C to stop)", err=True)
+        msg = receiver.wait_for_message(
+            mailbox=mailbox, timeout=timeout, poll_interval=poll_interval
+        )
+        if msg is None:
+            click.echo(f"Timed out after {timeout:g}s with no new email.", err=True)
+            raise SystemExit(2)
+
+        click.echo(f"From:    {msg.get('From', '')}")
+        click.echo(f"To:      {msg.get('To', '')}")
+        click.echo(f"Subject: {msg.get('Subject', '')}")
+        click.echo(f"Date:    {msg.get('Date', '')}")
+        click.echo("")
+
+        body, kind = extract_body(msg)
+        if body:
+            if kind == "html":
+                click.echo("(HTML body)", err=True)
+            click.echo(body)
+        else:
+            click.echo("(no text body)", err=True)
+
+        if attachments_dir:
+            saved = save_attachments(msg, Path(attachments_dir))
+            if saved:
+                for path in saved:
+                    click.echo(f"Saved attachment: {path}", err=True)
+            else:
+                click.echo("No attachments.", err=True)
+    except EmailCliError as e:
+        click.echo(f"Error: {e}", err=True)
+        raise SystemExit(1)
+
+
+
 @cli.command()
 @click.option("--config-dir", default=None, type=click.Path(), hidden=True, help="Config directory (for testing).")
 def init(config_dir):
@@ -100,6 +167,25 @@ def init(config_dir):
         "Encryption (starttls/ssl/none)", default="ssl"
     )
 
+    imap_section = None
+    if click.confirm("\nConfigure IMAP (needed for 'emailcli watch')?", default=False):
+        imap_host = click.prompt("IMAP host")
+        imap_port = click.prompt("IMAP port", type=int, default=993)
+        imap_username = click.prompt("IMAP username", default=smtp_username)
+        imap_password = click.prompt(
+            "IMAP password (empty = same as SMTP)",
+            hide_input=True, default="", show_default=False,
+        )
+        imap_encryption = click.prompt("IMAP encryption (ssl/starttls/none)", default="ssl")
+        imap_section = {
+            "host": imap_host,
+            "port": imap_port,
+            "username": imap_username,
+            "encryption": imap_encryption,
+        }
+        if imap_password:
+            imap_section["password"] = imap_password
+
     config_data = {
         "from": from_addr,
         "smtp": {
@@ -110,6 +196,8 @@ def init(config_dir):
             "encryption": smtp_encryption,
         },
     }
+    if imap_section:
+        config_data["imap"] = imap_section
 
     cfg_dir.mkdir(parents=True, exist_ok=True)
     with open(config_file, "w") as f:
@@ -138,6 +226,12 @@ def show(config_dir):
         click.echo(f"Username:   {cfg.smtp_username}")
         click.echo(f"Password:   ***")
         click.echo(f"Encryption: {cfg.smtp_encryption}")
+        if cfg.imap:
+            click.echo("")
+            click.echo(f"IMAP Host:  {cfg.imap.host}")
+            click.echo(f"IMAP Port:  {cfg.imap.port}")
+            click.echo(f"IMAP User:  {cfg.imap.username}")
+            click.echo(f"IMAP Encryption: {cfg.imap.encryption}")
     except EmailCliError as e:
         click.echo(f"Error: {e}", err=True)
         raise SystemExit(1)

{email_cli_tool-0.2.0 → email_cli_tool-0.3.0}/src/emailcli/config.py

@@ -6,6 +6,15 @@ import yaml
 from emailcli.exceptions import ConfigError
 
 
+@dataclass(frozen=True)
+class ImapConfig:
+    host: str
+    port: int
+    username: str
+    password: str
+    encryption: str  # "ssl" | "starttls" | "none"
+
+
 @dataclass(frozen=True)
 class ConfigData:
     from_addr: str
@@ -14,6 +23,7 @@ class ConfigData:
     smtp_username: str
     smtp_password: str
     smtp_encryption: str  # "starttls" | "ssl" | "none"
+    imap: ImapConfig | None = None
 
 
 def load_config(config_dir: Path | None = None) -> ConfigData:
@@ -43,6 +53,23 @@ def load_config(config_dir: Path | None = None) -> ConfigData:
         if field not in smtp:
             raise ConfigError(f"Missing required smtp field: '{field}'")
 
+    imap_data = data.get("imap")
+    imap = None
+    if imap_data is not None:
+        if not isinstance(imap_data, dict):
+            raise ConfigError("'imap' must be a mapping")
+        if "host" not in imap_data:
+            raise ConfigError("Missing required imap field: 'host'")
+        # Username/password default to the SMTP credentials (common case:
+        # same account, e.g. a Gmail app password works for both).
+        imap = ImapConfig(
+            host=imap_data["host"],
+            port=imap_data.get("port", 993),
+            username=imap_data.get("username", smtp["username"]),
+            password=imap_data.get("password", smtp["password"]),
+            encryption=imap_data.get("encryption", "ssl"),
+        )
+
     return ConfigData(
         from_addr=data.get("from", ""),
         smtp_host=smtp["host"],
@@ -50,4 +77,5 @@ def load_config(config_dir: Path | None = None) -> ConfigData:
         smtp_username=smtp["username"],
         smtp_password=smtp["password"],
         smtp_encryption=smtp.get("encryption", "starttls"),
+        imap=imap,
     )

{email_cli_tool-0.2.0 → email_cli_tool-0.3.0}/src/emailcli/exceptions.py

@@ -12,3 +12,7 @@ class MessageError(EmailCliError):
 
 class SendError(EmailCliError):
     """Email sending errors."""
+
+
+class ReceiveError(EmailCliError):
+    """Email receiving errors."""

email_cli_tool-0.3.0/src/emailcli/receiver.py

@@ -0,0 +1,146 @@
+import email
+import email.policy
+import imaplib
+import re
+import time
+from email.message import EmailMessage
+from pathlib import Path
+
+from emailcli.exceptions import ReceiveError
+
+_UIDNEXT_RE = re.compile(rb"UIDNEXT (\d+)")
+
+
+class ImapReceiver:
+    def __init__(
+        self,
+        host: str,
+        port: int,
+        username: str,
+        password: str,
+        encryption: str,
+    ):
+        self.host = host
+        self.port = port
+        self.username = username
+        self.password = password
+        self.encryption = encryption
+
+    def _connect(self) -> imaplib.IMAP4:
+        try:
+            if self.encryption == "ssl":
+                conn = imaplib.IMAP4_SSL(self.host, self.port)
+            else:
+                conn = imaplib.IMAP4(self.host, self.port)
+                if self.encryption == "starttls":
+                    conn.starttls()
+            conn.login(self.username, self.password)
+            return conn
+        except Exception as e:
+            raise ReceiveError(f"Failed to connect to IMAP server: {e}") from e
+
+    def wait_for_message(
+        self,
+        mailbox: str = "INBOX",
+        timeout: float = 0,
+        poll_interval: float = 10.0,
+    ) -> EmailMessage | None:
+        """Block until a message arrives after this call starts.
+
+        Polls the mailbox every poll_interval seconds and returns the first
+        message whose UID is >= the UIDNEXT recorded at start, so existing
+        unread mail is ignored. Returns None if timeout (seconds, 0 = no
+        limit) expires first.
+        """
+        conn = self._connect()
+        try:
+            typ, data = conn.status(mailbox, "(UIDNEXT)")
+            if typ != "OK":
+                raise ReceiveError(f"IMAP STATUS failed: {data}")
+            match = _UIDNEXT_RE.search(data[0])
+            if not match:
+                raise ReceiveError(f"Could not read UIDNEXT from: {data[0]!r}")
+            uidnext = int(match.group(1))
+
+            typ, data = conn.select(mailbox)
+            if typ != "OK":
+                raise ReceiveError(f"Cannot select mailbox {mailbox!r}: {data}")
+
+            deadline = time.monotonic() + timeout if timeout > 0 else None
+            while True:
+                # NOOP prompts the server to report newly arrived messages.
+                conn.noop()
+                typ, data = conn.uid("search", "UID", f"{uidnext}:*")
+                if typ != "OK":
+                    raise ReceiveError(f"IMAP SEARCH failed: {data}")
+                uids = [int(u) for u in data[0].split()] if data and data[0] else []
+                # "N:*" also matches the last existing message when its UID
+                # is below N, so keep only genuinely new UIDs.
+                new = sorted(u for u in uids if u >= uidnext)
+                if new:
+                    return self._fetch(conn, new[0])
+                if deadline is not None and time.monotonic() >= deadline:
+                    return None
+                sleep_for = poll_interval
+                if deadline is not None:
+                    sleep_for = min(sleep_for, max(0.0, deadline - time.monotonic()))
+                time.sleep(sleep_for)
+        except ReceiveError:
+            raise
+        except Exception as e:
+            raise ReceiveError(f"Failed while waiting for email: {e}") from e
+        finally:
+            try:
+                conn.logout()
+            except Exception:
+                pass
+
+    def _fetch(self, conn: imaplib.IMAP4, uid: int) -> EmailMessage:
+        typ, msg_data = conn.uid("fetch", str(uid), "(RFC822)")
+        if typ != "OK":
+            raise ReceiveError(f"IMAP FETCH failed: {msg_data}")
+        raw = None
+        for item in msg_data:
+            if isinstance(item, tuple) and len(item) >= 2 and isinstance(item[1], (bytes, bytearray)):
+                raw = item[1]
+                break
+        if raw is None:
+            raise ReceiveError(f"Unexpected FETCH response for UID {uid}")
+        return email.message_from_bytes(raw, policy=email.policy.default)
+
+
+def extract_body(msg: EmailMessage) -> tuple[str, str]:
+    """Return (content, kind) where kind is "text", "html", or ""."""
+    part = msg.get_body(preferencelist=("plain", "html"))
+    if part is None:
+        return "", ""
+    kind = "html" if part.get_content_subtype() == "html" else "text"
+    return part.get_content(), kind
+
+
+def save_attachments(msg: EmailMessage, dest: Path) -> list[Path]:
+    """Save all attachments into dest, returning the written paths.
+
+    Filenames are stripped to their basename and deduplicated with -1, -2...
+    suffixes so a crafted attachment name cannot escape dest or overwrite
+    an earlier file.
+    """
+    dest.mkdir(parents=True, exist_ok=True)
+    saved: list[Path] = []
+    for i, part in enumerate(msg.iter_attachments()):
+        name = Path(part.get_filename() or f"attachment-{i + 1}").name
+        if not name or name in (".", ".."):
+            name = f"attachment-{i + 1}"
+        target = dest / name
+        stem, suffix = target.stem, target.suffix
+        n = 1
+        while target.exists():
+            target = dest / f"{stem}-{n}{suffix}"
+            n += 1
+        payload = part.get_payload(decode=True)
+        if payload is None:
+            content = part.get_content()
+            payload = content.encode() if isinstance(content, str) else bytes(content)
+        target.write_bytes(payload)
+        saved.append(target)
+    return saved

{email_cli_tool-0.2.0 → email_cli_tool-0.3.0}/tests/test_cli.py

@@ -1,3 +1,4 @@
+from importlib.metadata import version as pkg_version
 from pathlib import Path
 from unittest.mock import MagicMock, patch
 
@@ -178,7 +179,7 @@ def test_init_creates_config(runner, tmp_path):
     result = runner.invoke(cli, [
         "init",
         "--config-dir", str(config_dir),
-    ], input="me@163.com\nsmtp.163.com\n465\nme@163.com\nmypassword\nssl\n")
+    ], input="me@163.com\nsmtp.163.com\n465\nme@163.com\nmypassword\nssl\nn\n")
     assert result.exit_code == 0
     assert (config_dir / "config.yaml").exists()
 
@@ -190,7 +191,7 @@ def test_init_sets_file_permissions(runner, tmp_path):
     result = runner.invoke(cli, [
         "init",
         "--config-dir", str(config_dir),
-    ], input="me@163.com\nsmtp.163.com\n465\nme@163.com\nmypassword\nssl\n")
+    ], input="me@163.com\nsmtp.163.com\n465\nme@163.com\nmypassword\nssl\nn\n")
     assert result.exit_code == 0
 
     config_file = config_dir / "config.yaml"
@@ -217,3 +218,152 @@ def test_config_show_no_config(runner, tmp_path):
         "--config-dir", str(tmp_path / "nonexistent"),
     ])
     assert result.exit_code != 0
+
+
+def test_version_option(runner):
+    result = runner.invoke(cli, ["--version"])
+    assert result.exit_code == 0
+    assert pkg_version("email-cli-tool") in result.output
+
+
+@pytest.fixture
+def config_home_imap(tmp_path):
+    config_dir = tmp_path / ".emailcli"
+    config_dir.mkdir()
+    (config_dir / "config.yaml").write_text(yaml.dump({
+        "from": "me@example.com",
+        "smtp": {
+            "host": "smtp.example.com",
+            "port": 587,
+            "username": "me@example.com",
+            "password": "secret",
+            "encryption": "starttls",
+        },
+        "imap": {
+            "host": "imap.example.com",
+        },
+    }))
+    return config_dir
+
+
+def _sample_incoming_message(attachments=None):
+    import email
+    import email.policy
+    from email.message import EmailMessage
+
+    msg = EmailMessage()
+    msg["From"] = "sender@example.com"
+    msg["To"] = "me@example.com"
+    msg["Subject"] = "Incoming"
+    msg["Date"] = "Mon, 31 Aug 2026 10:00:00 +0800"
+    msg.set_content("Incoming body")
+    for name, data in (attachments or []):
+        msg.add_attachment(
+            data, maintype="application", subtype="octet-stream", filename=name
+        )
+    return email.message_from_bytes(bytes(msg), policy=email.policy.default)
+
+
+@patch("emailcli.cli.ImapReceiver")
+def test_watch_receives_message(mock_receiver_cls, runner, config_home_imap):
+    mock_receiver = MagicMock()
+    mock_receiver.wait_for_message.return_value = _sample_incoming_message()
+    mock_receiver_cls.return_value = mock_receiver
+
+    result = runner.invoke(cli, ["watch", "--config-dir", str(config_home_imap)])
+
+    assert result.exit_code == 0
+    assert "Subject: Incoming" in result.output
+    assert "Incoming body" in result.output
+    # IMAP credentials fall back to SMTP ones
+    mock_receiver_cls.assert_called_once_with(
+        host="imap.example.com",
+        port=993,
+        username="me@example.com",
+        password="secret",
+        encryption="ssl",
+    )
+
+
+@patch("emailcli.cli.ImapReceiver")
+def test_watch_saves_attachments(mock_receiver_cls, runner, config_home_imap, tmp_path):
+    mock_receiver = MagicMock()
+    mock_receiver.wait_for_message.return_value = _sample_incoming_message(
+        attachments=[("report.pdf", b"%PDF-1.4")]
+    )
+    mock_receiver_cls.return_value = mock_receiver
+
+    dest = tmp_path / "downloads"
+    result = runner.invoke(cli, [
+        "watch",
+        "--config-dir", str(config_home_imap),
+        "--save-attachments", str(dest),
+    ])
+
+    assert result.exit_code == 0
+    assert (dest / "report.pdf").read_bytes() == b"%PDF-1.4"
+
+
+@patch("emailcli.cli.ImapReceiver")
+def test_watch_timeout_exits_2(mock_receiver_cls, runner, config_home_imap):
+    mock_receiver = MagicMock()
+    mock_receiver.wait_for_message.return_value = None
+    mock_receiver_cls.return_value = mock_receiver
+
+    result = runner.invoke(cli, [
+        "watch", "--timeout", "1", "--config-dir", str(config_home_imap),
+    ])
+
+    assert result.exit_code == 2
+    assert "Timed out" in result.output
+
+
+def test_watch_without_imap_config(runner, config_home):
+    result = runner.invoke(cli, ["watch", "--config-dir", str(config_home)])
+
+    assert result.exit_code == 1
+    assert "IMAP" in result.output
+
+
+@patch("emailcli.cli.ImapReceiver")
+def test_watch_passes_options(mock_receiver_cls, runner, config_home_imap):
+    mock_receiver = MagicMock()
+    mock_receiver.wait_for_message.return_value = _sample_incoming_message()
+    mock_receiver_cls.return_value = mock_receiver
+
+    result = runner.invoke(cli, [
+        "watch",
+        "--timeout", "300",
+        "--poll-interval", "5",
+        "--mailbox", "Work",
+        "--config-dir", str(config_home_imap),
+    ])
+
+    assert result.exit_code == 0
+    mock_receiver.wait_for_message.assert_called_once_with(
+        mailbox="Work", timeout=300.0, poll_interval=5.0
+    )
+
+
+def test_init_with_imap(runner, tmp_path):
+    config_dir = tmp_path / ".emailcli"
+    result = runner.invoke(cli, [
+        "init",
+        "--config-dir", str(config_dir),
+    ], input=(
+        "me@163.com\nsmtp.163.com\n465\nme@163.com\nmypassword\nssl\n"  # smtp
+        "y\nimap.163.com\n993\nme@163.com\n\nssl\n"  # imap, empty password = reuse
+    ))
+    assert result.exit_code == 0
+
+    data = yaml.safe_load((config_dir / "config.yaml").read_text())
+    assert data["imap"]["host"] == "imap.163.com"
+    assert data["imap"]["port"] == 993
+    assert "password" not in data["imap"]  # falls back to smtp password
+
+
+def test_config_show_with_imap(runner, config_home_imap):
+    result = runner.invoke(cli, ["config", "show", "--config-dir", str(config_home_imap)])
+    assert result.exit_code == 0
+    assert "imap.example.com" in result.output
+    assert "secret" not in result.output

email_cli_tool-0.3.0/tests/test_config.py

@@ -0,0 +1,145 @@
+import os
+from pathlib import Path
+
+import pytest
+import yaml
+
+from emailcli.config import load_config, ConfigData
+
+
+@pytest.fixture
+def config_dir(tmp_path):
+    return tmp_path / ".emailcli"
+
+
+@pytest.fixture
+def valid_config(config_dir):
+    config_dir.mkdir()
+    config_file = config_dir / "config.yaml"
+    config_file.write_text(yaml.dump({
+        "from": "me@example.com",
+        "smtp": {
+            "host": "smtp.example.com",
+            "port": 587,
+            "username": "me@example.com",
+            "password": "secret",
+            "encryption": "starttls",
+        },
+    }))
+    return config_file
+
+
+def test_load_valid_config(valid_config, config_dir):
+    config = load_config(config_dir)
+    assert config.from_addr == "me@example.com"
+    assert config.smtp_host == "smtp.example.com"
+    assert config.smtp_port == 587
+    assert config.smtp_username == "me@example.com"
+    assert config.smtp_password == "secret"
+    assert config.smtp_encryption == "starttls"
+
+
+def test_load_config_file_not_found(config_dir):
+    from emailcli.exceptions import ConfigError
+
+    with pytest.raises(ConfigError, match="not found"):
+        load_config(config_dir)
+
+
+def test_load_config_missing_smtp_host(config_dir):
+    from emailcli.exceptions import ConfigError
+
+    config_dir.mkdir()
+    config_file = config_dir / "config.yaml"
+    config_file.write_text(yaml.dump({
+        "from": "me@example.com",
+        "smtp": {"port": 587},
+    }))
+    with pytest.raises(ConfigError, match="host"):
+        load_config(config_dir)
+
+
+def test_load_config_ssl_encryption(config_dir):
+    config_dir.mkdir()
+    config_file = config_dir / "config.yaml"
+    config_file.write_text(yaml.dump({
+        "from": "me@example.com",
+        "smtp": {
+            "host": "smtp.163.com",
+            "port": 465,
+            "username": "me@163.com",
+            "password": "authcode",
+            "encryption": "ssl",
+        },
+    }))
+    config = load_config(config_dir)
+    assert config.smtp_encryption == "ssl"
+    assert config.smtp_port == 465
+
+
+def test_load_config_without_imap(valid_config, config_dir):
+    config = load_config(config_dir)
+    assert config.imap is None
+
+
+def test_load_config_with_imap(config_dir):
+    config_dir.mkdir()
+    (config_dir / "config.yaml").write_text(yaml.dump({
+        "from": "me@example.com",
+        "smtp": {
+            "host": "smtp.example.com",
+            "username": "me@example.com",
+            "password": "secret",
+        },
+        "imap": {
+            "host": "imap.example.com",
+            "port": 143,
+            "username": "other@example.com",
+            "password": "imap-secret",
+            "encryption": "starttls",
+        },
+    }))
+    config = load_config(config_dir)
+    assert config.imap is not None
+    assert config.imap.host == "imap.example.com"
+    assert config.imap.port == 143
+    assert config.imap.username == "other@example.com"
+    assert config.imap.password == "imap-secret"
+    assert config.imap.encryption == "starttls"
+
+
+def test_load_config_imap_defaults_from_smtp(config_dir):
+    config_dir.mkdir()
+    (config_dir / "config.yaml").write_text(yaml.dump({
+        "from": "me@example.com",
+        "smtp": {
+            "host": "smtp.example.com",
+            "username": "me@example.com",
+            "password": "secret",
+        },
+        "imap": {
+            "host": "imap.example.com",
+        },
+    }))
+    config = load_config(config_dir)
+    assert config.imap.port == 993
+    assert config.imap.encryption == "ssl"
+    assert config.imap.username == "me@example.com"
+    assert config.imap.password == "secret"
+
+
+def test_load_config_imap_missing_host(config_dir):
+    from emailcli.exceptions import ConfigError
+
+    config_dir.mkdir()
+    (config_dir / "config.yaml").write_text(yaml.dump({
+        "from": "me@example.com",
+        "smtp": {
+            "host": "smtp.example.com",
+            "username": "me@example.com",
+            "password": "secret",
+        },
+        "imap": {"port": 993},
+    }))
+    with pytest.raises(ConfigError, match="imap.*host"):
+        load_config(config_dir)

email_cli_tool-0.3.0/tests/test_receiver.py

@@ -0,0 +1,194 @@
+from email.message import EmailMessage
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from emailcli.exceptions import ReceiveError
+from emailcli.receiver import ImapReceiver, extract_body, save_attachments
+
+
+def make_raw_message(body="Hello", html=None, attachments=None):
+    msg = EmailMessage()
+    msg["From"] = "sender@example.com"
+    msg["To"] = "me@example.com"
+    msg["Subject"] = "Test mail"
+    if body:
+        msg.set_content(body)
+    if html:
+        msg.add_alternative(html, subtype="html")
+    for name, data in (attachments or []):
+        msg.add_attachment(
+            data, maintype="application", subtype="octet-stream", filename=name
+        )
+    return bytes(msg)
+
+
+def make_conn(search_results, raw=None, uidnext=100):
+    """Mock IMAP connection. search_results: list of SEARCH data bytes per poll."""
+    conn = MagicMock()
+    conn.status.return_value = ("OK", [b"INBOX (UIDNEXT %d)" % uidnext])
+    conn.select.return_value = ("OK", [b"3"])
+    conn.noop.return_value = ("OK", [b""])
+    results = iter(search_results)
+
+    def uid(cmd, *args):
+        if cmd == "search":
+            return ("OK", [next(results)])
+        if cmd == "fetch":
+            return ("OK", [(b"1 (RFC822 {123}", raw), b")"])
+        raise AssertionError(f"unexpected uid command: {cmd}")
+
+    conn.uid.side_effect = uid
+    return conn
+
+
+def make_receiver():
+    return ImapReceiver(
+        host="imap.example.com",
+        port=993,
+        username="me@example.com",
+        password="secret",
+        encryption="ssl",
+    )
+
+
+@patch("emailcli.receiver.imaplib.IMAP4_SSL")
+def test_wait_returns_new_message(mock_imap_cls):
+    raw = make_raw_message(body="Hello there")
+    conn = make_conn([b"100"], raw=raw)
+    mock_imap_cls.return_value = conn
+
+    msg = make_receiver().wait_for_message(timeout=5, poll_interval=0.01)
+
+    assert msg is not None
+    assert msg["Subject"] == "Test mail"
+    conn.login.assert_called_once_with("me@example.com", "secret")
+    conn.uid.assert_any_call("search", "UID", "100:*")
+
+
+@patch("emailcli.receiver.imaplib.IMAP4_SSL")
+def test_wait_ignores_existing_mail(mock_imap_cls):
+    # "100:*" matches the last existing message (UID 99) even though it is
+    # older than UIDNEXT; it must be ignored, then UID 100 arrives.
+    raw = make_raw_message()
+    conn = make_conn([b"99", b"99 100"], raw=raw)
+    mock_imap_cls.return_value = conn
+
+    msg = make_receiver().wait_for_message(timeout=5, poll_interval=0.01)
+
+    assert msg is not None
+    # Fetched the new message, not the old one
+    conn.uid.assert_any_call("fetch", "100", "(RFC822)")
+
+
+@patch("emailcli.receiver.imaplib.IMAP4_SSL")
+def test_wait_timeout_returns_none(mock_imap_cls):
+    conn = make_conn([b"", b"", b"", b"", b""])
+    mock_imap_cls.return_value = conn
+
+    msg = make_receiver().wait_for_message(timeout=0.03, poll_interval=0.01)
+
+    assert msg is None
+    conn.logout.assert_called_once()
+
+
+@patch("emailcli.receiver.imaplib.IMAP4_SSL")
+def test_connect_failure_raises_receive_error(mock_imap_cls):
+    mock_imap_cls.side_effect = OSError("connection refused")
+
+    with pytest.raises(ReceiveError, match="connect"):
+        make_receiver().wait_for_message(timeout=1, poll_interval=0.01)
+
+
+@patch("emailcli.receiver.imaplib.IMAP4_SSL")
+def test_bad_status_raises(mock_imap_cls):
+    conn = MagicMock()
+    conn.status.return_value = ("NO", [b"error"])
+    mock_imap_cls.return_value = conn
+
+    with pytest.raises(ReceiveError, match="STATUS"):
+        make_receiver().wait_for_message(timeout=1, poll_interval=0.01)
+
+
+@patch("emailcli.receiver.imaplib.IMAP4")
+def test_starttls_connection(mock_imap_cls):
+    raw = make_raw_message()
+    conn = make_conn([b"100"], raw=raw)
+    mock_imap_cls.return_value = conn
+
+    receiver = ImapReceiver(
+        host="imap.example.com",
+        port=143,
+        username="me@example.com",
+        password="secret",
+        encryption="starttls",
+    )
+    msg = receiver.wait_for_message(timeout=5, poll_interval=0.01)
+
+    assert msg is not None
+    conn.starttls.assert_called_once()
+
+
+def parse(raw):
+    import email
+    import email.policy
+
+    return email.message_from_bytes(raw, policy=email.policy.default)
+
+
+def test_extract_body_plain():
+    msg = parse(make_raw_message(body="Plain text"))
+    body, kind = extract_body(msg)
+    assert body.strip() == "Plain text"
+    assert kind == "text"
+
+
+def test_extract_body_prefers_plain_over_html():
+    msg = parse(make_raw_message(body="Plain", html="<p>HTML</p>"))
+    body, kind = extract_body(msg)
+    assert body.strip() == "Plain"
+    assert kind == "text"
+
+
+def test_extract_body_html_only():
+    msg = EmailMessage()
+    msg["Subject"] = "html"
+    msg.set_content("<p>HTML only</p>", subtype="html")
+    body, kind = extract_body(parse(bytes(msg)))
+    assert "HTML only" in body
+    assert kind == "html"
+
+
+def test_save_attachments(tmp_path):
+    raw = make_raw_message(attachments=[("report.pdf", b"%PDF-1.4")])
+    saved = save_attachments(parse(raw), tmp_path / "downloads")
+
+    assert len(saved) == 1
+    assert saved[0].name == "report.pdf"
+    assert saved[0].read_bytes() == b"%PDF-1.4"
+
+
+def test_save_attachments_sanitizes_path(tmp_path):
+    raw = make_raw_message(attachments=[("../../evil.sh", b"#!/bin/sh")])
+    dest = tmp_path / "downloads"
+    saved = save_attachments(parse(raw), dest)
+
+    assert saved[0].parent == dest
+    assert saved[0].name == "evil.sh"
+    assert not (tmp_path / "evil.sh").exists()
+
+
+def test_save_attachments_deduplicates(tmp_path):
+    raw = make_raw_message(
+        attachments=[("a.txt", b"one"), ("a.txt", b"two")]
+    )
+    saved = save_attachments(parse(raw), tmp_path)
+
+    assert [p.name for p in saved] == ["a.txt", "a-1.txt"]
+    assert (tmp_path / "a-1.txt").read_bytes() == b"two"
+
+
+def test_save_attachments_none(tmp_path):
+    raw = make_raw_message(body="no attachments")
+    assert save_attachments(parse(raw), tmp_path) == []

{email_cli_tool-0.2.0 → email_cli_tool-0.3.0}/uv.lock

@@ -25,7 +25,7 @@ wheels = [
 
 [[package]]
 name = "email-cli-tool"
-version = "0.2.0"
+version = "0.2.1"
 source = { editable = "." }
 dependencies = [
     { name = "click" },

email_cli_tool-0.2.0/tests/test_config.py

@@ -1,77 +0,0 @@
-import os
-from pathlib import Path
-
-import pytest
-import yaml
-
-from emailcli.config import load_config, ConfigData
-
-
-@pytest.fixture
-def config_dir(tmp_path):
-    return tmp_path / ".emailcli"
-
-
-@pytest.fixture
-def valid_config(config_dir):
-    config_dir.mkdir()
-    config_file = config_dir / "config.yaml"
-    config_file.write_text(yaml.dump({
-        "from": "me@example.com",
-        "smtp": {
-            "host": "smtp.example.com",
-            "port": 587,
-            "username": "me@example.com",
-            "password": "secret",
-            "encryption": "starttls",
-        },
-    }))
-    return config_file
-
-
-def test_load_valid_config(valid_config, config_dir):
-    config = load_config(config_dir)
-    assert config.from_addr == "me@example.com"
-    assert config.smtp_host == "smtp.example.com"
-    assert config.smtp_port == 587
-    assert config.smtp_username == "me@example.com"
-    assert config.smtp_password == "secret"
-    assert config.smtp_encryption == "starttls"
-
-
-def test_load_config_file_not_found(config_dir):
-    from emailcli.exceptions import ConfigError
-
-    with pytest.raises(ConfigError, match="not found"):
-        load_config(config_dir)
-
-
-def test_load_config_missing_smtp_host(config_dir):
-    from emailcli.exceptions import ConfigError
-
-    config_dir.mkdir()
-    config_file = config_dir / "config.yaml"
-    config_file.write_text(yaml.dump({
-        "from": "me@example.com",
-        "smtp": {"port": 587},
-    }))
-    with pytest.raises(ConfigError, match="host"):
-        load_config(config_dir)
-
-
-def test_load_config_ssl_encryption(config_dir):
-    config_dir.mkdir()
-    config_file = config_dir / "config.yaml"
-    config_file.write_text(yaml.dump({
-        "from": "me@example.com",
-        "smtp": {
-            "host": "smtp.163.com",
-            "port": 465,
-            "username": "me@163.com",
-            "password": "authcode",
-            "encryption": "ssl",
-        },
-    }))
-    config = load_config(config_dir)
-    assert config.smtp_encryption == "ssl"
-    assert config.smtp_port == 465