imapsynchronizer.py

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
IMAP Synchronizer — interactive IMAP migration toolkit.

Cross-platform (Windows / macOS / Linux) tool to inspect, migrate and
verify IMAP mailboxes. Runs an interactive, colorized menu:

  1. List folders and message counts of an account (exportable to TXT).
  2. Copy messages from a source account into a destination account,
     under _IMAP-Synchronizer/<user>_<host>/..., resumable and duplicate-safe.
  3. Compare two accounts folder-by-folder / message-by-message.

Only third-party dependency is 'rich', which is installed automatically
on first run. Everything else is the Python standard library.

Originally based on imapcopy (c) 2013 Christoph Heer (BSD license);
rewritten as an interactive tool.
"""

import sys

MIN_PYTHON = (3, 8)
if sys.version_info < MIN_PYTHON:
    sys.stderr.write(
        "IMAP Synchronizer requires Python %d.%d or later (you are running %s).\n"
        % (MIN_PYTHON[0], MIN_PYTHON[1], sys.version.split()[0])
    )
    sys.exit(1)


def _ensure_dependencies():
    """Install missing third-party packages (rich) on first run."""
    try:
        import rich  # noqa: F401
        return
    except ImportError:
        pass

    import platform
    import subprocess
    import importlib

    print("First run: installing required package 'rich' ...")

    try:
        import pip  # noqa: F401
    except ImportError:
        subprocess.call([sys.executable, "-m", "ensurepip", "--upgrade"])

    commands = [
        [sys.executable, "-m", "pip", "install", "--disable-pip-version-check", "rich"],
        [sys.executable, "-m", "pip", "install", "--user",
         "--disable-pip-version-check", "rich"],
        # Debian 12+ / Ubuntu 23.04+ mark the system Python as
        # "externally managed" (PEP 668) and refuse both commands above;
        # a per-user install with this override is the standard workaround.
        [sys.executable, "-m", "pip", "install", "--user",
         "--break-system-packages", "--disable-pip-version-check", "rich"],
    ]
    for cmd in commands:
        if subprocess.call(cmd) == 0:
            importlib.invalidate_caches()
            try:
                import rich  # noqa: F401
                print("Dependency 'rich' installed successfully.\n")
                return
            except ImportError:
                continue

    system = platform.system()
    print("\nCould not install 'rich' automatically. Please install it manually:")
    if system == "Darwin":
        print("    brew install python3        (if Python came from Homebrew)")
        print("    python3 -m pip install rich")
    elif system == "Windows":
        print("    python -m pip install rich")
    else:
        print("    sudo apt install python3-rich      (Debian / Ubuntu)")
        print("    sudo dnf install python3-rich      (Fedora)")
        print("    python3 -m pip install --user rich (other distributions)")
    sys.exit(1)


_ensure_dependencies()

import os  # noqa: E402
import re  # noqa: E402
import csv  # noqa: E402
import ssl  # noqa: E402
import json  # noqa: E402
import base64  # noqa: E402
import socket  # noqa: E402
import hashlib  # noqa: E402
import imaplib  # noqa: E402
import logging  # noqa: E402
from pathlib import Path  # noqa: E402
from datetime import datetime, timedelta  # noqa: E402
from collections import Counter  # noqa: E402
from dataclasses import dataclass, field  # noqa: E402
from email.parser import BytesHeaderParser  # noqa: E402
from email.message import EmailMessage  # noqa: E402
from email.utils import formatdate, make_msgid  # noqa: E402
from html import escape as html_escape  # noqa: E402

from rich import box  # noqa: E402
from rich.markup import escape as rich_escape  # noqa: E402
from rich.panel import Panel  # noqa: E402
from rich.table import Table  # noqa: E402
from rich.console import Console  # noqa: E402
from rich.prompt import Prompt, IntPrompt, Confirm  # noqa: E402
from rich.progress import (  # noqa: E402
    Progress, SpinnerColumn, BarColumn, TextColumn,
    TaskProgressColumn, TimeElapsedColumn,
)

APP_NAME = "IMAP Synchronizer"
APP_VERSION = "2.1"
APP_OWNER = "function0xMarki"
APP_REPO_URL = "https://github.com/function0xMarki/IMAP-Synchronizer"
MIGRATION_ROOT = "_IMAP-Synchronizer"
# Sandbox roots used by older versions — still excluded when the source and
# destination are the same account, so re-runs never copy them into themselves.
LEGACY_MIGRATION_ROOTS = ("_IMAP_SYNC",)
SCRIPT_DIR = Path(__file__).resolve().parent
PROFILES_FILE = SCRIPT_DIR / "imapsynchronizer_profiles.json"
REPORTS_DIR = SCRIPT_DIR / "reports"
LOGS_DIR = SCRIPT_DIR / "logs"


def ensure_reports_dir() -> Path:
    """All exported TXT reports go into reports/ ."""
    REPORTS_DIR.mkdir(exist_ok=True)
    return REPORTS_DIR


def ensure_logs_dir() -> Path:
    """Session error logs and detailed migration logs go into logs/ ."""
    LOGS_DIR.mkdir(exist_ok=True)
    return LOGS_DIR

# Large mailboxes produce long untagged responses; the imaplib default
# (1 MB) can be exceeded by FETCH responses with big header sets.
imaplib._MAXLINE = 10 * 1024 * 1024
socket.setdefaulttimeout(60)

# Legacy Windows consoles default to a codepage (cp1252/cp850) that cannot
# represent the box-drawing characters used in folder trees.
if sys.platform == "win32":
    os.system("")  # enable VT / ANSI processing in the console
    for _stream in (sys.stdout, sys.stderr):
        try:
            _stream.reconfigure(encoding="utf-8", errors="replace")
        except (AttributeError, OSError):
            pass

console = Console(highlight=False)
log = logging.getLogger("imapsynchronizer")
log.setLevel(logging.DEBUG)

from rich.logging import RichHandler  # noqa: E402

_console_log = RichHandler(console=console, show_time=False, show_path=False)
_console_log.setLevel(logging.WARNING)
log.addHandler(_console_log)

_error_log_handler = None


def setup_error_log():
    """Open one session error log per program start, under logs/.

    Records every WARNING and ERROR of the whole session — connection
    failures, per-message/per-folder errors, and transient errors that
    were retried and resolved — so an admin can debug afterwards."""
    global _error_log_handler
    try:
        path = (ensure_logs_dir()
                / f"imapsynchronizer_{datetime.now():%Y%m%d_%H%M%S}.log")
        with open(path, "w", encoding="utf-8") as fh:
            fh.write(
                f"# {APP_NAME} v{APP_VERSION} — session error log\n"
                f"# Started : {datetime.now():%Y-%m-%d %H:%M:%S}\n"
                f"# Python  : {sys.version.split()[0]} on {sys.platform}\n"
                f"# Mode    : {' '.join(sys.argv[1:]) or 'interactive menu'}\n"
                "# Contains: warnings and errors, including transient "
                "errors that were retried and resolved\n")
        handler = logging.FileHandler(path, mode="a", encoding="utf-8")
    except OSError as exc:
        console.print(f"[yellow]Could not create the session error log "
                      f"({exc}) — continuing without it.[/yellow]")
        return None
    handler.setLevel(logging.WARNING)
    handler.setFormatter(
        logging.Formatter("%(asctime)s %(levelname)-7s %(message)s"))
    log.addHandler(handler)
    _error_log_handler = handler
    return path


def close_error_log(exit_code: int):
    global _error_log_handler
    if _error_log_handler is None:
        return
    path = _error_log_handler.baseFilename
    log.removeHandler(_error_log_handler)
    _error_log_handler.close()
    _error_log_handler = None
    try:
        with open(path, "a", encoding="utf-8") as fh:
            fh.write(f"# Ended   : {datetime.now():%Y-%m-%d %H:%M:%S} "
                     f"(exit code {exit_code})\n")
    except OSError:
        pass


# --------------------------------------------------------------------------
# IMAP modified UTF-7 (RFC 3501 section 5.1.3) folder-name codec
# --------------------------------------------------------------------------

def imap_utf7_encode(text: str) -> str:
    """Encode a folder name to IMAP modified UTF-7 (ASCII-safe)."""
    out, buf = [], []

    def flush():
        if buf:
            b64 = base64.b64encode("".join(buf).encode("utf-16-be"))
            out.append("&" + b64.decode("ascii").rstrip("=").replace("/", ",") + "-")
            buf.clear()

    for ch in text:
        if 0x20 <= ord(ch) <= 0x7E:
            flush()
            out.append("&-" if ch == "&" else ch)
        else:
            buf.append(ch)
    flush()
    return "".join(out)


def imap_utf7_decode(text: str) -> str:
    """Decode an IMAP modified UTF-7 folder name to a normal string."""
    out, i = [], 0
    while i < len(text):
        ch = text[i]
        if ch != "&":
            out.append(ch)
            i += 1
            continue
        end = text.find("-", i + 1)
        if end == -1:
            out.append(text[i:])
            break
        chunk = text[i + 1:end]
        if chunk == "":
            out.append("&")
        else:
            b64 = chunk.replace(",", "/")
            b64 += "=" * ((4 - len(b64) % 4) % 4)
            try:
                out.append(base64.b64decode(b64).decode("utf-16-be"))
            except Exception:
                out.append(text[i:end + 1])
        i = end + 1
    return "".join(out)


def quote_mailbox(raw: str) -> str:
    """Quote a mailbox name for use in an IMAP command (imaplib does not)."""
    return '"' + raw.replace("\\", "\\\\").replace('"', '\\"') + '"'


def sanitize_component(part: str, delimiter) -> str:
    """Make a folder-path component safe for the destination server."""
    part = "".join(ch for ch in part if ord(ch) >= 32)
    if delimiter:
        part = part.replace(delimiter, "_")
    part = part.strip()
    return part or "_"


def sanitize_filename(name: str) -> str:
    return re.sub(r"[^\w.@-]+", "_", name).strip("._") or "account"


def strip_surrounding_quotes(value: str) -> str:
    """Remove one pair of matching surrounding quotes, if present.

    Lets users paste passwords wrapped in quotes (to protect leading or
    trailing spaces) without the quotes becoming part of the password.
    Everything typed between them — commas, semicolons, ñ, symbols — is
    taken literally.
    """
    if len(value) >= 2 and value[0] == value[-1] and value[0] in ('"', "'"):
        return value[1:-1]
    return value


def is_ascii(text: str) -> bool:
    return all(ord(ch) < 128 for ch in text)


def normalize_host(text: str):
    """Clean a server address the way users actually paste it.

    Accepts 'imap://host', 'imaps://host/', 'host:993', stray spaces or a
    trailing slash; returns (host, port_or_None). IPv6 literals are left
    untouched."""
    host = (text or "").strip().rstrip("/")
    for prefix in ("imaps://", "imap://"):
        if host.lower().startswith(prefix):
            host = host[len(prefix):]
            break
    port = None
    if host.count(":") == 1:
        candidate, maybe_port = host.rsplit(":", 1)
        if maybe_port.isdigit():
            host, port = candidate, int(maybe_port)
    return host, port


def message_key(header_bytes: bytes) -> str:
    """Stable identity of a message: Message-ID, or a hash of its headers."""
    msg = BytesHeaderParser().parsebytes(header_bytes or b"")
    mid = (msg.get("Message-ID") or "").strip()
    if mid:
        return "mid:" + mid
    digest = hashlib.sha1(b"".join((header_bytes or b"").split())).hexdigest()
    return "hdr:" + digest


def _chunks(seq, size):
    for i in range(0, len(seq), size):
        yield seq[i:i + size]


def _flatten_response(data) -> bytes:
    parts = []
    for item in data or []:
        if isinstance(item, tuple):
            parts.extend(p for p in item if isinstance(p, bytes))
        elif isinstance(item, bytes):
            parts.append(item)
    return b" ".join(parts)


def _iter_fetch_literals(data):
    """Yield (info, literal) pairs from an imaplib FETCH response.

    Servers may place attributes (e.g. UID) before or after the literal;
    imaplib delivers the part after it as a separate bytes element, so all
    fragments of one message record are merged into a single info line.
    """
    info, literal = None, None
    for item in data or []:
        if isinstance(item, tuple) and len(item) >= 2:
            if info is not None:
                yield info, literal
            info, literal = item[0], item[1]
        elif isinstance(item, bytes) and info is not None:
            info += b" " + item
    if info is not None:
        yield info, literal


# --------------------------------------------------------------------------
# IMAP session
# --------------------------------------------------------------------------

class ImapError(Exception):
    pass


class MigrationAborted(ImapError):
    """Raised when too many consecutive messages fail — the connection is
    almost certainly dead and continuing would hang for hours on timeouts."""


# Flags every IMAP server must accept in APPEND (RFC 3501). Anything else
# (keywords like $Forwarded, Gmail labels) may be rejected by strict servers.
STANDARD_FLAGS = ("\\seen", "\\answered", "\\flagged", "\\draft", "\\deleted")


def append_flag_attempts(flags):
    """Flag sets to try for APPEND, from most to least faithful.

    Starts with the original flags; falls back to the standard subset and
    finally to no flags, so a server that rejects custom keywords still
    receives the message (losing only the keyword, which is logged)."""
    attempts = [flags]
    if flags:
        std = " ".join(t for t in flags.split() if t.lower() in STANDARD_FLAGS)
        for alt in (std or None, None):
            if alt not in attempts:
                attempts.append(alt)
    return attempts


@dataclass
class Account:
    host: str
    port: int
    user: str
    password: str = field(repr=False, default="")

    @property
    def label(self) -> str:
        return f"{self.user} @ {self.host}:{self.port}"


@dataclass
class Folder:
    raw: str                # raw (modified UTF-7) full name, as used on the wire
    name: str               # decoded, human-readable full name
    delimiter: str          # hierarchy delimiter (may be None on odd servers)
    parts: tuple            # decoded path components
    selectable: bool
    flags: str = ""         # LIST flags, e.g. "\\HasChildren \\All"

    def has_flag(self, flag: str) -> bool:
        return flag.lower() in self.flags.lower().split()


_LIST_LINE_RE = re.compile(
    r'^\((?P<flags>[^)]*)\)\s+(?:"(?P<delim>(?:\\.|[^"\\])*)"|NIL)\s+(?P<name>.*)$',
    re.DOTALL,
)
_LIST_PREFIX_RE = re.compile(
    r'^\((?P<flags>[^)]*)\)\s+(?:"(?P<delim>(?:\\.|[^"\\])*)"|NIL)\s+'
)


def _unescape_quoted(value: str) -> str:
    return value.replace('\\"', '"').replace("\\\\", "\\")


def parse_list_entry(entry):
    """Parse one imaplib LIST response entry.

    Returns (flags, delimiter, raw_name) or None if unparseable.
    Handles quoted names, unquoted names and literal continuations
    (imaplib delivers literals as (prefix, name) tuples).
    """
    if entry is None:
        return None
    if isinstance(entry, tuple):
        prefix = entry[0].decode("ascii", "replace")
        m = _LIST_PREFIX_RE.match(prefix)
        if not m:
            return None
        raw_name = entry[1].decode("ascii", "replace")
    else:
        line = entry.decode("ascii", "replace")
        if not line.strip():
            return None
        m = _LIST_LINE_RE.match(line)
        if not m:
            return None
        raw_name = m.group("name").strip()
        if raw_name.startswith('"') and raw_name.endswith('"') and len(raw_name) >= 2:
            raw_name = _unescape_quoted(raw_name[1:-1])
    flags = m.group("flags") or ""
    delim = m.group("delim")
    if delim is not None:
        delim = _unescape_quoted(delim)
    return flags, delim, raw_name


class ImapSession:
    def __init__(self, account: Account, role: str = "server"):
        self.account = account
        self.role = role
        self.conn = None
        self.delimiter = "/"
        self.allow_insecure_ssl = True
        self._selected = None            # (raw_name, readonly) currently selected
        self._known_raw = None           # set of raw folder names known to exist

    # -- connection -------------------------------------------------------

    def connect(self):
        acct = self.account
        ctx = ssl.create_default_context()
        if self.allow_insecure_ssl:
            ctx.check_hostname = False
            ctx.verify_mode = ssl.CERT_NONE

        if acct.port == 993:
            conn = imaplib.IMAP4_SSL(acct.host, acct.port, ssl_context=ctx)
        else:
            conn = imaplib.IMAP4(acct.host, acct.port)
            if "STARTTLS" in conn.capabilities:
                conn.starttls(ctx)
            else:
                log.warning("%s: connection to %s:%s is NOT encrypted",
                            self.role, acct.host, acct.port)

        # IMAP LOGIN only carries ASCII. Credentials with ñ, accents or any
        # other non-ASCII characters are sent via AUTHENTICATE PLAIN, which
        # is base64-encoded UTF-8 and accepts every character.
        if is_ascii(acct.user) and is_ascii(acct.password):
            conn.login(acct.user, acct.password)
        else:
            def _auth_plain(_challenge):
                return (b"\0" + acct.user.encode("utf-8")
                        + b"\0" + acct.password.encode("utf-8"))
            try:
                conn.authenticate("PLAIN", _auth_plain)
            except imaplib.IMAP4.error as exc:
                raise ImapError(
                    "The password/username contains non-ASCII characters and "
                    "the server rejected AUTH PLAIN (%s). Plain IMAP LOGIN "
                    "cannot transmit those characters." % exc)
        self.conn = conn
        self._detect_delimiter()

    def _detect_delimiter(self):
        typ, data = self.conn.list('""', '*')
        if typ == "OK":
            for entry in data:
                parsed = parse_list_entry(entry)
                if parsed and parsed[1]:
                    self.delimiter = parsed[1]
                    return

    def reconnect(self):
        try:
            self.conn.shutdown()
        except Exception:
            pass
        log.warning("%s: connection lost, reconnecting to %s",
                    self.role, self.account.host)
        self.connect()
        if self._selected:
            raw, readonly = self._selected
            self.select_folder(raw, readonly=readonly)

    def logout(self):
        if self.conn is None:
            return
        try:
            if self.conn.state == "SELECTED":
                self.conn.close()
            self.conn.logout()
        except Exception:
            pass
        self.conn = None

    def _retry(self, fn):
        """Run fn(); on a dropped connection, reconnect once and retry."""
        try:
            return fn()
        except (imaplib.IMAP4.abort, ssl.SSLError, OSError) as exc:
            log.warning("%s: retrying after connection error: %s", self.role, exc)
            self.reconnect()
            result = fn()
            log.warning("%s: operation succeeded after reconnect — "
                        "transient error resolved", self.role)
            return result

    # -- folders ----------------------------------------------------------

    def list_folders(self):
        typ, data = self._retry(lambda: self.conn.list())
        if typ != "OK":
            raise ImapError(f"LIST failed on {self.account.host}: "
                            f"{_flatten_response(data).decode('ascii', 'replace')}")
        folders = []
        for entry in data:
            if not entry:
                continue
            parsed = parse_list_entry(entry)
            if parsed is None:
                log.warning("%s: unparseable LIST entry skipped: %r", self.role, entry)
                continue
            flags, delim, raw = parsed
            delim = delim or self.delimiter
            name = imap_utf7_decode(raw)
            parts = tuple(name.split(delim)) if delim else (name,)
            selectable = "\\noselect" not in flags.lower()
            folders.append(Folder(raw=raw, name=name, delimiter=delim,
                                  parts=parts, selectable=selectable,
                                  flags=flags))
        folders.sort(key=lambda f: tuple(p.lower() for p in f.parts))
        self._known_raw = {f.raw for f in folders}
        return folders

    def message_count(self, folder: Folder):
        if not folder.selectable:
            return None
        typ, data = self._retry(
            lambda: self.conn.status(quote_mailbox(folder.raw), "(MESSAGES)"))
        if typ == "OK":
            m = re.search(rb"MESSAGES\s+(\d+)", _flatten_response(data))
            if m:
                return int(m.group(1))
        # Some servers refuse STATUS; fall back to EXAMINE.
        try:
            return self.select_folder(folder.raw, readonly=True)
        except ImapError:
            return None

    def select_folder(self, raw: str, readonly: bool = True) -> int:
        typ, data = self._retry(
            lambda: self.conn.select(quote_mailbox(raw), readonly=readonly))
        if typ != "OK":
            raise ImapError(
                f"Cannot open folder '{imap_utf7_decode(raw)}' on "
                f"{self.account.host}: "
                f"{_flatten_response(data).decode('ascii', 'replace')}")
        self._selected = (raw, readonly)
        try:
            return int(data[0])
        except (TypeError, ValueError, IndexError):
            return 0

    def ensure_path(self, parts) -> str:
        """Create folder path (and ancestors) on this server; return raw name."""
        if self._known_raw is None:
            self.list_folders()
        raw_parts = [imap_utf7_encode(p) for p in parts]
        raw = ""
        for i in range(1, len(raw_parts) + 1):
            raw = self.delimiter.join(raw_parts[:i])
            if raw in self._known_raw or raw.upper() == "INBOX":
                continue
            typ, data = self._retry(lambda r=raw: self.conn.create(quote_mailbox(r)))
            if typ != "OK":
                detail = _flatten_response(data).decode("ascii", "replace")
                # Tolerate only a real "already exists" answer. A plain
                # 'exist' substring is NOT enough: Dovecot's namespace
                # rejection says "nonexistent namespace", which must fail
                # here so the INBOX-prefix fallback can kick in.
                compact = detail.lower().replace(" ", "")
                if ("alreadyexists" not in compact
                        and "fileexists" not in compact):
                    raise ImapError(
                        f"Cannot create folder '{' / '.join(parts[:i])}' on "
                        f"{self.account.host}: {detail}")
            try:
                self.conn.subscribe(quote_mailbox(raw))
            except Exception:
                pass
            self._known_raw.add(raw)
        return raw

    # -- messages ---------------------------------------------------------

    def search_uids(self, raw: str, criteria=None):
        """Return the UID list of messages matching criteria (default: ALL)."""
        self.select_folder(raw, readonly=True)
        typ, data = self._retry(
            lambda: self.conn.uid("SEARCH", criteria or "ALL"))
        if typ != "OK":
            raise ImapError(f"SEARCH failed in '{imap_utf7_decode(raw)}'")
        return data[0].split() if data and data[0] else []

    def fetch_message_keys(self, raw: str, criteria=None, on_progress=None):
        """Return [(uid, key), ...] for messages matching criteria (default ALL)."""
        uids = self.search_uids(raw, criteria)
        pairs = []
        for chunk in _chunks(uids, 400):
            uidset = b",".join(chunk).decode("ascii")

            def do_fetch(us=uidset):
                return self.conn.uid(
                    "FETCH", us,
                    "(BODY.PEEK[HEADER.FIELDS (MESSAGE-ID FROM TO DATE SUBJECT)])")

            typ, fdata = self._retry(do_fetch)
            if typ != "OK":
                raise ImapError(f"FETCH failed in '{imap_utf7_decode(raw)}'")
            for info, literal in _iter_fetch_literals(fdata):
                m = re.search(rb"UID (\d+)", info)
                if not m:
                    continue
                pairs.append((m.group(1).decode("ascii"), message_key(literal)))
            if on_progress:
                on_progress(len(chunk))
        return pairs

    def fetch_full_message(self, uid: str):
        """Return (flags, internaldate, rfc822_bytes) or None."""
        def do_fetch():
            return self.conn.uid("FETCH", uid, "(FLAGS INTERNALDATE BODY.PEEK[])")

        typ, data = self._retry(do_fetch)
        if typ != "OK" or not data:
            return None
        # Use only the record that carries the message literal; servers may
        # interleave unsolicited untagged responses (flag changes seen by
        # other sessions) whose FLAGS must not be mistaken for this message's.
        meta, body = b"", None
        for info, literal in _iter_fetch_literals(data):
            if literal is not None and b"BODY[" in info.upper():
                meta, body = info, literal
        if body is None:
            return None

        flags = None
        m = re.search(rb"FLAGS \(([^)]*)\)", meta)
        if m:
            tokens = [t for t in m.group(1).decode("ascii", "replace").split()
                      if t.lower() != "\\recent"]
            if tokens:
                flags = " ".join(tokens)

        internaldate = None
        m = re.search(rb'INTERNALDATE "([^"]+)"', meta)
        if m:
            internaldate = m.group(1).decode("ascii", "replace")

        return flags, internaldate, body

    def append_message(self, raw: str, flags, internaldate, body: bytes):
        date_param = '"%s"' % internaldate if internaldate else None

        detail = ""
        for attempt, fl in enumerate(append_flag_attempts(flags)):
            def do_append(f=fl):
                return self.conn.append(quote_mailbox(raw), f, date_param, body)

            typ, data = self._retry(do_append)
            if typ == "OK":
                if attempt:
                    log.warning("%s: server refused flags %r — message stored "
                                "with %r instead",
                                imap_utf7_decode(raw), flags, fl)
                return
            detail = _flatten_response(data).decode("ascii", "replace")
        raise ImapError(
            f"APPEND to '{imap_utf7_decode(raw)}' failed: {detail}")


# --------------------------------------------------------------------------
# Profiles (host/port/user only — passwords are never stored)
# --------------------------------------------------------------------------

def load_profiles():
    try:
        with open(PROFILES_FILE, "r", encoding="utf-8") as fh:
            data = json.load(fh)
    except (OSError, json.JSONDecodeError):
        return []
    profiles = []
    for p in data.get("profiles", []):
        if not (isinstance(p, dict) and p.get("host") and p.get("user")):
            continue
        try:
            p["port"] = int(p.get("port", 993))
        except (TypeError, ValueError):
            p["port"] = 993          # hand-edited file with a broken port
        profiles.append(p)
    return profiles


def save_profiles(profiles):
    try:
        with open(PROFILES_FILE, "w", encoding="utf-8") as fh:
            json.dump({"profiles": profiles}, fh, indent=2, ensure_ascii=False)
    except OSError as exc:
        console.print(f"[yellow]Could not save profiles: {exc}[/yellow]")


def maybe_save_profile(account: Account):
    profiles = load_profiles()
    for p in profiles:
        if (p["host"], int(p.get("port", 993)), p["user"]) == \
                (account.host, account.port, account.user):
            return
    if Confirm.ask("  Save this connection as a profile "
                   "(the password is [bold]never[/bold] stored)?", default=True):
        name = Prompt.ask("  Profile name", default=account.user)
        profiles.append({"name": name, "host": account.host,
                         "port": account.port, "user": account.user})
        save_profiles(profiles)
        console.print(f"  [green]Profile '{name}' saved.[/green]")


# --------------------------------------------------------------------------
# Interactive prompts
# --------------------------------------------------------------------------

def prompt_account(title: str) -> Account:
    console.print()
    console.rule(f"[bold cyan]{title}[/bold cyan]", style="cyan")

    profiles = load_profiles()
    chosen = None
    if profiles:
        table = Table(box=box.SIMPLE, show_edge=False, pad_edge=False)
        table.add_column("#", style="cyan", justify="right")
        table.add_column("Profile")
        table.add_column("User")
        table.add_column("Server")
        for idx, p in enumerate(profiles, 1):
            table.add_row(str(idx), p.get("name", ""), p["user"],
                          f"{p['host']}:{p.get('port', 993)}")
        console.print(table)
        answer = Prompt.ask(
            "  Use a saved profile? Enter its number, or press Enter for a new one",
            default="")
        if answer.strip().isdigit() and 1 <= int(answer) <= len(profiles):
            chosen = profiles[int(answer) - 1]

    if chosen:
        # Normalize here too — the profiles file may be edited by hand.
        host, embedded_port = normalize_host(chosen["host"])
        port = embedded_port or int(chosen.get("port", 993))
        user = chosen["user"]
        console.print(f"  Using profile: [bold]{user}[/bold] @ {host}:{port}")
    else:
        host, embedded_port = normalize_host(
            Prompt.ask("  IMAP server (e.g. imap.example.com)"))
        if embedded_port:
            port = embedded_port
            console.print(f"  Port [bold]{port}[/bold] taken from the "
                          "server address.")
        else:
            port = IntPrompt.ask("  Port", default=993)
        user = Prompt.ask("  Username / e-mail address").strip()

    # Hidden input needs a real terminal; when stdin is piped (scripted
    # use), getpass would read from the console and hang instead.
    password = Prompt.ask(
        '  Password [dim](any characters allowed; may be wrapped in "quotes")[/dim]',
        password=sys.stdin.isatty())
    password = strip_surrounding_quotes(password)
    return Account(host=host, port=port, user=user, password=password)


def connect_session(account: Account, role: str):
    """Connect and authenticate; returns an ImapSession or None on failure."""
    session = ImapSession(account, role=role)
    session.allow_insecure_ssl = Confirm.ask(
        "  Use insecure SSL (skip certificate verification)?", default=True)
    while True:
        try:
            with console.status(f"Connecting to [bold]{account.host}:{account.port}"
                                f"[/bold] as {account.user} ..."):
                session.connect()
            console.print(f"  [green]OK[/green]  {role}: connected and "
                          f"authenticated ({account.label})")
            maybe_save_profile(account)
            return session
        except ssl.SSLCertVerificationError as exc:
            console.print(f"  [red]SSL certificate verification failed:[/red] {exc}")
            if session.allow_insecure_ssl or not Confirm.ask(
                    "  Connect anyway [bold red]without[/bold red] verifying "
                    "the certificate?", default=True):
                return None
            session.allow_insecure_ssl = True
        except (ImapError, imaplib.IMAP4.error, OSError) as exc:
            log.error("%s: connection to %s:%s as %s failed: %s",
                      role, account.host, account.port, account.user, exc)
            console.print(f"  [red]Connection to {account.host} failed:[/red] {exc}")
            return None


# --------------------------------------------------------------------------
# Folder tree rendering and reports
# --------------------------------------------------------------------------

def build_tree_lines(rows):
    """rows: iterable of (parts, count, selectable).

    Returns [(tree_label, count, selectable, parts), ...] with box-drawing
    prefixes, suitable for both console tables and plain-text export.
    """
    tree, info = {}, {}
    for parts, count, selectable in rows:
        node = tree
        for part in parts:
            node = node.setdefault(part, {})
        info[tuple(parts)] = (count, selectable)

    lines = []

    def walk(node, prefix, path):
        items = sorted(node.items(),
                       key=lambda kv: (kv[0].upper() != "INBOX", kv[0].lower()))
        for i, (name, child) in enumerate(items):
            last = i == len(items) - 1
            connector = "└── " if last else "├── "
            parts = path + (name,)
            count, selectable = info.get(parts, (None, False))
            lines.append((prefix + connector + name, count, selectable, parts))
            walk(child, prefix + ("    " if last else "│   "), parts)

    walk(tree, "", ())
    return lines


def render_tree_table(title, tree_lines, count_header="Messages"):
    table = Table(title=title, box=box.ROUNDED, title_style="bold cyan",
                  header_style="bold")
    table.add_column("Folder", overflow="fold")
    table.add_column(count_header, justify="right")
    total = 0
    n_folders = 0
    for label, count, selectable, _parts in tree_lines:
        if count is None:
            table.add_row(f"[dim]{rich_escape(label)}[/dim]", "[dim]—[/dim]")
        else:
            total += count
            n_folders += 1
            table.add_row(rich_escape(label), f"{count:,}")
    table.add_section()
    table.add_row(f"[bold]TOTAL  ({n_folders} folders)[/bold]", f"[bold]{total:,}[/bold]")
    return table, total, n_folders


def tree_lines_as_text(tree_lines):
    width = max((len(label) for label, *_ in tree_lines), default=20) + 2
    out = []
    total, n_folders = 0, 0
    for label, count, _selectable, _parts in tree_lines:
        if count is None:
            out.append(f"{label:<{width}} —")
        else:
            total += count
            n_folders += 1
            out.append(f"{label:<{width}} {count:,}")
    out.append("-" * (width + 10))
    out.append(f"{'TOTAL (' + str(n_folders) + ' folders)':<{width}} {total:,}")
    return out


def write_report(filename: str, lines) -> Path:
    """Write a report into reports/, never overwriting an earlier one.

    Report names are timestamped to the minute, so two migrations of the
    same account within a minute (typical in batch runs) would otherwise
    silently replace each other's report."""
    path = ensure_reports_dir() / filename
    stem, suffix = path.stem, path.suffix
    n = 2
    while path.exists():
        path = path.with_name(f"{stem}_{n}{suffix}")
        n += 1
    with open(path, "w", encoding="utf-8") as fh:
        fh.write("\n".join(lines) + "\n")
    return path


