mxctl 0.3.0__py3-none-any.whl

mxctl/config.py

@@ -0,0 +1,227 @@
+"""Configuration management for mxctl.
+
+Three-tier account resolution (most specific wins):
+1. Explicit --account flag
+2. Default in ~/.config/mxctl/config.json -> {"mail": {"default_account": "iCloud"}}
+3. Last-used account saved in ~/.config/mxctl/state.json -> {"mail": {"last_account": "iCloud"}}
+
+Migration note: Backward compatibility is maintained. Config lookups check the new
+namespaced format first (e.g., config["mail"]["default_account"]), then fall back
+to the legacy flat format (config["default_account"]) if the namespace key is missing.
+This allows existing configs to continue working without modification.
+"""
+
+from __future__ import annotations
+
+import fcntl
+import json
+import os
+import shutil
+import time
+from contextlib import contextmanager
+
+from mxctl.util.formatting import die
+
+CONFIG_DIR = os.path.expanduser("~/.config/mxctl")
+_LEGACY_CONFIG_DIR = os.path.expanduser("~/.config/my")
+CONFIG_FILE = os.path.join(CONFIG_DIR, "config.json")
+STATE_FILE = os.path.join(CONFIG_DIR, "state.json")
+TEMPLATES_FILE = os.path.join(CONFIG_DIR, "mail-templates.json")
+UNDO_LOG_FILE = os.path.join(CONFIG_DIR, "mail-undo.json")
+
+DEFAULT_MESSAGE_LIMIT = 25
+MAX_MESSAGE_LIMIT = 100
+DEFAULT_BODY_LENGTH = 10000
+DEFAULT_MAILBOX = "INBOX"
+
+# Caps for various operations
+MAX_MESSAGES_BATCH = 500
+DEFAULT_DIGEST_LIMIT = 50
+DEFAULT_TOP_SENDERS_LIMIT = 10
+MAX_EXPORT_BULK_LIMIT = 100
+
+# AppleScript timeout values (seconds)
+APPLESCRIPT_TIMEOUT_SHORT = 15
+APPLESCRIPT_TIMEOUT_DEFAULT = 30
+APPLESCRIPT_TIMEOUT_LONG = 60
+APPLESCRIPT_TIMEOUT_BATCH = 120
+
+# Data separators for AppleScript field/record parsing
+FIELD_SEPARATOR = "\x1F"
+RECORD_SEPARATOR = "\x1eEND\x1e"
+
+# Common patterns for identifying no-reply / automated senders
+NOREPLY_PATTERNS = [
+    "noreply", "no-reply", "notifications", "mailer-daemon", "donotreply",
+    "updates@", "news@", "info@", "support@", "billing@",
+]
+
+_migrated: bool = False
+
+
+def _migrate_legacy_config() -> None:
+    """One-time migration from ~/.config/my/ to ~/.config/mxctl/."""
+    global _migrated
+    if _migrated:
+        return
+    _migrated = True
+
+    if os.path.isdir(CONFIG_DIR):
+        return  # Already migrated or fresh install
+    if not os.path.isdir(_LEGACY_CONFIG_DIR):
+        return  # No legacy config to migrate
+
+    import sys
+    shutil.copytree(_LEGACY_CONFIG_DIR, CONFIG_DIR)
+    print(
+        f"Migrated config from {_LEGACY_CONFIG_DIR} to {CONFIG_DIR}",
+        file=sys.stderr,
+    )
+
+
+def _ensure_dir() -> None:
+    _migrate_legacy_config()
+    os.makedirs(CONFIG_DIR, exist_ok=True)
+
+
+@contextmanager
+def file_lock(path: str):
+    """Context manager for file-based locking with retry."""
+    lock_path = path + ".lock"
+    max_retries = 10
+    retry_delay = 0.05  # 50ms
+
+    os.makedirs(os.path.dirname(lock_path), exist_ok=True)
+    for attempt in range(max_retries):
+        try:
+            with open(lock_path, "w") as lock_file:
+                fcntl.flock(lock_file.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+                try:
+                    yield lock_file
+                finally:
+                    fcntl.flock(lock_file.fileno(), fcntl.LOCK_UN)
+                    try:
+                        os.unlink(lock_path)
+                    except OSError:
+                        pass
+            break
+        except BlockingIOError:
+            if attempt < max_retries - 1:
+                time.sleep(retry_delay)
+            else:
+                die(f"Could not acquire file lock for {path} after {max_retries} attempts. Another process may be holding it.")
+
+
+def _load_json(path: str) -> dict:
+    _migrate_legacy_config()
+    if os.path.isfile(path):
+        try:
+            with file_lock(path), open(path) as f:
+                content = f.read().strip()
+                if not content:  # Handle empty/truncated files
+                    return {}
+                return json.loads(content)
+        except json.JSONDecodeError:
+            import sys
+            print(f"Warning: {path} contains invalid JSON. Using defaults.", file=sys.stderr)
+            return {}
+        except OSError:
+            return {}
+    return {}
+
+
+_SENSITIVE_FILES = {CONFIG_FILE, STATE_FILE, UNDO_LOG_FILE, TEMPLATES_FILE}
+
+
+def _save_json(path: str, data: dict) -> None:
+    _ensure_dir()
+    with file_lock(path):
+        with open(path, "w") as f:
+            json.dump(data, f, indent=2)
+        if path in _SENSITIVE_FILES:
+            os.chmod(path, 0o600)
+
+
+_config_warned: bool = False
+
+
+def get_config(required: bool = False, warn: bool = True) -> dict:
+    global _config_warned
+    if not os.path.isfile(CONFIG_FILE):
+        _migrate_legacy_config()
+    if not os.path.isfile(CONFIG_FILE):
+        if required:
+            die("No config found. Run `mxctl init` to set up your default account.")
+        if warn and not _config_warned:
+            import sys
+            print(
+                "No config found. Run `mxctl init` to set up your default account.",
+                file=sys.stderr,
+            )
+            _config_warned = True
+    return _load_json(CONFIG_FILE)
+
+
+def get_state() -> dict:
+    return _load_json(STATE_FILE)
+
+
+def save_message_aliases(aliases: list[int]) -> None:
+    """Save ordered list of message IDs as session aliases to state."""
+    state = get_state()
+    state.setdefault("mail", {})["aliases"] = {
+        str(i + 1): mid for i, mid in enumerate(aliases)
+    }
+    _save_json(STATE_FILE, state)
+
+
+def resolve_alias(value) -> int | None:
+    """If value matches a saved alias number, resolve to real message ID."""
+    try:
+        n = int(value)
+    except (TypeError, ValueError):
+        return None
+    if n <= 0:
+        return None
+    state = get_state()
+    aliases = state.get("mail", {}).get("aliases", {})
+    real_id = aliases.get(str(n))
+    if real_id is not None:
+        return int(real_id)
+    return None
+
+
+def save_last_account(account: str) -> None:
+    state = get_state()
+    if "mail" not in state:
+        state["mail"] = {}
+    state["mail"]["last_account"] = account
+    _save_json(STATE_FILE, state)
+
+
+def resolve_account(explicit: str | None) -> str | None:
+    """Resolve account using three-tier strategy. Returns None if nothing set."""
+    if explicit:
+        save_last_account(explicit)
+        return explicit
+
+    cfg = get_config(required=False, warn=False)
+    # Check namespaced key first, fall back to legacy flat key
+    default_account = cfg.get("mail", {}).get("default_account") or cfg.get("default_account")
+    if default_account:
+        return default_account
+
+    state = get_state()
+    # Check namespaced key first, fall back to legacy flat key
+    return state.get("mail", {}).get("last_account") or state.get("last_account")
+
+
+def validate_limit(limit: int) -> int:
+    """Clamp limit to [1, MAX_MESSAGE_LIMIT]."""
+    return max(1, min(limit, MAX_MESSAGE_LIMIT))
+
+
+def get_gmail_accounts() -> list[str]:
+    """Return list of account names configured as Gmail accounts."""
+    cfg = get_config(required=False, warn=False)
+    return cfg.get("mail", {}).get("gmail_accounts", [])

mxctl/main.py

@@ -0,0 +1,89 @@
+"""Top-level argparse router for mxctl."""
+
+import argparse
+import sys
+
+from mxctl import __version__
+from mxctl.commands.mail.accounts import register as register_accounts
+from mxctl.commands.mail.actions import register as register_actions
+from mxctl.commands.mail.ai import register as register_ai
+from mxctl.commands.mail.analytics import register as register_analytics
+from mxctl.commands.mail.attachments import register as register_attachments
+from mxctl.commands.mail.batch import register as register_batch
+from mxctl.commands.mail.compose import register as register_compose
+from mxctl.commands.mail.composite import register as register_composite
+from mxctl.commands.mail.inbox_tools import register as register_inbox_tools
+from mxctl.commands.mail.manage import register as register_manage
+from mxctl.commands.mail.messages import register as register_messages
+from mxctl.commands.mail.setup import register as register_setup
+from mxctl.commands.mail.system import register as register_system
+from mxctl.commands.mail.templates import register as register_templates
+from mxctl.commands.mail.todoist_integration import register as register_todoist
+from mxctl.commands.mail.undo import register as register_undo
+
+_GROUPED_HELP = """\
+Apple Mail from your terminal.
+
+Commands by category:
+
+  Setup:        init, check, accounts, mailboxes
+  Reading:      inbox, count, list, read, search, thread, context, headers
+  Actions:      mark-read, mark-unread, flag, unflag, move, delete
+                junk, not-junk, unsubscribe, open, rules
+  Compose:      draft, reply, forward, templates
+  Manage:       create-mailbox, delete-mailbox, empty-trash
+  Batch:        batch-read, batch-flag, batch-move, batch-delete, undo
+  AI & Analytics: summary, triage, find-related, digest, top-senders,
+                show-flagged, weekly-review, process-inbox,
+                clean-newsletters, stats
+  Export:       export, attachments, save-attachment, to-todoist
+
+Run `mxctl <command> --help` for details on any command.
+"""
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="mxctl",
+        description=_GROUPED_HELP,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"mxctl {__version__}",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    register_accounts(subparsers)
+    register_messages(subparsers)
+    register_actions(subparsers)
+    register_compose(subparsers)
+    register_attachments(subparsers)
+    register_manage(subparsers)
+    register_batch(subparsers)
+    register_analytics(subparsers)
+    register_system(subparsers)
+    register_composite(subparsers)
+    register_ai(subparsers)
+    register_todoist(subparsers)
+    register_inbox_tools(subparsers)
+    register_templates(subparsers)
+    register_undo(subparsers)
+    register_setup(subparsers)
+
+    args = parser.parse_args()
+
+    if args.command is None:
+        parser.print_help()
+        sys.exit(0)
+
+    # Dispatch to the handler set by set_defaults(func=...)
+    try:
+        if hasattr(args, "func"):
+            args.func(args)
+        else:
+            parser.parse_args([args.command, "--help"])
+    except KeyboardInterrupt:
+        print("\nCancelled.", file=sys.stderr)
+        sys.exit(130)

mxctl/util/applescript.py

@@ -0,0 +1,139 @@
+"""AppleScript execution helpers."""
+
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+import sys
+
+from mxctl.config import APPLESCRIPT_TIMEOUT_DEFAULT, STATE_FILE
+
+_automation_warned: bool = False
+
+
+def _warn_automation_once() -> None:
+    """Print a one-time heads-up about macOS Automation permission if needed."""
+    global _automation_warned
+    if _automation_warned:
+        return
+
+    # Check if we've already shown the prompt in a previous session
+    from mxctl.config import _save_json, get_state
+
+    state = get_state()
+    if state.get("automation_prompted"):
+        _automation_warned = True
+        return
+
+    # Check terminal app name for a friendlier message
+    terminal_app = os.environ.get("TERM_PROGRAM", "your terminal app")
+    if terminal_app == "iTerm.app":
+        terminal_app = "iTerm"
+    elif terminal_app == "Apple_Terminal":
+        terminal_app = "Terminal"
+
+    print(
+        "Note: macOS will ask for Automation permission to control Mail.app. "
+        "If prompted, click Allow.",
+        file=sys.stderr,
+    )
+    print(
+        f"  If you see 'not authorized': System Settings → Privacy & Security → "
+        f"Automation → {terminal_app} → enable Mail.",
+        file=sys.stderr,
+    )
+
+    # Mark as warned for this session and persist to state
+    _automation_warned = True
+    state["automation_prompted"] = True
+    _save_json(STATE_FILE, state)
+
+
+def validate_msg_id(value) -> int:
+    """Validate that value is a positive integer suitable for use as a message ID.
+
+    Supports short session aliases: if value matches a saved alias (e.g. "1"),
+    resolves to the real message ID from the most recent listing command.
+
+    Raises SystemExit via die() if the value is not a positive integer.
+    Returns the integer value on success.
+    """
+    from mxctl.config import resolve_alias
+    from mxctl.util.formatting import die
+
+    # Reject floats explicitly — int(1.5) == 1 without error, which is misleading
+    if isinstance(value, float):
+        die(f"Invalid message ID '{value}': must be a positive integer.")
+
+    # Try alias resolution first
+    resolved = resolve_alias(value)
+    if resolved is not None:
+        return resolved
+
+    # Fall through to real ID validation
+    try:
+        int_val = int(value)
+    except (TypeError, ValueError):
+        die(f"Invalid message ID '{value}': must be a positive integer.")
+    if int_val <= 0:
+        die(f"Invalid message ID '{value}': must be a positive integer.")
+    return int_val
+
+
+def escape(s: str | None) -> str:
+    """Escape a string for safe use in AppleScript."""
+    if s is None:
+        return ""
+    s = str(s).replace("\\", "\\\\")
+    s = s.replace('"', '\\"')
+    s = s.replace("\n", "\\n")
+    s = s.replace("\r", "\\r")
+    s = re.sub(r'[\x00-\x1f]', '', s)
+    return s
+
+
+def sanitize_path(path: str) -> str:
+    """Expand and resolve a file path."""
+    return os.path.abspath(os.path.expanduser(path))
+
+
+def run(script: str, timeout: int = APPLESCRIPT_TIMEOUT_DEFAULT) -> str:
+    """Execute AppleScript and return stdout. Exits on error."""
+    _warn_automation_once()
+    try:
+        result = subprocess.run(
+            ["osascript", "-e", script],
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+    except FileNotFoundError:
+        print("Error: osascript not found. This tool requires macOS.", file=sys.stderr)
+        sys.exit(1)
+    except subprocess.TimeoutExpired:
+        print(
+            "Error: Mail operation timed out. Try reducing --limit or narrowing the date range.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    if result.returncode != 0:
+        err = result.stderr.strip()
+        err_lower = err.lower().replace("\u2018", "'").replace("\u2019", "'")
+        if "not authorized" in err_lower:
+            msg = "Mail access denied. Grant access in System Settings > Privacy & Security > Automation."
+        elif "application isn't running" in err_lower:
+            msg = "Mail.app failed to launch. Try opening Mail.app manually and try again."
+        elif "can't get account" in err_lower:
+            msg = "Account not found. Run `mxctl accounts` to see available accounts."
+        elif "can't get mailbox" in err_lower:
+            msg = "Mailbox not found. Run `mxctl mailboxes` to see available mailboxes."
+        elif "can't get message" in err_lower:
+            msg = "Message not found — it may have been moved or deleted."
+        else:
+            msg = f"AppleScript error: {err}"
+        print(f"Error: {msg}", file=sys.stderr)
+        sys.exit(1)
+
+    return result.stdout.strip()

mxctl/util/applescript_templates.py

@@ -0,0 +1,185 @@
+"""Reusable AppleScript template functions to reduce duplication.
+
+Common patterns extracted from command modules:
+1. Inbox iteration across all accounts
+2. Message iteration with cap/limit
+3. Single message lookup by ID
+4. Field output assembly with separators
+5. All-mailboxes iteration across one or all accounts
+
+Each template function returns a complete AppleScript string.
+Use FIELD_SEPARATOR from config.py in the templates.
+"""
+
+
+def inbox_iterator_all_accounts(inner_operations: str, cap: int = 20, account: str | None = None) -> str:
+    """Generate AppleScript to iterate over INBOX in all enabled accounts (or one).
+
+    Args:
+        inner_operations: AppleScript code to execute for each INBOX message.
+                         Available variables: m (message), acct (account),
+                         acctName (account name), mbox (INBOX mailbox)
+        cap: Maximum number of messages per inbox
+        account: If provided, scope iteration to this single account name
+
+    Returns:
+        Complete AppleScript string
+
+    Example:
+        inner_ops = f'set output to output & acctName & "{FIELD_SEPARATOR}" & (id of m) & "{FIELD_SEPARATOR}" & (subject of m) & linefeed'
+        script = inbox_iterator_all_accounts(inner_ops, cap=30)
+        script = inbox_iterator_all_accounts(inner_ops, cap=30, account="iCloud")
+    """
+    if account:
+        from mxctl.util.applescript import escape
+        acct_escaped = escape(account)
+        outer_open = f'set acct to account "{acct_escaped}"\n        set acctName to name of acct'
+        outer_close = ""
+    else:
+        outer_open = (
+            "repeat with acct in (every account)\n"
+            "            if enabled of acct then\n"
+            "                set acctName to name of acct"
+        )
+        outer_close = "            end if\n        end repeat"
+
+    return f"""
+    tell application "Mail"
+        set output to ""
+        set totalFound to 0
+        {outer_open}
+            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 cap to {cap}
+                        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
+                            {inner_operations}
+                            set totalFound to totalFound + 1
+                        end repeat
+                    end try
+                    exit repeat
+                end if
+            end repeat
+        {outer_close}
+        return output
+    end tell
+    """
+
+
+def set_message_property(
+    account_var: str,
+    mailbox_var: str,
+    message_id: int,
+    property_name: str,
+    property_value: str
+) -> str:
+    """Generate AppleScript to set a message property and return subject.
+
+    Args:
+        account_var: Variable name or escaped account name
+        mailbox_var: Variable name or escaped mailbox name
+        message_id: Message ID
+        property_name: Property to set (e.g., 'read status', 'flagged status')
+        property_value: Value to set (e.g., 'true', 'false')
+
+    Returns:
+        Complete AppleScript string
+
+    Example:
+        script = set_message_property(
+            '"iCloud"', '"INBOX"', 12345,
+            'read status', 'true'
+        )
+    """
+    return f"""
+    tell application "Mail"
+        set mb to mailbox {mailbox_var} of account {account_var}
+        set theMsg to first message of mb whose id is {message_id}
+        set {property_name} of theMsg to {property_value}
+        return subject of theMsg
+    end tell
+    """
+
+
+def mailbox_iterator(inner_operations: str, account: str | None = None) -> str:
+    """Generate AppleScript to iterate over every mailbox in one or all accounts.
+
+    Unlike inbox_iterator_all_accounts (which only looks at the INBOX mailbox),
+    this iterates over ALL mailboxes of the account(s).  Useful for whole-account
+    scans such as flagged-message or attachment searches.
+
+    Args:
+        inner_operations: AppleScript code to execute inside each mailbox.
+                         Available variables: mb (mailbox), acct (account)
+        account: If provided, scope iteration to this single (already-escaped)
+                 account name string, e.g. ``escape(account)``
+
+    Returns:
+        Complete AppleScript string
+
+    Example:
+        inner_ops = (
+            'set flaggedMsgs to (every message of mb whose flagged status is true)\\n'
+            'repeat with m in flaggedMsgs\\n'
+            '    set output to output & (id of m) & linefeed\\n'
+            'end repeat'
+        )
+        script = mailbox_iterator(inner_ops, account="iCloud")
+        script = mailbox_iterator(inner_ops)  # all accounts
+    """
+    if account:
+        acct_block = f'set acct to account "{account}"\n        repeat with mb in (every mailbox of acct)\n            {inner_operations}\n        end repeat'
+    else:
+        acct_block = (
+            "repeat with acct in (every account)\n"
+            "            if enabled of acct then\n"
+            f"                repeat with mb in (every mailbox of acct)\n"
+            f"                    {inner_operations}\n"
+            "                end repeat\n"
+            "            end if\n"
+            "        end repeat"
+        )
+
+    return f"""
+    tell application "Mail"
+        set output to ""
+        {acct_block}
+        return output
+    end tell
+    """
+
+
+def list_attachments(
+    account_var: str,
+    mailbox_var: str,
+    message_id: int
+) -> str:
+    """Generate AppleScript to list message attachments.
+
+    Args:
+        account_var: Variable name or escaped account name
+        mailbox_var: Variable name or escaped mailbox name
+        message_id: Message ID
+
+    Returns:
+        Complete AppleScript string (subject on first line, attachments below)
+
+    Example:
+        script = list_attachments('"iCloud"', '"INBOX"', 12345)
+    """
+    return f"""
+    tell application "Mail"
+        set mb to mailbox {mailbox_var} of account {account_var}
+        set theMsg to first message of mb whose id is {message_id}
+        set msgSubject to subject of theMsg
+        set output to msgSubject & linefeed
+        repeat with att in (mail attachments of theMsg)
+            set attName to name of att
+            set output to output & attName & linefeed
+        end repeat
+        return output
+    end tell
+    """

mxctl/util/dates.py

@@ -0,0 +1,54 @@
+"""Date parsing and conversion helpers."""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+
+from mxctl.util.formatting import die
+
+
+def parse_date(date_str: str) -> datetime:
+    """Parse YYYY-MM-DD string."""
+    try:
+        return datetime.strptime(date_str, "%Y-%m-%d")
+    except ValueError:
+        die(f"Invalid date format: '{date_str}'. Use YYYY-MM-DD (e.g. 2026-02-14).")
+
+
+def to_applescript_date(dt: datetime) -> str:
+    """Convert datetime to AppleScript date string (e.g. 'January 15, 2026')."""
+    return dt.strftime("%B %d, %Y")
+
+
+def days_ago(n: int) -> str:
+    """Return YYYY-MM-DD for N days ago."""
+    return (datetime.now() - timedelta(days=n)).strftime("%Y-%m-%d")
+
+
+def today() -> str:
+    """Return today as YYYY-MM-DD."""
+    return datetime.now().strftime("%Y-%m-%d")
+
+
+def parse_applescript_date(date_str: str) -> str:
+    """Parse AppleScript date to ISO 8601 format.
+
+    Converts dates like:
+    - "Tuesday, January 14, 2026 at 2:30:00 PM" → "2026-01-14T14:30:00"
+    - "January 14, 2026 at 2:30:00 PM" → "2026-01-14T14:30:00"
+
+    Returns original string if parsing fails (don't crash).
+    """
+    # Try with weekday first
+    for fmt in [
+        "%A, %B %d, %Y at %I:%M:%S %p",  # With weekday
+        "%B %d, %Y at %I:%M:%S %p",  # Without weekday
+    ]:
+        try:
+            dt = datetime.strptime(date_str, fmt)
+            return dt.strftime("%Y-%m-%dT%H:%M:%S")
+        except ValueError:
+            continue
+
+    # Return original if parsing fails
+    return date_str