mxctl 0.3.0__py3-none-any.whl

mxctl/commands/mail/analytics.py

@@ -0,0 +1,390 @@
+"""Mail analytics commands: stats, top-senders, digest, show-flagged."""
+
+from collections import Counter, defaultdict
+from datetime import datetime, timedelta
+
+from mxctl.config import (
+    APPLESCRIPT_TIMEOUT_LONG,
+    DEFAULT_DIGEST_LIMIT,
+    DEFAULT_MAILBOX,
+    DEFAULT_MESSAGE_LIMIT,
+    DEFAULT_TOP_SENDERS_LIMIT,
+    FIELD_SEPARATOR,
+    MAX_MESSAGES_BATCH,
+    resolve_account,
+    save_message_aliases,
+    validate_limit,
+)
+from mxctl.util.applescript import escape, run
+from mxctl.util.dates import to_applescript_date
+from mxctl.util.formatting import die, format_output, truncate
+from mxctl.util.mail_helpers import extract_email, parse_message_line
+
+# ---------------------------------------------------------------------------
+# top-senders
+# ---------------------------------------------------------------------------
+
+def cmd_top_senders(args) -> None:
+    """Show most frequent email senders over a time period."""
+    days = getattr(args, "days", 30)
+    limit = getattr(args, "limit", DEFAULT_TOP_SENDERS_LIMIT)
+
+    since_dt = datetime.now() - timedelta(days=days)
+    since_as = to_applescript_date(since_dt)
+
+    script = f"""
+    tell application "Mail"
+        set output to ""
+        repeat with acct in (every account)
+            if enabled of acct then
+                repeat with mbox in (mailboxes of acct)
+                    if name of mbox is "INBOX" then
+                        try
+                            set msgs to (every message of mbox whose date received >= date "{since_as}")
+                            set msgCount to count of msgs
+                            set cap to {MAX_MESSAGES_BATCH}
+                            if msgCount < cap then set cap to msgCount
+                            repeat with i from 1 to cap
+                                set m to item i of msgs
+                                set output to output & (sender of m) & linefeed
+                            end repeat
+                        end try
+                        exit repeat
+                    end if
+                end repeat
+            end if
+        end repeat
+        return output
+    end tell
+    """
+
+    result = run(script, timeout=APPLESCRIPT_TIMEOUT_LONG)
+    if not result.strip():
+        format_output(args, f"No messages found in the last {days} days.",
+                      json_data={"days": days, "senders": []})
+        return
+
+    counter = Counter(line.strip() for line in result.strip().split("\n") if line.strip())
+    top = counter.most_common(limit)
+
+    text = f"Top {limit} senders (last {days} days):"
+    for i, (sender, count) in enumerate(top, 1):
+        text += f"\n  {i}. {truncate(sender, 50)} — {count} messages"
+    format_output(args, text, json_data=[{"sender": s, "count": c} for s, c in top])
+
+
+# ---------------------------------------------------------------------------
+# digest — grouped unread summary
+# ---------------------------------------------------------------------------
+
+def cmd_digest(args) -> None:
+    """Show unread messages grouped by sender domain."""
+    script = f"""
+    tell application "Mail"
+        set output to ""
+        repeat with acct in (every account)
+            if enabled of acct then
+                repeat with mbox in (mailboxes of acct)
+                    if name of mbox is "INBOX" then
+                        try
+                            set unreadMsgs to (every message of mbox whose read status is false)
+                            set acctName to name of acct
+                            set cap to {DEFAULT_DIGEST_LIMIT}
+                            if (count of unreadMsgs) < cap then set cap to (count of unreadMsgs)
+                            repeat with j from 1 to cap
+                                set m to item j of unreadMsgs
+                                set output to output & acctName & "{FIELD_SEPARATOR}" & (id of m) & "{FIELD_SEPARATOR}" & (subject of m) & "{FIELD_SEPARATOR}" & (sender of m) & "{FIELD_SEPARATOR}" & (date received of m) & linefeed
+                            end repeat
+                        end try
+                        exit repeat
+                    end if
+                end repeat
+            end if
+        end repeat
+        return output
+    end tell
+    """
+
+    result = run(script, timeout=APPLESCRIPT_TIMEOUT_LONG)
+    if not result.strip():
+        format_output(args, "No unread messages. Inbox zero!")
+        return
+
+    # Group by sender domain
+    groups = defaultdict(list)
+    for line in result.strip().split("\n"):
+        if not line.strip():
+            continue
+        msg = parse_message_line(line, ["account", "id", "subject", "sender", "date"], FIELD_SEPARATOR)
+        if msg is None:
+            continue
+        # Extract domain from sender
+        email = extract_email(msg["sender"])
+        if "@" in email:
+            domain = email.split("@")[1].lower()
+        else:
+            domain = "other"
+        groups[domain].append(msg)
+
+    # Collect all messages into a flat list for sequential aliases
+    all_messages = []
+    for _domain, msgs in sorted(groups.items(), key=lambda x: -len(x[1])):
+        all_messages.extend(msgs)
+    save_message_aliases([m["id"] for m in all_messages])
+    for i, m in enumerate(all_messages, 1):
+        m["alias"] = i
+
+    total = sum(len(msgs) for msgs in groups.values())
+    text = f"Unread Digest ({total} messages, {len(groups)} groups):"
+    for domain, msgs in sorted(groups.items(), key=lambda x: -len(x[1])):
+        text += f"\n\n  {domain} ({len(msgs)}):"
+        for m in msgs[:5]:
+            text += f"\n    [{m['alias']}] {truncate(m['subject'], 45)}"
+            text += f"\n      From: {truncate(m['sender'], 40)}"
+        if len(msgs) > 5:
+            text += f"\n    ... and {len(msgs) - 5} more"
+    format_output(args, text, json_data=dict(groups))
+
+
+# ---------------------------------------------------------------------------
+# stats
+# ---------------------------------------------------------------------------
+
+def cmd_stats(args) -> None:
+    """Show message count and unread count for a mailbox, or account-wide stats with --all."""
+    show_all = getattr(args, "all", False)
+    # For --all, we need to know if the user *explicitly* passed -a, not just the resolved default.
+    # resolve_account() falls back to the configured default (e.g. iCloud), which would cause
+    # --all without -a to incorrectly use the single-account branch.
+    explicit_account = getattr(args, "account", None)
+    account = resolve_account(explicit_account)
+
+    if show_all:
+        # Only use the account branch when the user explicitly specified -a.
+        if explicit_account:
+            # --all -a ACCOUNT: stats for every mailbox in one account
+            acct_escaped = escape(account)
+            script = f"""
+            tell application "Mail"
+                set acct to account "{acct_escaped}"
+                set acctName to name of acct
+                set output to ""
+                set grandTotal to 0
+                set grandUnread to 0
+                repeat with mb in (every mailbox of acct)
+                    set mbName to name of mb
+                    set totalCount to count of messages of mb
+                    set unreadCount to unread count of mb
+                    set grandTotal to grandTotal + totalCount
+                    set grandUnread to grandUnread + unreadCount
+                    set output to output & acctName & "{FIELD_SEPARATOR}" & mbName & "{FIELD_SEPARATOR}" & (totalCount as text) & "{FIELD_SEPARATOR}" & (unreadCount as text) & linefeed
+                end repeat
+                return (grandTotal as text) & "{FIELD_SEPARATOR}" & (grandUnread as text) & linefeed & output
+            end tell
+            """
+        else:
+            # --all (no -a): stats for every mailbox across ALL accounts
+            script = f"""
+            tell application "Mail"
+                set output to ""
+                set grandTotal to 0
+                set grandUnread to 0
+                repeat with acct in (every account)
+                    if enabled of acct then
+                        set acctName to name of acct
+                        repeat with mb in (every mailbox of acct)
+                            set mbName to name of mb
+                            set totalCount to count of messages of mb
+                            set unreadCount to unread count of mb
+                            set grandTotal to grandTotal + totalCount
+                            set grandUnread to grandUnread + unreadCount
+                            set output to output & acctName & "{FIELD_SEPARATOR}" & mbName & "{FIELD_SEPARATOR}" & (totalCount as text) & "{FIELD_SEPARATOR}" & (unreadCount as text) & linefeed
+                        end repeat
+                    end if
+                end repeat
+                return (grandTotal as text) & "{FIELD_SEPARATOR}" & (grandUnread as text) & linefeed & output
+            end tell
+            """
+
+        result = run(script, timeout=APPLESCRIPT_TIMEOUT_LONG)
+        lines = result.strip().split("\n")
+        if not lines:
+            scope = f"account '{account}'" if explicit_account else "any account"
+            format_output(args, f"No mailboxes found in {scope}.",
+                          json_data={"mailboxes": []})
+            return
+
+        # First line has grand totals
+        totals_parts = lines[0].split(FIELD_SEPARATOR)
+        grand_total = int(totals_parts[0]) if len(totals_parts) >= 1 and totals_parts[0].isdigit() else 0
+        grand_unread = int(totals_parts[1]) if len(totals_parts) >= 2 and totals_parts[1].isdigit() else 0
+
+        # Subsequent lines: acctName|mbName|total|unread
+        mailboxes = []
+        for line in lines[1:]:
+            if not line.strip():
+                continue
+            parts = line.split(FIELD_SEPARATOR)
+            if len(parts) >= 4:
+                mailboxes.append({
+                    "account": parts[0],
+                    "name": parts[1],
+                    "total": int(parts[2]) if parts[2].isdigit() else 0,
+                    "unread": int(parts[3]) if parts[3].isdigit() else 0,
+                })
+
+        # Build text output — use explicit_account so resolved defaults don't bleed in.
+        scope_label = f"Account: {account}" if explicit_account else "All Accounts"
+        text = f"{scope_label}\n"
+        text += f"Total: {grand_total} messages, {grand_unread} unread\n"
+        text += f"\nMailboxes ({len(mailboxes)}):"
+        for mb in mailboxes:
+            acct_prefix = "" if explicit_account else f"[{mb['account']}] "
+            text += f"\n  {acct_prefix}{mb['name']}: {mb['total']} messages, {mb['unread']} unread"
+
+        format_output(args, text, json_data={
+            "scope": account or "all",
+            "total_messages": grand_total,
+            "total_unread": grand_unread,
+            "mailboxes": mailboxes,
+        })
+    else:
+        # Single mailbox stats (existing behavior)
+        if not account:
+            die("Account required. Use -a ACCOUNT.")
+        mailbox = getattr(args, "mailbox", None) or DEFAULT_MAILBOX
+        acct_escaped = escape(account)
+        mb_escaped = escape(mailbox)
+
+        script = f"""
+        tell application "Mail"
+            set mb to mailbox "{mb_escaped}" of account "{acct_escaped}"
+            set totalCount to count of messages of mb
+            set unreadCount to unread count of mb
+            return (totalCount as text) & "{FIELD_SEPARATOR}" & (unreadCount as text)
+        end tell
+        """
+
+        result = run(script)
+        parts = result.split(FIELD_SEPARATOR)
+        total = int(parts[0]) if len(parts) >= 1 and parts[0].isdigit() else 0
+        unread = int(parts[1]) if len(parts) >= 2 and parts[1].isdigit() else 0
+
+        format_output(args, f"{mailbox} [{account}]: {total} messages, {unread} unread",
+                      json_data={"mailbox": mailbox, "account": account, "total": total, "unread": unread})
+
+
+# ---------------------------------------------------------------------------
+# show-flagged — list all flagged messages
+# ---------------------------------------------------------------------------
+
+def cmd_show_flagged(args) -> None:
+    """List all flagged messages."""
+    account = resolve_account(getattr(args, "account", None))
+    limit = validate_limit(getattr(args, "limit", DEFAULT_MESSAGE_LIMIT))
+
+    if account:
+        # Search in specific account only
+        acct_escaped = escape(account)
+        script = f"""
+        tell application "Mail"
+            set acct to account "{acct_escaped}"
+            set output to ""
+            set totalFound to 0
+            repeat with mb in (every mailbox of acct)
+                if totalFound >= {limit} then exit repeat
+                set mbName to name of mb
+                set flaggedMsgs to (every message of mb whose flagged status is true)
+                repeat with m in flaggedMsgs
+                    if totalFound >= {limit} then exit repeat
+                    set output to output & (id of m) & "{FIELD_SEPARATOR}" & (subject of m) & "{FIELD_SEPARATOR}" & (sender of m) & "{FIELD_SEPARATOR}" & (date received of m) & "{FIELD_SEPARATOR}" & mbName & "{FIELD_SEPARATOR}" & "{acct_escaped}" & linefeed
+                    set totalFound to totalFound + 1
+                end repeat
+            end repeat
+            return output
+        end tell
+        """
+    else:
+        # Search across all accounts
+        script = f"""
+        tell application "Mail"
+            set output to ""
+            set totalFound to 0
+            repeat with acct in (every account)
+                if totalFound >= {limit} then exit repeat
+                set acctName to name of acct
+                repeat with mb in (every mailbox of acct)
+                    if totalFound >= {limit} then exit repeat
+                    set mbName to name of mb
+                    set flaggedMsgs to (every message of mb whose flagged status is true)
+                    repeat with m in flaggedMsgs
+                        if totalFound >= {limit} then exit repeat
+                        set output to output & (id of m) & "{FIELD_SEPARATOR}" & (subject of m) & "{FIELD_SEPARATOR}" & (sender of m) & "{FIELD_SEPARATOR}" & (date received of m) & "{FIELD_SEPARATOR}" & mbName & "{FIELD_SEPARATOR}" & acctName & linefeed
+                        set totalFound to totalFound + 1
+                    end repeat
+                end repeat
+            end repeat
+            return output
+        end tell
+        """
+
+    result = run(script, timeout=APPLESCRIPT_TIMEOUT_LONG)
+
+    if not result.strip():
+        scope = f" in account '{account}'" if account else " across all accounts"
+        format_output(args, f"No flagged messages found{scope}.",
+                      json_data={"flagged_messages": []})
+        return
+
+    # Build JSON data
+    messages = []
+    for line in result.strip().split("\n"):
+        if not line.strip():
+            continue
+        msg = parse_message_line(line, ["id", "subject", "sender", "date", "mailbox", "account"], FIELD_SEPARATOR)
+        if msg is not None:
+            messages.append(msg)
+
+    save_message_aliases([m["id"] for m in messages])
+    for i, m in enumerate(messages, 1):
+        m["alias"] = i
+
+    # Build text output
+    scope = f" in account '{account}'" if account else " across all accounts"
+    text = f"Flagged messages{scope} (showing up to {limit}):"
+    for m in messages:
+        text += f"\n- [{m['alias']}] {truncate(m['subject'], 60)}"
+        text += f"\n  From: {m['sender']}"
+        text += f"\n  Date: {m['date']}"
+        text += f"\n  Location: {m['mailbox']} [{m['account']}]"
+    format_output(args, text, json_data=messages)
+
+
+# ---------------------------------------------------------------------------
+# Registration
+# ---------------------------------------------------------------------------
+
+def register(subparsers) -> None:
+    """Register analytics mail subcommands."""
+    p = subparsers.add_parser("top-senders", help="Most frequent senders")
+    p.add_argument("--days", type=int, default=30, help="Look back N days (default: 30)")
+    p.add_argument("--limit", type=int, default=10, help="Number of senders to show")
+    p.add_argument("--json", action="store_true", help="Output as JSON")
+    p.set_defaults(func=cmd_top_senders)
+
+    p = subparsers.add_parser("digest", help="Grouped unread summary")
+    p.add_argument("--json", action="store_true", help="Output as JSON")
+    p.set_defaults(func=cmd_digest)
+
+    p = subparsers.add_parser("stats", help="Message count and unread count for a mailbox")
+    p.add_argument("mailbox", nargs="?", default=None, help="Mailbox name (default: INBOX)")
+    p.add_argument("-a", "--account", help="Mail account name")
+    p.add_argument("--all", action="store_true", help="Show account-wide stats across all mailboxes")
+    p.add_argument("--json", action="store_true", help="Output as JSON")
+    p.set_defaults(func=cmd_stats)
+
+    p = subparsers.add_parser("show-flagged", help="List all flagged messages")
+    p.add_argument("-a", "--account", help="Filter by account name")
+    p.add_argument("--limit", type=int, default=DEFAULT_MESSAGE_LIMIT, help="Maximum messages to show")
+    p.add_argument("--json", action="store_true", help="Output as JSON")
+    p.set_defaults(func=cmd_show_flagged)