def report_timestamp() -> str:
    return datetime.now().strftime("%d%m%y_%H%M")


def _report_email_html(ctx, src_account, dst_account) -> str:
    """E-mail-safe HTML version of the migration report (inline styles
    only, table-based layout — renders correctly in every mail client)."""
    esc = html_escape
    ok = ctx["ok"]
    accent = "#1a7f37" if ok else "#c62828"
    verdict = "VERIFIED OK" if ok else "DIFFERENCES FOUND"

    info_html = "".join(
        f'<tr><td style="padding:4px 14px 4px 0;color:#57606a;'
        f'white-space:nowrap">{esc(k)}</td>'
        f'<td style="padding:4px 0;color:#24292f">{esc(v)}</td></tr>'
        for k, v in (("Source", src_account.label),
                     ("Destination", dst_account.label),
                     ("Copied into", ctx["copied_into"]),
                     ("Date filter", ctx["date_filter"]),
                     ("Date", ctx["stamp"]),
                     ("Duration", ctx["elapsed"])))

    heads = ("Folder", "Source", "Copied", "Existing", "Failed", "Missing")
    head_html = "".join(
        f'<th style="text-align:{"left" if h == "Folder" else "right"};'
        f'padding:8px 10px;background:#24292f;color:#ffffff;'
        f'font-size:12px">{h}</th>' for h in heads)

    def num_cell(value, bad=False):
        style = ("color:#c62828;font-weight:bold" if bad and value
                 else "color:#24292f")
        return (f'<td style="padding:6px 10px;text-align:right;'
                f'border-bottom:1px solid #eaecef;{style}">{value:,}</td>')

    body_rows = []
    for i, (name, srct, copied, already, failed, missing) in \
            enumerate(ctx["rows"]):
        body_rows.append(
            f'<tr style="background:{"#ffffff" if i % 2 == 0 else "#f6f8fa"}">'
            f'<td style="padding:6px 10px;border-bottom:1px solid #eaecef;'
            f'color:#24292f">{esc(name)}</td>'
            + num_cell(srct) + num_cell(copied) + num_cell(already)
            + num_cell(failed, True) + num_cell(missing, True) + "</tr>")
    tot = [sum(r[i] for r in ctx["rows"]) for i in range(1, 6)]
    totals_html = (
        '<tr><td style="padding:8px 10px;font-weight:bold;color:#24292f;'
        f'border-top:2px solid #24292f">TOTAL ({len(ctx["rows"])} folders)</td>'
        + "".join(f'<td style="padding:8px 10px;text-align:right;'
                  f'font-weight:bold;color:#24292f;'
                  f'border-top:2px solid #24292f">{v:,}</td>'
                  for v in tot) + "</tr>")

    errors_html = ""
    for title, items in (
            ("Folders that could not be processed", ctx["folder_errors"]),
            ("Folders copied but whose verification failed (re-run to verify)",
             ctx["verify_errors"])):
        if items:
            lis = "".join(f'<li style="margin:2px 0"><b>{esc(n)}</b>: '
                          f'{esc(e)}</li>' for n, e in items)
            errors_html += (
                '<div style="margin-top:14px;padding:10px 14px;'
                'background:#fff5f5;border:1px solid #f1b8b8;border-radius:6px">'
                f'<div style="font-weight:bold;color:#c62828;'
                f'margin-bottom:4px">{title}</div>'
                f'<ul style="margin:0;padding-left:18px;color:#24292f">'
                f'{lis}</ul></div>')

    return (
        '<html><body style="margin:0;padding:24px;background:#eef1f4">'
        '<table role="presentation" cellpadding="0" cellspacing="0" '
        'style="max-width:720px;margin:0 auto;background:#ffffff;'
        'border-radius:8px;overflow:hidden;color:#24292f;'
        'font-family:Arial,Helvetica,sans-serif">'
        f'<tr><td style="background:{accent};padding:18px 24px;'
        'color:#ffffff">'
        f'<div style="color:#ffffff;font-size:18px;font-weight:bold">'
        f'{APP_NAME} &mdash; Migration report</div>'
        f'<div style="color:#d8e8dc;font-size:13px;margin-top:2px">'
        f'{esc(ctx["stamp"])}</div></td></tr>'
        '<tr><td style="padding:20px 24px;color:#24292f">'
        f'<span style="display:inline-block;padding:4px 14px;'
        f'border-radius:12px;background:{accent};color:#ffffff;'
        f'font-size:13px;font-weight:bold">{verdict}</span>'
        f'<table cellpadding="0" cellspacing="0" '
        f'style="margin-top:14px;font-size:13px">{info_html}</table>'
        f'<table cellpadding="0" cellspacing="0" width="100%" '
        f'style="margin-top:16px;font-size:13px;border-collapse:collapse">'
        f'<tr>{head_html}</tr>{"".join(body_rows)}{totals_html}</table>'
        f'{errors_html}</td></tr>'
        '<tr><td style="padding:14px 24px;background:#f6f8fa;'
        'border-top:1px solid #eaecef;font-size:12px;color:#57606a">'
        f'{APP_NAME} v{APP_VERSION} &middot; by {APP_OWNER} &middot; '
        f'<a href="{APP_REPO_URL}" style="color:#0969da">{APP_REPO_URL}</a>'
        '</td></tr></table></body></html>')


def build_report_email(report_lines, src_account, dst_account,
                       html_ctx=None, attachment_name=None) -> bytes:
    """RFC 822 message carrying the migration report, stored in the
    destination account as a permanent record of what was done.

    Structure: plain-text body (fallback) + styled HTML alternative
    (what mail clients display) + the TXT report attached; signed with
    the program name, version, owner and repository."""
    msg = EmailMessage()
    msg["From"] = f"{APP_NAME} <no-reply@imap-synchronizer.invalid>"
    msg["To"] = dst_account.user
    msg["Subject"] = (f"Migration report: {src_account.user} -> "
                      f"{dst_account.user} ({datetime.now():%Y-%m-%d %H:%M})")
    msg["Date"] = formatdate(localtime=True)
    msg["Message-ID"] = make_msgid("report", domain="imap-synchronizer.invalid")
    signature = ["", "-- ",
                 f"{APP_NAME} v{APP_VERSION}",
                 f"by {APP_OWNER}",
                 APP_REPO_URL]
    msg.set_content("\n".join(list(report_lines) + signature))
    if html_ctx is not None:
        msg.add_alternative(
            _report_email_html(html_ctx, src_account, dst_account),
            subtype="html")
    if attachment_name:
        msg.add_attachment("\n".join(report_lines).encode("utf-8"),
                           maintype="text", subtype="plain",
                           filename=attachment_name)
    return msg.as_bytes()


def offer_export(default_name: str, lines):
    if Confirm.ask("\nExport this to a TXT file?", default=True):
        try:
            path = write_report(default_name, lines)
        except OSError as exc:
            console.print(f"[red]Could not save the report: {exc}[/red]")
            return
        console.print(f"[green]Report saved:[/green] {path}")


# --------------------------------------------------------------------------
# Action 1 — list folders and message counts
# --------------------------------------------------------------------------

def action_list_account():
    account = prompt_account("Account to inspect")
    session = connect_session(account, "Account")
    if session is None:
        return
    try:
        with console.status("Reading folder list ..."):
            folders = session.list_folders()

        rows = []
        with Progress(SpinnerColumn(), TextColumn("[progress.description]{task.description}"),
                      BarColumn(), TaskProgressColumn(), console=console,
                      transient=True) as progress:
            task = progress.add_task("Counting messages", total=len(folders))
            for folder in folders:
                progress.update(task,
                                description=f"Counting: {rich_escape(folder.name)}")
                rows.append((folder.parts, session.message_count(folder),
                             folder.selectable))
                progress.advance(task)

        tree_lines = build_tree_lines(rows)
        table, total, n_folders = render_tree_table(
            f"{account.user} @ {account.host}", tree_lines)
        console.print()
        console.print(table)
        console.print("[dim]— : folder cannot hold messages (container only)[/dim]")

        stamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
        report = [
            "IMAP folder report",
            "=" * 60,
            f"Account : {account.user}",
            f"Server  : {account.host}:{account.port}",
            f"Date    : {stamp}",
            f"Folders : {n_folders}   Total messages: {total:,}",
            "",
        ] + tree_lines_as_text(tree_lines)
        offer_export(f"{sanitize_filename(account.user)}_{report_timestamp()}.txt",
                     report)
    finally:
        session.logout()


# --------------------------------------------------------------------------
# Action 2 — copy / migrate
# --------------------------------------------------------------------------