mxctl/commands/mail/attachments.py

@@ -0,0 +1,156 @@
+"""Attachment commands: attachments (list), save-attachment."""
+
+import os
+
+from mxctl.util.applescript import escape, run, sanitize_path, validate_msg_id
+from mxctl.util.applescript_templates import list_attachments
+from mxctl.util.formatting import die, format_output, truncate
+from mxctl.util.mail_helpers import resolve_message_context
+
+
+def cmd_attachments(args) -> None:
+    """List attachments on a message."""
+    account, mailbox, acct_escaped, mb_escaped = resolve_message_context(args)
+    message_id = validate_msg_id(args.id)
+
+    script = list_attachments(f'"{acct_escaped}"', f'"{mb_escaped}"', message_id)
+
+    result = run(script)
+    lines = result.strip().split("\n")
+
+    if len(lines) <= 1:
+        subject = lines[0] if lines else "Unknown"
+        format_output(
+            args,
+            f"No attachments in message '{truncate(subject, 50)}'.",
+            json_data={"subject": subject, "attachments": []}
+        )
+        return
+
+    subject = lines[0]
+    att_list = [a for a in lines[1:] if a.strip()]
+
+    text = f"Attachments in '{truncate(subject, 50)}':"
+    for i, att in enumerate(att_list, 1):
+        text += f"\n  {i}. {att}"
+    format_output(args, text, json_data={"subject": subject, "attachments": att_list})
+
+
+def cmd_save_attachment(args) -> None:
+    """Save an attachment from a message to disk."""
+    account, mailbox, acct_escaped, mb_escaped = resolve_message_context(args)
+    message_id = validate_msg_id(args.id)
+    attachment = args.attachment
+    output_dir = sanitize_path(getattr(args, "output_dir", "~/Downloads"))
+
+    # Ensure output directory exists
+    if not os.path.isdir(output_dir):
+        die(f"Output directory does not exist: {output_dir}")
+
+    # First, get the list of attachments to resolve index vs name
+    list_script = list_attachments(f'"{acct_escaped}"', f'"{mb_escaped}"', message_id)
+
+    result = run(list_script)
+    lines = result.strip().split("\n")
+
+    if len(lines) <= 1:
+        subject = lines[0] if lines else "Unknown"
+        die(f"No attachments found in message '{truncate(subject, 50)}'.")
+
+    subject = lines[0]
+    att_list = [a for a in lines[1:] if a.strip()]
+
+    # Resolve attachment name (could be index or name)
+    att_name = None
+    if attachment.isdigit():
+        # Index-based (1-indexed)
+        idx = int(attachment) - 1
+        if 0 <= idx < len(att_list):
+            att_name = att_list[idx]
+        else:
+            die(f"Attachment index {attachment} out of range (1-{len(att_list)}).")
+    else:
+        # Name-based (exact match or prefix match)
+        exact_matches = [a for a in att_list if a == attachment]
+        if exact_matches:
+            att_name = exact_matches[0]
+        else:
+            # Try prefix match
+            prefix_matches = [a for a in att_list if a.startswith(attachment)]
+            if len(prefix_matches) == 1:
+                att_name = prefix_matches[0]
+            elif len(prefix_matches) > 1:
+                die(f"Ambiguous attachment name '{attachment}'. Matches: {', '.join(prefix_matches)}")
+            else:
+                die(f"Attachment '{attachment}' not found. Available: {', '.join(att_list)}")
+
+    # Build save path
+    save_path = os.path.join(output_dir, att_name)
+
+    # Guard against path traversal (e.g. att_name = "../../.ssh/authorized_keys")
+    real_save = os.path.realpath(os.path.abspath(save_path))
+    real_base = os.path.realpath(os.path.abspath(output_dir))
+    if not real_save.startswith(real_base + os.sep) and real_save != real_base:
+        die("Unsafe attachment filename: path traversal detected.")
+
+    save_path_posix = save_path  # Already absolute from sanitize_path + join
+
+    # Escape for AppleScript
+    att_name_escaped = escape(att_name)
+    save_path_posix_escaped = escape(save_path_posix)
+
+    # AppleScript to save the attachment
+    save_script = f"""
+    tell application "Mail"
+        set mb to mailbox "{mb_escaped}" of account "{acct_escaped}"
+        set theMsg to first message of mb whose id is {message_id}
+        repeat with att in (mail attachments of theMsg)
+            if name of att is "{att_name_escaped}" then
+                save att in POSIX file "{save_path_posix_escaped}"
+                return "saved"
+            end if
+        end repeat
+        error "Attachment not found"
+    end tell
+    """
+
+    try:
+        run(save_script)
+    except SystemExit:
+        die(f"Failed to save attachment '{att_name}'.")
+
+    # Verify file was created
+    if not os.path.isfile(save_path):
+        die(f"Attachment save reported success but file not found: {save_path}")
+
+    format_output(
+        args,
+        f"Saved attachment '{att_name}' from message '{truncate(subject, 50)}' to:\n  {save_path}",
+        json_data={
+            "message_id": message_id,
+            "subject": subject,
+            "attachment": att_name,
+            "saved_to": save_path,
+        }
+    )
+
+
+def register(subparsers) -> None:
+    """Register attachment subcommands."""
+    # attachments (list)
+    p = subparsers.add_parser("attachments", help="List attachments on a message")
+    p.add_argument("id", type=int, help="Message ID")
+    p.add_argument("-a", "--account", help="Mail account name")
+    p.add_argument("-m", "--mailbox", help="Mailbox name (default: INBOX)")
+    p.add_argument("--json", action="store_true", help="Output as JSON")
+    p.set_defaults(func=cmd_attachments)
+
+    # save-attachment
+    p = subparsers.add_parser("save-attachment", help="Save an attachment from a message")
+    p.add_argument("id", type=int, help="Message ID")
+    p.add_argument("attachment", help="Attachment name or index (1-based)")
+    p.add_argument("-a", "--account", help="Mail account name")
+    p.add_argument("-m", "--mailbox", help="Mailbox name (default: INBOX)")
+    p.add_argument("--output-dir", help="Output directory (default: ~/Downloads)")
+    p.add_argument("--json", action="store_true", help="Output as JSON")
+    p.set_defaults(func=cmd_save_attachment)