def build_dest_parts(source_parts, root_parts, dest_delimiter):
    return tuple(root_parts) + tuple(
        sanitize_component(p, dest_delimiter) for p in source_parts)


def migration_root_parts(src_account: Account, dst_session: ImapSession):
    label = sanitize_component(f"{src_account.user}_{src_account.host}",
                               dst_session.delimiter)
    return [MIGRATION_ROOT, label]


# RFC 6154 special-use flags used to pair standard folders across servers
# whose names differ ("Sent" vs "Sent Items" vs "[Gmail]/Enviados").
SPECIAL_USE_FLAGS = ("\\Sent", "\\Drafts", "\\Junk", "\\Trash", "\\Archive")


def special_use_map(folders):
    """Return {special-use flag: first folder declaring it}."""
    result = {}
    for f in folders:
        for flag in SPECIAL_USE_FLAGS:
            if flag not in result and f.has_flag(flag):
                result[flag] = f
    return result


def build_merge_map(src_folders, dst_folders, dst_delimiter):
    """Map every source folder onto the destination's own hierarchy.

    Used by merge mode (copy into the same folders instead of the
    _IMAP-Synchronizer sandbox):
      * INBOX maps to INBOX.
      * Standard folders are paired by their RFC 6154 special-use flag
        when both servers declare one (Sent -> "Sent Items", ...); their
        subfolders follow them.
      * Everything else keeps its relative path. A leading INBOX
        component is dropped when the source hierarchy lives under
        INBOX (Dovecot/Courier "INBOX." namespaces) and re-added when
        the destination only knows folders under INBOX.
    Returns {source_parts: destination_parts}."""
    dst_special = special_use_map(dst_folders)
    prefix_map = {}
    for flag, sfolder in special_use_map(src_folders).items():
        dfolder = dst_special.get(flag)
        if dfolder is not None:
            prefix_map[sfolder.parts] = dfolder.parts
    dest_inbox_only = all(f.parts[0].upper() == "INBOX" for f in dst_folders)

    mapping = {}
    for f in src_folders:
        parts = f.parts
        best = None
        for sprefix, dprefix in prefix_map.items():
            if (parts[:len(sprefix)] == sprefix
                    and (best is None or len(sprefix) > len(best[0]))):
                best = (sprefix, dprefix)
        if best is not None:
            rel = parts[len(best[0]):]
            base = best[1]
        else:
            rel = parts[1:] if parts[0].upper() == "INBOX" else parts
            if not rel:
                mapping[parts] = ("INBOX",)
                continue
            base = ("INBOX",) if dest_inbox_only else ()
        mapping[parts] = tuple(base) + tuple(
            sanitize_component(p, dst_delimiter) for p in rel)
    return mapping


# IMAP SEARCH dates must use English month abbreviations regardless of the
# system locale, so they are spelled out instead of using strftime %b.
IMAP_MONTHS = ("Jan", "Feb", "Mar", "Apr", "May", "Jun",
               "Jul", "Aug", "Sep", "Oct", "Nov", "Dec")


def imap_date(d: datetime) -> str:
    return f"{d.day}-{IMAP_MONTHS[d.month - 1]}-{d.year}"


def build_date_criteria(date_from, date_to):
    """IMAP SEARCH criteria for an inclusive [date_from, date_to] range.

    Uses the server's internal date. BEFORE is exclusive, so the end date
    is shifted one day to make the range inclusive.
    """
    parts = []
    if date_from:
        parts.append("SINCE " + imap_date(date_from))
    if date_to:
        parts.append("BEFORE " + imap_date(date_to + timedelta(days=1)))
    return "(" + " ".join(parts) + ")" if parts else None


def parse_user_date(text: str) -> datetime:
    # ISO yyyy-mm-dd is the documented format; dd/mm/yyyy and dd-mm-yyyy
    # are still accepted so older job/batch files keep working.
    for fmt in ("%Y-%m-%d", "%d/%m/%Y", "%d-%m-%Y"):
        try:
            return datetime.strptime(text.strip(), fmt)
        except ValueError:
            continue
    raise ValueError(f"Unrecognized date '{text}' — use yyyy-mm-dd")


def prompt_date_range():
    """Interactive optional date filter; returns (date_from, date_to)."""
    if not Confirm.ask(
            "Copy only a [bold]date range[/bold] instead of everything?",
            default=False):
        return None, None
    console.print("[dim]Dates are matched against the server (arrival) date. "
                  "Leave a field empty for no limit.[/dim]")
    while True:
        date_from = date_to = None
        try:
            raw = Prompt.ask("  From date (yyyy-mm-dd)", default="")
            if raw.strip():
                date_from = parse_user_date(raw)
            raw = Prompt.ask("  To date (yyyy-mm-dd, inclusive)", default="")
            if raw.strip():
                date_to = parse_user_date(raw)
        except ValueError as exc:
            console.print(f"[red]{exc}[/red]")
            continue
        if date_from and date_to and date_from > date_to:
            console.print("[red]The 'from' date is after the 'to' date.[/red]")
            continue
        return date_from, date_to


def warn_all_mail(folders):
    """Offer to exclude \\All folders (Gmail 'All Mail' and equivalents).

    Gmail exposes a virtual folder containing a copy of every message
    (named '[Gmail]/All Mail', '[Gmail]/Todos', ... depending on language);
    copying it duplicates the entire mailbox. The \\All special-use flag
    identifies it regardless of language.
    """
    kept = []
    for f in folders:
        if f.has_flag("\\All"):
            console.print(Panel(
                f"[bold yellow]'{rich_escape(f.name)}'[/bold yellow] is the server's "
                "\"all mail\" virtual folder: it contains a copy of every "
                "message in the account. Copying it would duplicate the "
                "whole mailbox in the destination.",
                border_style="yellow", title="[yellow]Gmail warning[/yellow]"))
            if Confirm.ask(f"  Exclude '{rich_escape(f.name)}' from the copy?",
                           default=True):
                console.print(f"  [yellow]Excluded: {rich_escape(f.name)}[/yellow]")
                continue
        kept.append(f)
    return kept


def parse_folder_exclusions(answer: str, names):
    """Resolve the folder-exclusion answer of choose_folders.

    Each comma-separated token may be a list number or a full folder name
    (case-insensitive, optionally quoted). Returns (indexes, unmatched)."""
    by_name = {n.lower(): i for i, n in enumerate(names)}
    excluded, unmatched = set(), []
    for token in answer.split(","):
        token = strip_surrounding_quotes(token.strip())
        if not token:
            continue
        if token.isdigit() and 1 <= int(token) <= len(names):
            excluded.add(int(token) - 1)
        elif token.lower() in by_name:
            excluded.add(by_name[token.lower()])
        else:
            unmatched.append(token)
    return excluded, unmatched


def choose_folders(folders):
    """Let the user optionally exclude folders; returns the selection."""
    selectable = warn_all_mail([f for f in folders if f.selectable])
    table = Table(box=box.SIMPLE, header_style="bold")
    table.add_column("#", style="cyan", justify="right")
    table.add_column("Folder")
    for idx, f in enumerate(selectable, 1):
        table.add_row(str(idx), rich_escape(f.name))
    console.print(table)
    answer = Prompt.ask(
        "Folders to [bold]exclude[/bold] — numbers and/or full names, "
        "comma-separated (Enter = copy everything)", default="")
    excluded, unmatched = parse_folder_exclusions(
        answer, [f.name for f in selectable])
    if unmatched:
        console.print("[yellow]Ignored (no such folder or number):[/yellow] "
                      + rich_escape(", ".join(unmatched)))
    if excluded:
        console.print("[yellow]Excluded:[/yellow] " + rich_escape(
            ", ".join(selectable[i].name for i in sorted(excluded))))
    return [f for i, f in enumerate(selectable) if i not in excluded]


def filter_folders_unattended(folders, exclude_names):
    """Folder selection for job/batch runs: no prompts.

    Drops non-selectable folders, \\All virtual folders (always — copying
    them duplicates the mailbox) and any folder whose full name matches
    the exclude list (case-insensitive).
    """
    excludes = {n.strip().lower() for n in exclude_names if n.strip()}
    kept = []
    for f in folders:
        if not f.selectable:
            continue
        if f.has_flag("\\All"):
            log.info("excluded \\All virtual folder: %s", f.name)
            continue
        if f.name.lower() in excludes:
            log.info("excluded by configuration: %s", f.name)
            continue
        kept.append(f)
    return kept


def setup_migration_log():
    """Attach a per-migration audit log (every copied message) under logs/.

    Returns (path, handler) or None. A failure to create it (read-only
    media, full disk) must not prevent the migration itself."""
    try:
        log_path = (ensure_logs_dir()
                    / f"imapsynchronizer_migration_{datetime.now():%Y%m%d_%H%M%S}.log")
        handler = logging.FileHandler(log_path, encoding="utf-8")
    except OSError as exc:
        console.print(f"[yellow]Could not create the log file ({exc}) — "
                      "continuing without it.[/yellow]")
        return None
    handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(message)s"))
    handler.setLevel(logging.INFO)
    log.addHandler(handler)
    return log_path, handler


def exclude_sync_subtree_if_same_account(src_folders, src_account, dst_account,
                                         quiet=False):
    """When source == destination account, drop a previous run's
    _IMAP-Synchronizer subtree from the source (it would be copied into itself,
    growing on every run)."""
    if ((src_account.host, src_account.port, src_account.user)
            != (dst_account.host, dst_account.port, dst_account.user)):
        return src_folders
    roots = (MIGRATION_ROOT,) + LEGACY_MIGRATION_ROOTS
    kept = [f for f in src_folders
            if not any(r in f.parts[:2] for r in roots)]
    if len(kept) != len(src_folders) and not quiet:
        console.print(f"[yellow]Same account on both sides — existing "
                      f"{MIGRATION_ROOT}/ folders were excluded from "
                      "the source.[/yellow]")
    return kept


def perform_migration(src, dst, src_account, dst_account, folders,
                      date_from=None, date_to=None,
                      interactive=True, auto_report=False, merge=False):
    """Analyze, plan, copy, verify and report one migration.

    Returns a result dict, or None if the user cancelled at the plan stage.
    `interactive=False` skips every prompt (job/batch mode); `auto_report`
    writes the TXT report without asking. `merge=True` copies into the
    destination's own folders (same structure) instead of the _IMAP-Synchronizer
    sandbox; existing destination messages are never touched and do not
    affect verification (only the presence of source messages is checked).
    """
    criteria = build_date_criteria(date_from, date_to)

    # ---- analysis phase --------------------------------------------------
    counts = {}
    with Progress(SpinnerColumn(), TextColumn("{task.description}"), BarColumn(),
                  TaskProgressColumn(), console=console, transient=True) as progress:
        task = progress.add_task("Analyzing source", total=len(folders))
        for folder in folders:
            progress.update(task,
                            description=f"Analyzing: {rich_escape(folder.name)}")
            try:
                if criteria:
                    counts[folder.parts] = len(
                        src.search_uids(folder.raw, criteria))
                else:
                    counts[folder.parts] = src.message_count(folder) or 0
            except (ImapError, imaplib.IMAP4.error, ssl.SSLError,
                    OSError) as exc:
                # Shown as 0 in the plan; the copy phase retries the folder
                # and reports it properly if it keeps failing.
                counts[folder.parts] = 0
                progress.console.print(
                    f"  [yellow]Could not analyze "
                    f"'{rich_escape(folder.name)}': {exc}[/yellow]")
            progress.advance(task)

    tree_lines = build_tree_lines(
        [(f.parts, counts[f.parts], True) for f in folders])
    table, total, n_folders = render_tree_table("Source content to copy",
                                                tree_lines)
    console.print(table)

    merge_map = {}
    if merge:
        with console.status("Reading destination folder structure ..."):
            dst_folders = dst.list_folders()
        merge_map = build_merge_map(folders, dst_folders, dst.delimiter)
        root_parts = []
        dest_root_display = "the destination's own folders (MERGE)"
    else:
        root_parts = migration_root_parts(src_account, dst)
        dest_root_display = f"{root_parts[0]}/{root_parts[1]}/"
    date_filter_text = "none (full mailbox)"
    if criteria:
        date_filter_text = "%s → %s" % (
            date_from.strftime("%Y-%m-%d") if date_from else "beginning",
            date_to.strftime("%Y-%m-%d") if date_to else "today")
    summary = Panel(
        f"[bold]Source     :[/bold] {src_account.label}\n"
        f"[bold]Destination:[/bold] {dst_account.label}\n"
        f"[bold]Copy into  :[/bold] {dest_root_display}\n"
        f"[bold]Date filter:[/bold] {date_filter_text}\n"
        f"[bold]Folders    :[/bold] {n_folders}\n"
        f"[bold]Messages   :[/bold] {total:,}\n\n"
        + ("[bold yellow]MERGE mode:[/bold yellow] messages are added into "
           "the destination's existing\nfolders (Sent→Sent, INBOX→INBOX, …), "
           "mixing with its current mail.\n" if merge else "")
        + "[dim]Existing destination content is never modified. Messages\n"
          "already present (from a previous partial run) are skipped.[/dim]",
        title="[bold]Migration plan[/bold]", border_style="cyan")
    console.print(summary)

    if interactive and not Confirm.ask("[bold]Proceed with the copy?[/bold]",
                                       default=False):
        console.print("[yellow]Migration cancelled.[/yellow]")
        return None

    # ---- copy phase --------------------------------------------------------
    log_path = mig_handler = None
    log_info = setup_migration_log()
    if log_info:
        log_path, mig_handler = log_info
        console.print(f"[dim]Detailed log: {log_path}[/dim]\n")
    try:
        log.info("Migration start: %s -> %s under %s (date filter: %s)",
                 src_account.label, dst_account.label, dest_root_display,
                 date_filter_text)

        # If the server refuses top-level folders, fall back to INBOX.<...>
        # (merge mode maps onto existing hierarchy, no sandbox root needed)
        if not merge:
            try:
                dst.ensure_path(root_parts[:1])
            except ImapError:
                root_parts = ["INBOX"] + root_parts
                log.info("destination rejected top-level folders — creating "
                         "under %s/%s/%s/ instead",
                         root_parts[0], root_parts[1], root_parts[2])
                console.print("[yellow]Top-level folder rejected by destination "
                              f"— creating under INBOX instead ({root_parts[0]}/"
                              f"{root_parts[1]}/{root_parts[2]}/).[/yellow]")

        stats = []           # (folder, total, already, copied, failed, dest_raw)
        src_key_counters = {}
        folder_errors = []   # (folder name, error) — folder skipped entirely
        dest_owner = {}      # dest_raw -> first source folder mapped to it
        started = datetime.now()

        for folder in folders:
            try:
                if merge:
                    dest_parts = merge_map[folder.parts]
                else:
                    dest_parts = build_dest_parts(folder.parts, root_parts,
                                                  dst.delimiter)
                dest_raw = dst.ensure_path(dest_parts)
                if dest_raw in dest_owner:
                    # Name sanitization can make two source folders share one
                    # destination folder; dedupe still works but they merge.
                    console.print(
                        f"  [yellow]Warning: '{rich_escape(folder.name)}' and "
                        f"'{rich_escape(dest_owner[dest_raw])}' map to the same "
                        "destination folder — their messages will be "
                        "merged.[/yellow]")
                    log.warning("destination collision: %s and %s -> %s",
                                folder.name, dest_owner[dest_raw],
                                imap_utf7_decode(dest_raw))
                else:
                    dest_owner[dest_raw] = folder.name

                with console.status(
                        f"Scanning [bold]{rich_escape(folder.name)}[/bold] "
                        "(source and destination) ..."):
                    src_pairs = src.fetch_message_keys(folder.raw, criteria)
                    dst_counter = Counter(
                        k for _u, k in dst.fetch_message_keys(dest_raw))
                src_key_counters[folder.parts] = Counter(
                    k for _u, k in src_pairs)

                remaining = dst_counter.copy()
                to_copy, already = [], 0
                for uid, key in src_pairs:
                    if remaining[key] > 0:
                        remaining[key] -= 1
                        already += 1
                    else:
                        to_copy.append(uid)

                copied = failed = vanished = consecutive = 0
                uid_to_key = dict(src_pairs)
                if to_copy:
                    src.select_folder(folder.raw, readonly=True)
                    with Progress(SpinnerColumn(),
                                  TextColumn("{task.description}"),
                                  BarColumn(), TaskProgressColumn(),
                                  TimeElapsedColumn(),
                                  console=console) as progress:
                        task = progress.add_task(
                            f"Copying {rich_escape(folder.name)}",
                            total=len(to_copy))
                        for uid in to_copy:
                            try:
                                fetched = src.fetch_full_message(uid)
                                if fetched is None:
                                    # The message disappeared from the source
                                    # between the scan and the copy (someone
                                    # emptied Trash mid-run, a client expunged
                                    # it, ...). Not a connection problem and
                                    # nothing left to copy: skip it, keep the
                                    # verification honest, don't feed the
                                    # dead-connection counter.
                                    vanished += 1
                                    key = uid_to_key.get(uid)
                                    if key:
                                        src_key_counters[folder.parts] -= \
                                            Counter((key,))
                                    log.warning(
                                        "%s UID %s no longer exists in the "
                                        "source (deleted during the run) — "
                                        "skipped", folder.name, uid)
                                    progress.advance(task)
                                    continue
                                flags, internaldate, body = fetched
                                dst.append_message(dest_raw, flags,
                                                   internaldate, body)
                                copied += 1
                                consecutive = 0
                                # Debug on purpose: one line per message would
                                # bloat the log; the per-folder summary
                                # (total/copied/already/failed) is what counts.
                                log.debug("copied %s UID %s (%d bytes)",
                                          folder.name, uid, len(body))
                            except (ImapError, imaplib.IMAP4.error,
                                    ssl.SSLError, OSError) as exc:
                                failed += 1
                                consecutive += 1
                                log.error("FAILED %s UID %s: %s",
                                          folder.name, uid, exc)
                                progress.console.print(
                                    f"  [red]Failed message UID {uid} in "
                                    f"{rich_escape(folder.name)}: {exc}[/red]")
                                if consecutive >= 10:
                                    raise MigrationAborted(
                                        f"{folder.name}: {consecutive} "
                                        f"consecutive failures — the "
                                        f"connection looks dead, stopping "
                                        f"(last error: {exc}). Re-running "
                                        "resumes where it left off.")
                            progress.advance(task)

                state = ("[green]done[/green]" if failed == 0
                         else "[red]with errors[/red]")
                vanished_txt = (f", [yellow]{vanished:,} deleted from source "
                                f"mid-run[/yellow]" if vanished else "")
                console.print(
                    f"  {rich_escape(folder.name)}: {copied:,} copied, "
                    f"{already:,} already present, {failed:,} failed"
                    f"{vanished_txt} — {state}")
                log.info("folder %s: total=%d copied=%d already=%d failed=%d "
                         "vanished=%d", folder.name,
                         len(src_pairs) - vanished, copied, already, failed,
                         vanished)
                stats.append((folder, len(src_pairs) - vanished, already,
                              copied, failed, dest_raw))
            except MigrationAborted:
                raise
            except (ImapError, imaplib.IMAP4.error, ssl.SSLError,
                    OSError) as exc:
                # One bad folder must not abort the rest of the migration.
                console.print(f"  [red]Folder '{rich_escape(folder.name)}' "
                              f"could not be processed: {exc}[/red]")
                log.error("FOLDER FAILED %s: %s", folder.name, exc)
                folder_errors.append((folder.name, str(exc)))

        # ---- verification phase ---------------------------------------------
        console.print()
        console.rule("[bold cyan]Verification[/bold cyan]", style="cyan")
        verify_table = Table(box=box.ROUNDED, header_style="bold")
        verify_table.add_column("Folder", overflow="fold")
        verify_table.add_column("Source", justify="right")
        verify_table.add_column("Copied", justify="right")
        verify_table.add_column("Existing", justify="right")
        verify_table.add_column("Failed", justify="right")
        verify_table.add_column("Verified", justify="center")

        all_ok = True
        total_copied = total_failed = total_missing = 0
        report_rows = []
        verify_errors = []   # (folder name, error) — copied but not re-checked
        for folder, src_total, already, copied, failed, dest_raw in stats:
            total_copied += copied
            total_failed += failed
            try:
                with console.status(
                        f"Verifying [bold]{rich_escape(folder.name)}[/bold] ..."):
                    dst_counter = Counter(
                        k for _u, k in dst.fetch_message_keys(dest_raw))
            except (ImapError, imaplib.IMAP4.error, ssl.SSLError,
                    OSError) as exc:
                # The copy already happened; a network hiccup here must not
                # discard the whole run's result.
                all_ok = False
                verify_errors.append((folder.name, str(exc)))
                log.error("VERIFY FAILED %s: %s", folder.name, exc)
                verify_table.add_row(rich_escape(folder.name), f"{src_total:,}",
                                     f"{copied:,}", f"{already:,}",
                                     f"{failed:,}",
                                     "[red]✗ verify error[/red]")
                continue
            missing = sum((src_key_counters[folder.parts] - dst_counter).values())
            ok = missing == 0 and failed == 0
            all_ok = all_ok and ok
            total_missing += missing
            verdict = "[green]✓[/green]" if ok else f"[red]✗ missing {missing}[/red]"
            verify_table.add_row(rich_escape(folder.name), f"{src_total:,}",
                                 f"{copied:,}", f"{already:,}", f"{failed:,}",
                                 verdict)
            report_rows.append((folder.name, src_total, copied, already,
                                failed, missing))
        for name, _err in folder_errors:
            all_ok = False
            verify_table.add_row(rich_escape(name), "—", "—", "—", "—",
                                 "[red]✗ folder error[/red]")
        console.print(verify_table)

        elapsed = datetime.now() - started
        if all_ok:
            console.print(Panel(
                "[bold green]Migration complete and verified.[/bold green]\n"
                "Every analyzed source message is present in the destination.",
                border_style="green"))
        else:
            console.print(Panel(
                "[bold red]Migration finished with differences.[/bold red]\n"
                "Some messages are missing in the destination — check the table\n"
                "above and the log file. Re-running the copy is safe: it only\n"
                "copies what is still missing.",
                border_style="red"))
        log.info("Migration finished in %s — verified_ok=%s", elapsed, all_ok)

        # ---- report -----------------------------------------------------------
        stamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
        copied_into = dest_root_display if merge else "/".join(root_parts) + "/"
        report = [
            "IMAP migration report",
            "=" * 60,
            f"Source      : {src_account.label}",
            f"Destination : {dst_account.label}",
            f"Copied into : {copied_into}",
            f"Date filter : {date_filter_text}",
            f"Date        : {stamp}   (duration {elapsed})",
            f"Result      : {'VERIFIED OK' if all_ok else 'DIFFERENCES FOUND'}",
            "",
            f"{'Folder':<50} {'Source':>8} {'Copied':>8} {'Existing':>9} "
            f"{'Failed':>7} {'Missing':>8}",
            "-" * 95,
        ]
        for name, src_total, copied, already, failed, missing in report_rows:
            report.append(f"{name:<50} {src_total:>8,} {copied:>8,} "
                          f"{already:>9,} {failed:>7,} {missing:>8,}")
        if folder_errors:
            report += ["", "Folders that could not be processed:"]
            report += [f"  {name}: {err}" for name, err in folder_errors]
        if verify_errors:
            report += ["", "Folders copied but whose verification failed "
                           "(re-run to verify):"]
            report += [f"  {name}: {err}" for name, err in verify_errors]

        report_name = (f"{sanitize_filename(src_account.user)}_migration_"
                       f"{report_timestamp()}.txt")

        # ---- leave the report as an e-mail inside the destination ----------
        # Sandbox: in the _IMAP-Synchronizer root (falling back to the
        # account subfolder if the root cannot hold messages). Merge: the
        # _IMAP-Synchronizer folder is created just for the record.
        # Body: plain text + styled HTML alternative + the TXT attached.
        try:
            html_ctx = {"ok": all_ok, "rows": report_rows,
                        "folder_errors": folder_errors,
                        "verify_errors": verify_errors,
                        "copied_into": copied_into,
                        "date_filter": date_filter_text, "stamp": stamp,
                        "elapsed": str(elapsed).split(".")[0]}
            mail_body = build_report_email(report, src_account, dst_account,
                                           html_ctx=html_ctx,
                                           attachment_name=report_name)
            if merge:
                candidates = ((MIGRATION_ROOT,), ("INBOX", MIGRATION_ROOT))
            else:
                candidates = (tuple(root_parts[:-1]), tuple(root_parts))
            stored_err = None
            for parts in candidates:
                try:
                    raw = dst.ensure_path(parts)
                    dst.append_message(raw, "\\Seen", None, mail_body)
                    console.print(f"[dim]A copy of this report was stored as "
                                  f"an e-mail in the destination folder "
                                  f"'{'/'.join(parts)}'.[/dim]")
                    log.info("report e-mail stored in destination folder %s",
                             "/".join(parts))
                    break
                except (ImapError, imaplib.IMAP4.error, ssl.SSLError,
                        OSError) as exc:
                    stored_err = exc
            else:
                log.warning("could not store the report e-mail in the "
                            "destination: %s", stored_err)
        except Exception as exc:
            # The record mail must never break a finished migration.
            log.warning("could not build/store the report e-mail: %s", exc)

        report_path = None
        if auto_report:
            # A report-write failure must not turn a verified migration
            # into an error exit for schedulers.
            try:
                report_path = write_report(report_name, report)
                console.print(f"[green]Report saved:[/green] {report_path}")
            except OSError as exc:
                console.print(f"[yellow]Could not save the report: "
                              f"{exc}[/yellow]")
        elif interactive:
            offer_export(report_name, report)

        return {"ok": all_ok, "copied": total_copied, "failed": total_failed,
                "missing": total_missing, "total": total,
                "report_path": report_path}
    finally:
        # Detach only this migration's audit log — the session error log
        # must keep recording until the program exits.
        if mig_handler is not None:
            log.removeHandler(mig_handler)
            mig_handler.close()


def action_copy():
    src_account = prompt_account("SOURCE account (messages are only read)")
    src = connect_session(src_account, "Source")
    if src is None:
        return
    dst = None
    try:
        dst_account = prompt_account("DESTINATION account (messages are added)")
        dst = connect_session(dst_account, "Destination")
        if dst is None:
            return

        console.print()
        console.rule("[bold cyan]Analysis[/bold cyan]", style="cyan")
        with console.status("Reading source folder structure ..."):
            src_folders = src.list_folders()
            dst.list_folders()          # warm the destination folder cache

        src_folders = exclude_sync_subtree_if_same_account(
            src_folders, src_account, dst_account)

        folders = choose_folders(src_folders)
        if not folders:
            console.print("[yellow]Nothing selected — aborting.[/yellow]")
            return

        console.print()
        console.print("Destination layout:")
        console.print(f"  [cyan]1[/cyan]  Sandbox — copy under "
                      f"{MIGRATION_ROOT}/<user>_<host>/ "
                      "(kept apart from existing mail)")
        console.print("  [cyan]2[/cyan]  Merge — add the messages into the "
                      "destination's [bold]same folders[/bold] "
                      "(INBOX→INBOX, Sent→Sent, …)")
        merge = Prompt.ask("Layout", choices=["1", "2"], default="1") == "2"

        date_from, date_to = prompt_date_range()
        perform_migration(src, dst, src_account, dst_account, folders,
                          date_from=date_from, date_to=date_to,
                          interactive=True, merge=merge)
    finally:
        src.logout()
        if dst is not None:
            dst.logout()


# --------------------------------------------------------------------------
# Action 3 — compare source and destination
# --------------------------------------------------------------------------

def action_verify():
    src_account = prompt_account("SOURCE account")
    src = connect_session(src_account, "Source")
    if src is None:
        return
    dst = None
    try:
        dst_account = prompt_account("DESTINATION account")
        dst = connect_session(dst_account, "Destination")
        if dst is None:
            return

        console.print()
        console.print("How should the two accounts be compared?")
        console.print("  [cyan]1[/cyan]  Mirror — same folder paths on both sides")
        console.print(f"  [cyan]2[/cyan]  Post-migration — source vs "
                      f"{MIGRATION_ROOT}/<user>_<host>/ subtree in destination")
        console.print("  [cyan]3[/cyan]  Merge check — folders mapped like "
                      "merge mode; verifies everything from the source exists "
                      "in the destination (its own extra mail is fine)")
        mode = Prompt.ask("Mode", choices=["1", "2", "3"], default="2")

        with console.status("Reading folder lists ..."):
            src_folders = [f for f in src.list_folders() if f.selectable]
            dst_folders = dst.list_folders()
        dst_by_parts = {f.parts: f for f in dst_folders}

        merge_map = {}
        if mode == "3":
            merge_map = build_merge_map(src_folders, dst_folders,
                                        dst.delimiter)
        if mode == "2":
            # Same filter the migration itself applies, so both sides of
            # the comparison see the same source folder set.
            src_folders = exclude_sync_subtree_if_same_account(
                src_folders, src_account, dst_account, quiet=True)
            root_parts = migration_root_parts(src_account, dst)
            if tuple(root_parts) not in {f.parts[:len(root_parts)]
                                         for f in dst_folders}:
                alt = ["INBOX"] + root_parts
                if tuple(alt) in {f.parts[:len(alt)] for f in dst_folders}:
                    root_parts = alt
                else:
                    console.print(
                        f"[red]No '{'/'.join(root_parts)}/' subtree found in the "
                        "destination account — was the migration run?[/red]")
                    return
        else:
            root_parts = []

        table = Table(box=box.ROUNDED, header_style="bold",
                      title="Comparison result", title_style="bold cyan")
        table.add_column("Source folder", overflow="fold")
        table.add_column("Src msgs", justify="right")
        table.add_column("Dst msgs", justify="right")
        table.add_column("Missing", justify="right")
        table.add_column("Extra", justify="right")
        table.add_column("Status", justify="center")

        all_ok = True
        report_rows = []
        for folder in src_folders:
            if mode == "2":
                dest_parts = build_dest_parts(folder.parts, root_parts,
                                              dst.delimiter)
            elif mode == "3":
                dest_parts = merge_map[folder.parts]
            else:
                dest_parts = folder.parts
            dst_folder = dst_by_parts.get(tuple(dest_parts))

            try:
                with console.status(
                        f"Comparing [bold]{rich_escape(folder.name)}[/bold] ..."):
                    src_counter = Counter(
                        k for _u, k in src.fetch_message_keys(folder.raw))
                    if dst_folder is None:
                        dst_counter = None
                    else:
                        dst_counter = Counter(
                            k for _u, k in dst.fetch_message_keys(dst_folder.raw))
            except (ImapError, imaplib.IMAP4.error, ssl.SSLError,
                    OSError) as exc:
                # One unreadable folder must not abort the whole comparison.
                all_ok = False
                table.add_row(rich_escape(folder.name), "—", "—", "—", "—",
                              "[red]error[/red]")
                report_rows.append((folder.name, 0, None, None, None,
                                    f"ERROR: {exc}"))
                continue

            if dst_counter is None:
                all_ok = False
                table.add_row(rich_escape(folder.name),
                              f"{sum(src_counter.values()):,}",
                              "—", "—", "—", "[red]folder missing[/red]")
                report_rows.append((folder.name, sum(src_counter.values()),
                                    None, None, None, "FOLDER MISSING"))
                continue

            missing = sum((src_counter - dst_counter).values())
            extra = sum((dst_counter - src_counter).values())
            # In merge check the destination's own mail is expected:
            # only missing source messages count as a failure.
            ok = missing == 0 and (extra == 0 or mode == "3")
            all_ok = all_ok and ok
            status = ("[green]identical[/green]" if missing == 0 and extra == 0
                      else ("[green]contained[/green]" if mode == "3"
                            else "[yellow]complete + extra[/yellow]")
                      if missing == 0
                      else "[red]incomplete[/red]")
            table.add_row(rich_escape(folder.name),
                          f"{sum(src_counter.values()):,}",
                          f"{sum(dst_counter.values()):,}",
                          f"{missing:,}", f"{extra:,}", status)
            if missing == 0 and extra == 0:
                status_txt = "IDENTICAL"
            elif missing == 0:
                status_txt = "CONTAINED" if mode == "3" else "COMPLETE+EXTRA"
            else:
                status_txt = "INCOMPLETE"
            report_rows.append((folder.name, sum(src_counter.values()),
                                sum(dst_counter.values()), missing, extra,
                                status_txt))

        console.print(table)
        if all_ok:
            console.print(Panel(
                "[bold green]Everything from the source is present in the "
                "destination.[/bold green]\nThe destination's own extra mail "
                "is expected in a merge and not a difference."
                if mode == "3" else
                "[bold green]Both accounts are identical[/bold green] for the "
                "compared scope: same folders, same messages.",
                border_style="green"))
        else:
            console.print(Panel(
                "[bold red]Differences found.[/bold red] See the table above — "
                "'missing' means present in source but not in destination.",
                border_style="red"))

        stamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
        report = [
            "IMAP comparison report",
            "=" * 60,
            f"Source      : {src_account.label}",
            f"Destination : {dst_account.label}",
            f"Mode        : "
            f"{'mirror' if mode == '1' else 'merge containment' if mode == '3' else 'post-migration (' + '/'.join(root_parts) + '/)'}",
            f"Date        : {stamp}",
            f"Result      : {'IDENTICAL' if all_ok else 'DIFFERENCES FOUND'}",
            "",
            f"{'Folder':<50} {'Source':>8} {'Dest':>8} {'Missing':>8} "
            f"{'Extra':>7}  Status",
            "-" * 100,
        ]
        for name, s, d, miss, extra, status in report_rows:
            d_s = "—" if d is None else f"{d:,}"
            miss_s = "—" if miss is None else f"{miss:,}"
            extra_s = "—" if extra is None else f"{extra:,}"
            report.append(f"{name:<50} {s:>8,} {d_s:>8} {miss_s:>8} "
                          f"{extra_s:>7}  {status}")
        offer_export(
            f"{sanitize_filename(src_account.user)}_verify_"
            f"{report_timestamp()}.txt", report)
    finally:
        src.logout()
        if dst is not None:
            dst.logout()


# --------------------------------------------------------------------------
# Unattended job mode (--job) and batch CSV mode (--batch)
# --------------------------------------------------------------------------

def _account_from_config(cfg, what: str) -> Account:
    if not isinstance(cfg, dict):
        raise ImapError(f"{what}: must be a JSON object with "
                        "host/user/password_env fields")
    host, embedded_port = normalize_host(cfg.get("host") or "")
    user = (cfg.get("user") or "").strip()
    if not host or not user:
        raise ImapError(f"{what}: 'host' and 'user' are required")
    port = int(cfg.get("port") or embedded_port or 993)
    env_name = (cfg.get("password_env") or "").strip()
    if env_name:
        password = os.environ.get(env_name, "")
        if not password:
            raise ImapError(
                f"{what}: environment variable '{env_name}' is not set")
    else:
        password = cfg.get("password") or ""
        if not password:
            raise ImapError(f"{what}: provide 'password' or 'password_env'")
    return Account(host=host, port=port, user=user,
                   password=strip_surrounding_quotes(password))


def _connect_unattended(account: Account, role: str, insecure=False):
    session = ImapSession(account, role=role)
    session.allow_insecure_ssl = bool(insecure)
    with console.status(f"Connecting to {account.host}:{account.port} "
                        f"as {account.user} ..."):
        session.connect()
    console.print(f"  [green]OK[/green]  {role}: connected ({account.label})")
    return session


def run_migration_unattended(src_account, dst_account, exclude_folders=(),
                             date_from=None, date_to=None, insecure=False,
                             merge=False):
    """One prompt-free migration; returns perform_migration's result dict."""
    src = dst = None
    try:
        src = _connect_unattended(src_account, "Source", insecure)
        dst = _connect_unattended(dst_account, "Destination", insecure)
        src_folders = src.list_folders()
        dst.list_folders()          # warm the destination folder cache
        src_folders = exclude_sync_subtree_if_same_account(
            src_folders, src_account, dst_account, quiet=True)
        folders = filter_folders_unattended(src_folders, exclude_folders)
        if not folders:
            raise ImapError("no folders left to copy after exclusions")
        return perform_migration(src, dst, src_account, dst_account, folders,
                                 date_from=date_from, date_to=date_to,
                                 interactive=False, auto_report=True,
                                 merge=merge)
    finally:
        if src is not None:
            src.logout()
        if dst is not None:
            dst.logout()


def _parse_config_date(value):
    value = (value or "").strip()
    return parse_user_date(value) if value else None


def parse_job_json(text: str) -> dict:
    """Parse a job file. Full lines starting with # or // are comments —
    plain JSON forbids them, but they make the job files self-documenting."""
    lines = [ln for ln in text.splitlines(keepends=True)
             if not ln.lstrip().startswith(("#", "//"))]
    return json.loads("".join(lines))


def run_job(job_path: str) -> int:
    """Entry point for --job. Exit codes: 0 verified OK, 1 error, 2 differences."""
    try:
        with open(job_path, "r", encoding="utf-8-sig") as fh:
            cfg = parse_job_json(fh.read())
        if not isinstance(cfg, dict):
            raise ValueError("the job file must contain a JSON object {...}")
        excludes = cfg.get("exclude_folders") or []
        if isinstance(excludes, str):
            # Tolerate "Trash, Junk" instead of ["Trash", "Junk"] — iterating
            # the string would silently exclude one-letter folder names.
            excludes = excludes.split(",")
        result = run_migration_unattended(
            _account_from_config(cfg.get("source") or {}, "source"),
            _account_from_config(cfg.get("destination") or {}, "destination"),
            exclude_folders=excludes,
            date_from=_parse_config_date(cfg.get("date_from")),
            date_to=_parse_config_date(cfg.get("date_to")),
            insecure=bool(cfg.get("allow_insecure_ssl", True)),
            merge=bool(cfg.get("merge")))
    except (OSError, json.JSONDecodeError, ValueError, ImapError,
            imaplib.IMAP4.error, ssl.SSLError) as exc:
        log.error("job %s failed: %s", job_path, exc)
        console.print(f"[red]Job failed:[/red] {exc}")
        return 1
    return 0 if result["ok"] else 2


def _prompt_job_account(title: str) -> dict:
    console.print()
    console.rule(f"[bold cyan]{title}[/bold cyan]", style="cyan")
    host, embedded_port = normalize_host(Prompt.ask("  IMAP server"))
    entry = {
        "host": host,
        "port": embedded_port or IntPrompt.ask("  Port", default=993),
        "user": Prompt.ask("  Username / e-mail address").strip(),
    }
    console.print("  How should the job file get the password?")
    console.print("    [cyan]1[/cyan]  From an environment variable (recommended)")
    console.print("    [cyan]2[/cyan]  Stored in the job file "
                  "[red](plain text — protect the file!)[/red]")
    how = Prompt.ask("  Password storage", choices=["1", "2"], default="1")
    if how == "1":
        entry["password_env"] = Prompt.ask(
            "  Environment variable name (e.g. SRC_IMAP_PASS)").strip()
    else:
        entry["password"] = strip_surrounding_quotes(
            Prompt.ask("  Password", password=sys.stdin.isatty()))
    return entry


def action_create_job():
    console.print(Panel(
        "Creates a JSON job file that runs a full migration with no questions\n"
        "asked — meant for scheduled or unattended runs. The following\n"
        "questions build the file; you can also copy and edit the template\n"
        "[bold]migration_job.example.json[/bold] shipped with the program.\n\n"
        "[dim]Run it with:   python imapsynchronizer.py --job <file>\n"
        "Exit codes:    0 = verified OK    1 = error    2 = differences found\n"
        "See README.md § Unattended use for all fields and scheduling "
        "examples.[/dim]",
        title="[bold]Unattended job[/bold]", border_style="cyan"))

    source = _prompt_job_account("Job SOURCE account")
    destination = _prompt_job_account("Job DESTINATION account")

    excludes = [p.strip() for p in Prompt.ask(
        "Folder names to exclude (comma-separated, Enter for none)",
        default="").split(",") if p.strip()]

    date_from = date_to = ""
    while True:
        date_from = Prompt.ask("From date yyyy-mm-dd (Enter for none)",
                               default="").strip()
        date_to = Prompt.ask("To date yyyy-mm-dd, inclusive (Enter for none)",
                             default="").strip()
        try:
            _parse_config_date(date_from)
            _parse_config_date(date_to)
            break
        except ValueError as exc:
            console.print(f"[red]{exc}[/red]")

    merge = Confirm.ask(
        "Merge into the destination's existing folders (same structure) "
        f"instead of copying under {MIGRATION_ROOT}/?", default=False)
    insecure = Confirm.ask(
        "Accept invalid TLS certificates (insecure SSL)?", default=True)

    cfg = {
        "source": source,
        "destination": destination,
        "exclude_folders": excludes,
        "date_from": date_from,
        "date_to": date_to,
        "merge": merge,
        "allow_insecure_ssl": insecure,
    }
    filename = Prompt.ask("Job file name", default="migration_job.json").strip()
    path = SCRIPT_DIR / filename
    with open(path, "w", encoding="utf-8") as fh:
        json.dump(cfg, fh, indent=2, ensure_ascii=False)
        fh.write("\n")

    lines = [
        f"[green]Job file created:[/green] {path}",
        "",
        "Run it manually:",
        f"    python imapsynchronizer.py --job \"{path}\"",
        "",
        "Schedule it daily at 03:00 — Windows:",
        f"    schtasks /Create /SC DAILY /ST 03:00 /TN \"IMAP sync\" "
        f"/TR \"python {SCRIPT_DIR / 'imapsynchronizer.py'} --job {path}\"",
        "  (use the full path to python.exe if it is not on PATH)",
        "Linux / macOS (crontab -e):",
        f"    0 3 * * * python3 {path.parent / 'imapsynchronizer.py'} "
        f"--job {path}",
    ]
    if "password" in source or "password" in destination:
        lines += ["", "[red]The job file contains a plain-text password — "
                      "restrict who can read it.[/red]"]
    if "password_env" in source or "password_env" in destination:
        env_names = [e.get("password_env") for e in (source, destination)
                     if e.get("password_env")]
        lines += ["", "Before running, set: " +
                  ", ".join(f"[cyan]{n}[/cyan]" for n in env_names)]
    console.print(Panel("\n".join(lines), border_style="green"))


BATCH_REQUIRED_COLUMNS = ("src_host", "src_user", "src_password",
                          "dst_host", "dst_user", "dst_password")

BATCH_TEMPLATE = (
    "src_host,src_port,src_user,src_password,"
    "dst_host,dst_port,dst_user,dst_password,"
    "date_from,date_to,exclude,insecure,merge\n"
    'imap.old-server.com,993,user1@old.com,"pass,word1",'
    'imap.new-server.com,993,user1@new.com,"secret2",'
    ",,Trash|Junk|Example_exclude,,\n"
    "imap.old-server.com,993,user2@old.com,secret3,"
    "imap.new-server.com,993,user2@new.com,secret4,"
    "2020-01-01,2025-12-31,,,\n")


def csv_flag(value, default=False) -> bool:
    """Interpret an optional CSV boolean cell (empty cell = default)."""
    text = (value or "").strip().lower()
    if not text:
        return default
    return text in ("1", "true", "yes", "y")


def load_batch_rows(path: str):
    with open(path, "r", newline="", encoding="utf-8-sig") as fh:
        sample = fh.read(8192)
        fh.seek(0)
        delimiter = ";" if sample.count(";") > sample.count(",") else ","
        reader = csv.DictReader(fh, delimiter=delimiter)
        rows = []
        for lineno, raw_row in enumerate(reader, 2):
            row = {(k or "").strip().lower(): (v or "").strip()
                   for k, v in raw_row.items()}
            if not any(row.values()):
                continue
            missing = [c for c in BATCH_REQUIRED_COLUMNS if not row.get(c)]
            if missing:
                raise ValueError(
                    f"line {lineno}: missing value(s) for {', '.join(missing)}")
            rows.append(row)
    if not rows:
        raise ValueError("the CSV contains no data rows")
    return rows


def run_batch(batch_path: str, interactive: bool) -> int:
    """Run every migration in a CSV. Exit codes: 0 all OK, 1 error, 2 issues."""
    try:
        rows = load_batch_rows(batch_path)
    except (OSError, ValueError, csv.Error) as exc:
        console.print(f"[red]Cannot read batch file:[/red] {exc}")
        return 1

    console.print(f"\n[bold]{len(rows)}[/bold] migration(s) found in {batch_path}")
    if interactive and not Confirm.ask("Start the batch run?", default=False):
        console.print("[yellow]Batch cancelled.[/yellow]")
        return 1

    results = []
    for idx, row in enumerate(rows, 1):
        console.print()
        console.rule(f"[bold cyan]Batch {idx}/{len(rows)}: "
                     f"{row['src_user']} → {row['dst_user']}[/bold cyan]",
                     style="cyan")
        try:
            src_host, src_embedded = normalize_host(row["src_host"])
            dst_host, dst_embedded = normalize_host(row["dst_host"])
            src_account = Account(
                host=src_host,
                port=int(row.get("src_port") or src_embedded or 993),
                user=row["src_user"],
                password=strip_surrounding_quotes(row["src_password"]))
            dst_account = Account(
                host=dst_host,
                port=int(row.get("dst_port") or dst_embedded or 993),
                user=row["dst_user"],
                password=strip_surrounding_quotes(row["dst_password"]))
            excludes = [p.strip() for p in (row.get("exclude") or "").split("|")
                        if p.strip()]
            result = run_migration_unattended(
                src_account, dst_account, exclude_folders=excludes,
                date_from=_parse_config_date(row.get("date_from")),
                date_to=_parse_config_date(row.get("date_to")),
                insecure=csv_flag(row.get("insecure"), default=True),
                merge=csv_flag(row.get("merge")))
            status = "VERIFIED OK" if result["ok"] else "DIFFERENCES"
            results.append((idx, row["src_user"], row["dst_user"], status,
                            result["copied"], result["failed"]))
        except (ImapError, imaplib.IMAP4.error, ssl.SSLError, OSError,
                ValueError) as exc:
            log.error("batch row %d (%s -> %s) failed: %s", idx,
                      row.get("src_user", "?"), row.get("dst_user", "?"), exc)
            console.print(f"[red]Migration {idx} failed:[/red] {exc}")
            results.append((idx, row.get("src_user", "?"),
                            row.get("dst_user", "?"), f"ERROR: {exc}", 0, 0))

    console.print()
    table = Table(title="Batch summary", title_style="bold cyan",
                  box=box.ROUNDED, header_style="bold")
    table.add_column("#", justify="right")
    table.add_column("Source", overflow="fold")
    table.add_column("Destination", overflow="fold")
    table.add_column("Copied", justify="right")
    table.add_column("Failed", justify="right")
    table.add_column("Status", overflow="fold")
    all_ok = True
    for idx, src_user, dst_user, status, copied, failed in results:
        ok = status == "VERIFIED OK"
        all_ok = all_ok and ok
        style = "green" if ok else "red"
        table.add_row(str(idx), src_user, dst_user, f"{copied:,}",
                      f"{failed:,}", f"[{style}]{status}[/{style}]")
    console.print(table)

    stamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
    report = [
        "IMAP batch migration report",
        "=" * 60,
        f"Batch file : {batch_path}",
        f"Date       : {stamp}",
        f"Result     : {'ALL VERIFIED OK' if all_ok else 'ISSUES FOUND'}",
        "",
        f"{'#':>3} {'Source':<32} {'Destination':<32} {'Copied':>8} "
        f"{'Failed':>7}  Status",
        "-" * 100,
    ]
    for idx, src_user, dst_user, status, copied, failed in results:
        report.append(f"{idx:>3} {src_user:<32} {dst_user:<32} {copied:>8,} "
                      f"{failed:>7,}  {status}")
    report_name = f"batch_{report_timestamp()}.txt"
    if interactive:
        offer_export(report_name, report)
    else:
        try:
            path = write_report(report_name, report)
            console.print(f"[green]Batch report saved:[/green] {path}")
        except OSError as exc:
            console.print(f"[yellow]Could not save the batch report: "
                          f"{exc}[/yellow]")
    return 0 if all_ok else 2


def action_batch():
    console.print(Panel(
        "Runs one migration per CSV row, sequentially, without prompts.\n"
        "Required columns: src_host, src_user, src_password, dst_host, "
        "dst_user, dst_password.\n"
        "Optional: src_port, dst_port (default 993), date_from, date_to "
        "(yyyy-mm-dd), exclude (folder names separated by |), insecure\n"
        "(yes = accept invalid TLS certificates), merge (yes = copy into "
        "the destination's own folders instead of _IMAP-Synchronizer/).\n\n"
        "[dim]Passwords containing commas must be quoted, CSV-style: "
        '"pass,word". The same file works with '
        "python imapsynchronizer.py --batch <file> for scheduled runs.\n"
        "A ready-to-edit template ships as batch_migrations.example.csv; "
        "see README.md § Unattended use.[/dim]",
        title="[bold]Batch copy from CSV[/bold]", border_style="cyan"))
    default_path = str(SCRIPT_DIR / "batch_migrations.csv")
    path = Prompt.ask("CSV file path", default=default_path).strip()
    path = strip_surrounding_quotes(path)
    if not Path(path).exists():
        console.print(f"[yellow]File not found:[/yellow] {path}")
        if Confirm.ask("Create a template CSV there to fill in?", default=True):
            try:
                Path(path).write_text(BATCH_TEMPLATE, encoding="utf-8")
            except OSError as exc:
                console.print(f"[red]Could not create the template: {exc}[/red]")
                return
            console.print(f"[green]Template created:[/green] {path}\n"
                          "Edit it with your accounts and run this option again.")
        return
    run_batch(path, interactive=True)


# --------------------------------------------------------------------------
# Action — manage saved profiles
# --------------------------------------------------------------------------

def action_profiles():
    while True:
        profiles = load_profiles()
        console.print()
        if not profiles:
            console.print("[dim]No saved profiles. They are offered for saving "
                          "after each successful connection.[/dim]")
            return
        table = Table(box=box.ROUNDED, header_style="bold",
                      title="Saved profiles (passwords are never stored)",
                      title_style="bold cyan")
        table.add_column("#", style="cyan", justify="right")
        table.add_column("Profile")
        table.add_column("User")
        table.add_column("Server")
        for idx, p in enumerate(profiles, 1):
            table.add_row(str(idx), p.get("name", ""), p["user"],
                          f"{p['host']}:{p.get('port', 993)}")
        console.print(table)
        answer = Prompt.ask("Profile number to delete, or press Enter to go back",
                            default="")
        if not answer.strip():
            return
        if answer.strip().isdigit() and 1 <= int(answer) <= len(profiles):
            removed = profiles.pop(int(answer) - 1)
            save_profiles(profiles)
            console.print(f"[yellow]Deleted profile "
                          f"'{removed.get('name', removed['user'])}'.[/yellow]")


# --------------------------------------------------------------------------
# Main menu
# --------------------------------------------------------------------------

def show_banner():
    console.print(Panel(
        f"[bold cyan]{APP_NAME}[/bold cyan] [dim]v{APP_VERSION}[/dim]\n"
        "[dim]Inspect, migrate and verify IMAP mailboxes[/dim]",
        border_style="cyan", box=box.DOUBLE, expand=False, padding=(0, 4)))


def main():
    show_banner()
    actions = {
        "1": ("List account folders and message counts", action_list_account),
        "2": ("Copy messages from source to destination", action_copy),
        "3": ("Verify source against destination", action_verify),
        "4": ("Batch copy multiple accounts from a CSV file", action_batch),
        "5": ("Create an unattended job file (scheduled runs)", action_create_job),
        "6": ("Manage saved connection profiles", action_profiles),
        "0": ("Exit", None),
    }
    while True:
        console.print()
        console.rule("[bold]Main menu[/bold]")
        for key, (label, _fn) in actions.items():
            style = "red" if key == "0" else "cyan"
            console.print(f"  [{style}]{key}[/{style}]  {label}")
        try:
            choice = Prompt.ask("\nChoose an option",
                                choices=list(actions.keys()), default="0")
        except (KeyboardInterrupt, EOFError):
            break
        if choice == "0":
            break
        _label, fn = actions[choice]
        try:
            fn()
        except (KeyboardInterrupt, EOFError):
            console.print("\n[yellow]Cancelled — back to the main menu.[/yellow]")
        except (ImapError, imaplib.IMAP4.error) as exc:
            log.error("menu action '%s' failed: %s", _label, exc)
            console.print(Panel(f"[red]{exc}[/red]", title="IMAP error",
                                border_style="red"))
        except Exception:
            log.exception("unexpected error in menu action '%s'", _label)
            console.print("[red]Unexpected error:[/red]")
            console.print_exception(max_frames=6)
    console.print("\n[cyan]Goodbye.[/cyan]")


# --------------------------------------------------------------------------
# Self-test (development aid): python imapsynchronizer.py --selftest
# --------------------------------------------------------------------------

def _selftest():
    assert imap_utf7_encode("Enviados") == "Enviados"
    assert imap_utf7_encode("Año") == "A&APE-o"
    assert imap_utf7_decode("A&APE-o") == "Año"
    assert imap_utf7_decode(imap_utf7_encode("Papelera & Más")) == "Papelera & Más"
    assert imap_utf7_encode("A&B") == "A&-B"
    assert imap_utf7_decode("A&-B") == "A&B"

    assert quote_mailbox('Sent Items') == '"Sent Items"'
    assert quote_mailbox('We "quote"') == '"We \\"quote\\""'

    assert parse_list_entry(b'(\\HasNoChildren) "/" INBOX') == \
        ("\\HasNoChildren", "/", "INBOX")
    assert parse_list_entry(b'(\\HasChildren \\Noselect) "." "[Gmail]"') == \
        ("\\HasChildren \\Noselect", ".", "[Gmail]")
    assert parse_list_entry(b'(\\HasNoChildren) "/" "Sent Items"') == \
        ("\\HasNoChildren", "/", "Sent Items")
    assert parse_list_entry(b'() NIL Notes') == ("", None, "Notes")
    assert parse_list_entry((b'(\\HasNoChildren) "/" {12}', b"Facturas 2024")) == \
        ("\\HasNoChildren", "/", "Facturas 2024")
    assert parse_list_entry(b"") is None
    assert parse_list_entry(b"garbage") is None

    k1 = message_key(b"Message-ID: <abc@x>\r\nFrom: a@b\r\n\r\n")
    assert k1 == "mid:<abc@x>"
    k2 = message_key(b"From: a@b\r\nSubject: hi\r\n\r\n")
    k3 = message_key(b"From: a@b\r\nSubject:  hi\r\n\r\n")
    assert k2.startswith("hdr:") and k2 == k3

    lines = build_tree_lines([
        (("INBOX",), 10, True),
        (("INBOX", "Sub"), 3, True),
        (("Archive",), 5, True),
        (("[Gmail]",), None, False),
        (("[Gmail]", "Sent"), 7, True),
    ])
    labels = [l for l, *_ in lines]
    assert labels[0].endswith("INBOX")
    assert any("Sub" in l for l in labels)
    text = tree_lines_as_text(lines)
    assert text[-1].endswith("25")

    assert sanitize_component("a/b", "/") == "a_b"
    assert sanitize_component("  ", "/") == "_"
    assert build_dest_parts(("INBOX", "Sub"), ["_IMAP-Synchronizer", "u_h"], "/") == \
        ("_IMAP-Synchronizer", "u_h", "INBOX", "Sub")
    assert sanitize_filename("user@example.com") == "user@example.com"

    assert strip_surrounding_quotes('"p;a,s ñ"') == "p;a,s ñ"
    assert strip_surrounding_quotes("'secret'") == "secret"
    assert strip_surrounding_quotes('ab"cd') == 'ab"cd'
    assert strip_surrounding_quotes('"unbalanced') == '"unbalanced'
    assert strip_surrounding_quotes('p,a;s"w') == 'p,a;s"w'
    assert strip_surrounding_quotes('""') == ""
    assert is_ascii("normal-Pass123!,;")
    assert not is_ascii("contraseña")

    assert normalize_host("imap.example.com") == ("imap.example.com", None)
    assert normalize_host(" imaps://mail.x.com/ ") == ("mail.x.com", None)
    assert normalize_host("imap://mail.x.com:143") == ("mail.x.com", 143)
    assert normalize_host("mail.x.com:993") == ("mail.x.com", 993)
    assert normalize_host("::1") == ("::1", None)
    assert normalize_host("mail.x.com:abc") == ("mail.x.com:abc", None)

    d1 = datetime(2020, 1, 5)
    d2 = datetime(2021, 12, 31)
    assert imap_date(d1) == "5-Jan-2020"
    assert build_date_criteria(d1, d2) == "(SINCE 5-Jan-2020 BEFORE 1-Jan-2022)"
    assert build_date_criteria(d1, None) == "(SINCE 5-Jan-2020)"
    assert build_date_criteria(None, d2) == "(BEFORE 1-Jan-2022)"
    assert build_date_criteria(None, None) is None
    assert parse_user_date("05/01/2020") == d1
    assert parse_user_date("2020-01-05") == d1
    try:
        parse_user_date("garbage")
        raise AssertionError("parse_user_date should have raised")
    except ValueError:
        pass

    mail = build_report_email(["IMAP migration report", "Línea con ñ"],
                              Account("h1", 993, "a@old.com", "x"),
                              Account("h2", 993, "b@new.com", "y"))
    parsed = BytesHeaderParser().parsebytes(mail)
    assert parsed["Subject"].startswith("Migration report: a@old.com")
    assert parsed["Message-ID"] and parsed["Date"]
    import email as _email
    full = _email.message_from_bytes(mail)
    body = full.get_payload(decode=True).decode("utf-8")
    assert "Línea con ñ" in body and APP_REPO_URL in body
    assert f"{APP_NAME} v{APP_VERSION}" in body and APP_OWNER in body

    ctx = {"ok": True, "rows": [("INBOX", 5, 4, 1, 0, 0),
                                ("Año 2024 <&>", 1, 1, 0, 0, 0)],
           "folder_errors": [], "verify_errors": [],
           "copied_into": "_IMAP-Synchronizer/u_h/", "date_filter": "none",
           "stamp": "2026-07-04 10:00:00", "elapsed": "0:00:10"}
    mail2 = build_report_email(["IMAP migration report", "Línea con ñ"],
                               Account("h1", 993, "a@old.com", "x"),
                               Account("h2", 993, "b@new.com", "y"),
                               html_ctx=ctx, attachment_name="report.txt")
    m2 = _email.message_from_bytes(mail2)
    parts = {}
    for p in m2.walk():
        parts.setdefault(p.get_content_type(), p)
    assert "text/plain" in parts and "text/html" in parts
    html_body = parts["text/html"].get_payload(decode=True).decode("utf-8")
    assert "VERIFIED OK" in html_body and APP_REPO_URL in html_body
    assert "Año 2024 &lt;&amp;&gt;" in html_body     # names are escaped
    # Every table cell must force its text color: dark-mode mail clients
    # inherit LIGHT text, invisible over the forced white backgrounds.
    cells = re.findall(r"<t[dh][^>]*>", html_body)
    assert cells and all("color:" in c for c in cells), \
        "an HTML report cell lacks an explicit text color"
    plain_body = parts["text/plain"].get_payload(decode=True).decode("utf-8")
    assert "Línea con ñ" in plain_body
    attachments = [p for p in m2.walk() if p.get_filename()]
    assert attachments and attachments[0].get_filename() == "report.txt"
    att_text = attachments[0].get_payload(decode=True).decode("utf-8")
    assert att_text.startswith("IMAP migration report")

    def _mkfolder(name, delim="/", flags=""):
        return Folder(raw=name, name=name, delimiter=delim,
                      parts=tuple(name.split(delim)), selectable=True,
                      flags=flags)

    src_fs = [_mkfolder("INBOX", "."),
              _mkfolder("INBOX.Sent", ".", "\\Sent"),
              _mkfolder("INBOX.Sent.2020", "."),
              _mkfolder("INBOX.Archive Docs.Clients", "."),
              _mkfolder("Notes", ".")]
    for f in src_fs:                      # dotted server: split by "."
        f.parts = tuple(f.name.split("."))
    dst_fs = [_mkfolder("INBOX"),
              _mkfolder("Sent Items", "/", "\\Sent"),
              _mkfolder("Projects")]
    mm = build_merge_map(src_fs, dst_fs, "/")
    assert mm[("INBOX",)] == ("INBOX",)
    assert mm[("INBOX", "Sent")] == ("Sent Items",)
    assert mm[("INBOX", "Sent", "2020")] == ("Sent Items", "2020")
    assert mm[("INBOX", "Archive Docs", "Clients")] == \
        ("Archive Docs", "Clients")
    assert mm[("Notes",)] == ("Notes",)
    # Destination that only knows folders under INBOX gets the prefix back.
    dst_inbox_only = [_mkfolder("INBOX", "."),
                      _mkfolder("INBOX.Sent", ".", "\\Sent")]
    for f in dst_inbox_only:
        f.parts = tuple(f.name.split("."))
    mm2 = build_merge_map(src_fs, dst_inbox_only, ".")
    assert mm2[("INBOX",)] == ("INBOX",)
    assert mm2[("INBOX", "Sent")] == ("INBOX", "Sent")
    assert mm2[("Notes",)] == ("INBOX", "Notes")
    assert mm2[("INBOX", "Archive Docs", "Clients")] == \
        ("INBOX", "Archive Docs", "Clients")

    names = ["INBOX", "INBOX.Sent", "INBOX.Trash.z TRART ARCHIVO^1and1"]
    assert parse_folder_exclusions("INBOX, 3", names) == ({0, 2}, [])
    assert parse_folder_exclusions("inbox.sent", names) == ({1}, [])
    assert parse_folder_exclusions('"INBOX", nope, 99', names) == \
        ({0}, ["nope", "99"])
    assert parse_folder_exclusions("INBOX.Trash.z TRART ARCHIVO^1and1",
                                   names) == ({2}, [])
    assert parse_folder_exclusions("", names) == (set(), [])

    inbox_f = _mkfolder("INBOX")
    legacy_f = _mkfolder("_IMAP_SYNC/u_h/INBOX")
    newroot_f = _mkfolder(MIGRATION_ROOT + "/u_h/INBOX")
    a1 = Account("h", 993, "u", "p")
    a2 = Account("h", 994, "u", "p")      # same host, DIFFERENT port
    assert exclude_sync_subtree_if_same_account(
        [inbox_f, legacy_f, newroot_f], a1, a1, quiet=True) == [inbox_f]
    assert exclude_sync_subtree_if_same_account(
        [inbox_f, legacy_f, newroot_f], a1, a2, quiet=True) == \
        [inbox_f, legacy_f, newroot_f]

    gmail_all = Folder(raw="[Gmail]/All Mail", name="[Gmail]/All Mail",
                       delimiter="/", parts=("[Gmail]", "All Mail"),
                       selectable=True, flags="\\HasNoChildren \\All")
    inbox = Folder(raw="INBOX", name="INBOX", delimiter="/",
                   parts=("INBOX",), selectable=True,
                   flags="\\HasNoChildren")
    trash = Folder(raw="Trash", name="Trash", delimiter="/",
                   parts=("Trash",), selectable=True, flags="")
    assert gmail_all.has_flag("\\All") and not inbox.has_flag("\\All")
    kept = filter_folders_unattended([gmail_all, inbox, trash], ["trash"])
    assert kept == [inbox]

    import tempfile
    with tempfile.NamedTemporaryFile("w", suffix=".csv", delete=False,
                                     newline="", encoding="utf-8") as fh:
        fh.write(BATCH_TEMPLATE)
        tmp_csv = fh.name
    try:
        rows = load_batch_rows(tmp_csv)
        assert len(rows) == 2
        assert rows[0]["src_password"] == "pass,word1"
        assert rows[1]["date_from"] == "2020-01-01"
    finally:
        os.unlink(tmp_csv)

    assert csv_flag("yes") and csv_flag("1") and csv_flag(" TRUE ")
    assert not csv_flag("") and not csv_flag(None) and not csv_flag("no")
    assert csv_flag("", default=True) and csv_flag(None, default=True)
    assert not csv_flag("no", default=True) and csv_flag("yes", default=True)

    assert parse_job_json('# note\n{\n  # inner\n  "a": 1\n}\n') == {"a": 1}
    assert parse_job_json('// slashes too\n{"a": "# not a comment"}') == \
        {"a": "# not a comment"}

    # ensure_path must NOT mistake Dovecot's "nonexistent namespace"
    # rejection for an "already exists" answer (real-world regression:
    # it silently skipped the INBOX-prefix fallback and every folder
    # of the migration failed afterwards).
    class _CreateStub:
        def __init__(self, response):
            self.response = response
        def create(self, name):
            return "NO", [self.response]
        def subscribe(self, name):
            return "OK", [b""]

    sess = ImapSession(Account("h", 993, "u", "p"))
    sess.conn = _CreateStub(
        b"Client tried to access nonexistent namespace. (Mailbox name "
        b"should probably be prefixed with: INBOX.)")
    sess._known_raw = set()
    try:
        sess.ensure_path(("_IMAP-Synchronizer",))
        raise AssertionError("namespace rejection must raise ImapError")
    except ImapError:
        pass
    for benign in (b"[ALREADYEXISTS] Mailbox already exists",
                   b"Mailbox already exists",
                   b"Can't create mailbox node: File exists"):
        sess.conn = _CreateStub(benign)
        sess._known_raw = set()
        assert sess.ensure_path(("_IMAP-Synchronizer",)) == "_IMAP-Synchronizer"

    assert append_flag_attempts(None) == [None]
    assert append_flag_attempts("\\Seen") == ["\\Seen", None]
    assert append_flag_attempts("\\Seen $Forwarded") == \
        ["\\Seen $Forwarded", "\\Seen", None]
    assert append_flag_attempts("$Label1") == ["$Label1", None]

    # Shipped example files must stay usable and in sync with the code.
    example_csv = SCRIPT_DIR / "batch_migrations.example.csv"
    if example_csv.exists():
        assert example_csv.read_text(encoding="utf-8") == BATCH_TEMPLATE, \
            "batch_migrations.example.csv is out of sync with BATCH_TEMPLATE"
    example_job = SCRIPT_DIR / "migration_job.example.json"
    if example_job.exists():
        cfg = parse_job_json(example_job.read_text(encoding="utf-8-sig"))
        for side in ("source", "destination"):
            assert cfg[side]["host"] and cfg[side]["user"]
            assert cfg[side].get("password_env") or cfg[side].get("password")
        assert isinstance(cfg.get("exclude_folders"), list)

    print("All self-tests passed.")


def _cli_file_arg(flag: str) -> str:
    idx = sys.argv.index(flag)
    if idx + 1 >= len(sys.argv):
        sys.stderr.write(f"Usage: python imapsynchronizer.py {flag} <file>\n")
        sys.exit(1)
    return sys.argv[idx + 1]


if __name__ == "__main__":
    if "--selftest" in sys.argv:
        _selftest()
        sys.exit(0)

    setup_error_log()
    exit_code = 0
    try:
        if "--job" in sys.argv:
            show_banner()
            exit_code = run_job(_cli_file_arg("--job"))
        elif "--batch" in sys.argv:
            show_banner()
            exit_code = run_batch(_cli_file_arg("--batch"), interactive=False)
        else:
            main()
    except KeyboardInterrupt:
        console.print("\n[yellow]Interrupted.[/yellow]")
        log.warning("session interrupted with Ctrl+C")
        exit_code = 130
    except SystemExit as exc:
        exit_code = exc.code if isinstance(exc.code, int) else 1
    except Exception:
        log.exception("uncaught error — session aborted")
        console.print("[red]Unexpected fatal error:[/red]")
        console.print_exception(max_frames=6)
        exit_code = 1
    finally:
        close_error_log(exit_code)
    sys.exit(exit_code)