pcode 0.1.0__py3-none-any.whl

pcode/email_remote/mailbox.py

@@ -0,0 +1,336 @@
+"""Gmail over IMAP and SMTP, and the app password in the macOS keychain.
+
+Gmail's IMAP extensions give what acceptance needs without the Gmail API's
+OAuth project: `X-GM-LABELS` carries the message-level `\\Sent` label,
+`X-GM-MSGID` a stable message id, and `X-GM-RAW` Gmail's own search. The
+listener reads only: the All Mail folder is opened read-only, and bodies are
+fetched with `BODY.PEEK`, so nothing is marked read or relabelled.
+
+The credential is a Gmail app password. It is read from the keychain by the
+listener alone; a remote host's sandbox cannot reach the keychain, and its
+environment never holds the password. There is no plaintext fallback.
+"""
+
+from __future__ import annotations
+
+import imaplib
+import re
+import shutil
+import smtplib
+import subprocess
+import sys
+from dataclasses import dataclass
+from email.message import EmailMessage
+from typing import Protocol, TypeAlias
+
+IMAP_HOST = "imap.gmail.com"
+SMTP_HOST = "smtp.gmail.com"
+KEYCHAIN_SERVICE = "pcode-email"
+TIMEOUT = 60
+
+
+class SetupError(RuntimeError):
+    """Something `pcode --email-setup` fixes; the message says what."""
+
+
+BAD_LOGIN = (
+    "Gmail rejected the app password for {owner}. Check that it was created while "
+    "signed in as {owner} (the app-passwords page opens in the browser's current "
+    "Google account), that 2-Step Verification is on, and that it was copied whole; "
+    "then run pcode --email-setup again."
+)
+
+
+def app_password(text: str) -> str:
+    """Google shows app passwords as `abcd efgh ijkl mnop`; pastes also bring
+    bracketed-paste markers. Neither belongs in the password."""
+    return re.sub(r"\x1b\[20[01]~|\s", "", text)
+
+
+@dataclass(frozen=True)
+class Meta:
+    """What the mailbox says about a message before its content is read."""
+
+    gmail_id: str
+    labels: frozenset[str]
+    size: int
+
+    @property
+    def sent(self) -> bool:
+        """The message itself was sent from the account (`\\Sent`), not delivered to it."""
+        return "\\Sent" in self.labels
+
+
+class Mailbox(Protocol):
+    """The listener's view of the account; `GmailMailbox` is the real one."""
+
+    def search(self, alias: str) -> list[str]: ...
+    def meta(self, handle: str) -> Meta: ...
+    def headers(self, handle: str) -> bytes: ...
+    def fetch(self, handle: str) -> bytes: ...
+    def send(self, message: EmailMessage) -> None: ...
+    def close(self) -> None: ...
+
+
+def _keychain() -> str:
+    if sys.platform != "darwin" or (tool := shutil.which("security")) is None:
+        raise SetupError(
+            "The email remote keeps its app password in the macOS keychain, which "
+            "this machine does not have. There is no plaintext fallback."
+        )
+    return tool
+
+
+def read_password(owner: str) -> str:
+    result = subprocess.run(
+        [_keychain(), "find-generic-password", "-s", KEYCHAIN_SERVICE, "-a", owner, "-w"],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode or not result.stdout.strip():
+        raise SetupError(f"No app password for {owner} in the keychain; run pcode --email-setup.")
+    return result.stdout.rstrip("\n")
+
+
+def store_password(owner: str) -> None:
+    """Ask for the app password on the terminal (`security` prompts; pcode never sees it)."""
+    subprocess.run(
+        [
+            _keychain(),
+            "add-generic-password",
+            "-U",
+            "-s",
+            KEYCHAIN_SERVICE,
+            "-a",
+            owner,
+            "-l",
+            "pcode email remote",
+            # Trust no application: every read, the listener's included, asks
+            # macOS first, so nothing else running as you reads it silently.
+            "-T",
+            "",
+            # Last, with no value: `security` prompts for it.
+            "-w",
+        ],
+        check=True,
+    )
+
+
+# Keep string values (quoted or literal bytes) distinct from protocol atoms
+# (str). In particular, label contents must never become FETCH field names.
+_TOKEN = re.compile(rb'\s+|[()]|"(?:[^"\\]|\\.)*"|[^\s()"{}]+')
+_Value: TypeAlias = str | bytes | list["_Value"]
+
+
+def _fetch_records(data: list) -> list[dict[str, _Value]]:
+    """Parse imaplib's tuple/literal fragments and continuations as records."""
+    records = []
+    root: list[_Value] = []
+    stack = [root]
+    for part in data:
+        if part is None:
+            continue
+        literal = None
+        if isinstance(part, tuple) and len(part) == 2:
+            fragment, literal = part
+            if not isinstance(fragment, bytes) or not isinstance(literal, bytes):
+                raise imaplib.IMAP4.error("Invalid FETCH literal")
+            marker = re.search(rb"\{([0-9]+)\}$", fragment)
+            if marker is None or int(marker[1]) != len(literal):
+                raise imaplib.IMAP4.error("Invalid FETCH literal length")
+            fragment = fragment[: marker.start()]
+        elif isinstance(part, bytes):
+            fragment = part
+        else:
+            raise imaplib.IMAP4.error("Invalid FETCH fragment")
+        index = 0
+        while index < len(fragment):
+            match = _TOKEN.match(fragment, index)
+            if match is None:
+                raise imaplib.IMAP4.error("Invalid FETCH syntax")
+            token = match[0]
+            index = match.end()
+            if token.isspace():
+                continue
+            if token == b"(":
+                child: list[_Value] = []
+                stack[-1].append(child)
+                stack.append(child)
+            elif token == b")":
+                if len(stack) == 1:
+                    raise imaplib.IMAP4.error("Unbalanced FETCH response")
+                stack.pop()
+                if len(stack) == 1:
+                    if (
+                        len(root) != 2
+                        or not isinstance(root[0], str)
+                        or not root[0].isascii()
+                        or not root[0].isdigit()
+                        or not isinstance(root[1], list)
+                    ):
+                        raise imaplib.IMAP4.error("Invalid FETCH record")
+                    values = root[1]
+                    if len(values) % 2:
+                        raise imaplib.IMAP4.error("Unpaired FETCH field")
+                    fields: dict[str, _Value] = {}
+                    for key, value in zip(values[::2], values[1::2]):
+                        if not isinstance(key, str) or key.upper() in fields:
+                            raise imaplib.IMAP4.error("Invalid or duplicate FETCH field")
+                        fields[key.upper()] = value
+                    records.append(fields)
+                    root.clear()
+            elif token.startswith(b'"'):
+                stack[-1].append(re.sub(rb"\\(.)", rb"\1", token[1:-1]))
+            else:
+                stack[-1].append(token.decode("ascii"))
+        if literal is not None:
+            if len(stack) == 1:
+                raise imaplib.IMAP4.error("FETCH literal outside a record")
+            stack[-1].append(literal)
+    if len(stack) != 1 or root:
+        raise imaplib.IMAP4.error("Incomplete FETCH response")
+    return records
+
+
+def _labels(fields: dict[str, _Value]) -> frozenset[str]:
+    values = fields.get("X-GM-LABELS", [])
+    if not isinstance(values, list):
+        raise imaplib.IMAP4.error("Invalid FETCH labels")
+    labels = []
+    for value in values:
+        if isinstance(value, list):
+            raise imaplib.IMAP4.error("Invalid FETCH label")
+        labels.append(value.decode() if isinstance(value, bytes) else value)
+    return frozenset(labels)
+
+
+def parse_labels(line: str) -> frozenset[str]:
+    """The `X-GM-LABELS (...)` list of a complete FETCH response."""
+    records = _fetch_records([line.encode()])
+    return _labels(records[0]) if records else frozenset()
+
+
+def _number(name: str, fields: dict[str, _Value]) -> str:
+    value = fields.get(name)
+    if not isinstance(value, str) or not value.isascii() or not value.isdigit():
+        raise imaplib.IMAP4.error(f"FETCH response without valid {name}")
+    return value
+
+
+def _message_records(data: list, handle: str) -> list[dict[str, _Value]]:
+    return [fields for fields in _fetch_records(data) if fields.get("UID") == handle]
+
+
+def _all_mail(imap: imaplib.IMAP4) -> str:
+    """The All Mail folder, found by its `\\All` flag (its name is localized)."""
+    status, lines = imap.list()
+    if status != "OK":
+        raise imaplib.IMAP4.error("LIST failed")
+    for raw in lines:
+        line = raw.decode() if isinstance(raw, bytes) else str(raw)
+        match = re.match(r'\((?P<flags>[^)]*)\) (?:"[^"]*"|NIL) (?P<name>.+)$', line)
+        if match and "\\All" in match.group("flags").split():
+            return match.group("name")
+    raise SetupError("This account has no All Mail folder over IMAP; is it Gmail?")
+
+
+class GmailMailbox:
+    """One owner's Gmail: an IMAP connection kept open, and SMTP per message sent."""
+
+    def __init__(self, owner: str, password: str) -> None:
+        self.owner = owner
+        self._password = app_password(password)
+        self._imap: imaplib.IMAP4 | None = None
+
+    def _connection(self) -> imaplib.IMAP4:
+        if self._imap is None:
+            imap = imaplib.IMAP4_SSL(IMAP_HOST, timeout=TIMEOUT)
+            try:
+                try:
+                    imap.login(self.owner, self._password)
+                except imaplib.IMAP4.error as error:
+                    if "AUTHENTICATIONFAILED" in str(error):
+                        raise SetupError(BAD_LOGIN.format(owner=self.owner)) from None
+                    raise
+                status, _ = imap.select(_all_mail(imap), readonly=True)
+                if status != "OK":
+                    raise imaplib.IMAP4.error("Could not open All Mail")
+            except BaseException:
+                imap.shutdown()
+                raise
+            self._imap = imap
+        return self._imap
+
+    def _command(self, name: str, *args) -> list:
+        """One IMAP command, reconnecting once if the connection dropped."""
+        for attempt in (1, 2):
+            try:
+                status, data = getattr(self._connection(), name)(*args)
+            except (imaplib.IMAP4.abort, OSError):
+                self.close()
+                if attempt == 2:
+                    raise
+                continue
+            if status != "OK":
+                raise imaplib.IMAP4.error(f"{name.upper()} {args[0] if args else ''} failed")
+            return data
+        raise AssertionError("unreachable")
+
+    def _uid(self, *args) -> list:
+        return self._command("uid", *args)
+
+    def verify(self) -> None:
+        """Log in and open All Mail, so setup fails now rather than at the first poll."""
+        self._connection()
+
+    def search(self, alias: str) -> list[str]:
+        # A selected mailbox is a snapshot: Gmail only adds mail that arrived
+        # since SELECT once the client polls, so without NOOP a long-lived
+        # connection searches the mailbox as it was at login.
+        self._command("noop")
+        data = self._uid("SEARCH", "X-GM-RAW", f'"to:{alias} newer_than:1d"')
+        return [uid.decode() for uid in (data[0] or b"").split()]
+
+    def meta(self, handle: str) -> Meta:
+        data = self._uid("FETCH", handle, "(X-GM-MSGID X-GM-LABELS RFC822.SIZE)")
+        for fields in _message_records(data, handle):
+            # An unsolicited FLAGS update for this UID is not our result.
+            if not {"X-GM-MSGID", "X-GM-LABELS", "RFC822.SIZE"} <= fields.keys():
+                continue
+            return Meta(
+                gmail_id=_number("X-GM-MSGID", fields),
+                labels=_labels(fields),
+                size=int(_number("RFC822.SIZE", fields)),
+            )
+        raise imaplib.IMAP4.error(f"No metadata for message {handle}")
+
+    def _literal(self, handle: str, item: str) -> bytes:
+        data = self._uid("FETCH", handle, f"({item})")
+        # PEEK is a request modifier, not part of the returned BODY field.
+        field = item.replace("BODY.PEEK[", "BODY[")
+        for fields in _message_records(data, handle):
+            value = fields.get(field)
+            if isinstance(value, bytes):
+                return value
+        raise imaplib.IMAP4.error(f"No content for message {handle}")
+
+    def headers(self, handle: str) -> bytes:
+        return self._literal(handle, "BODY.PEEK[HEADER]")
+
+    def fetch(self, handle: str) -> bytes:
+        return self._literal(handle, "BODY.PEEK[]")
+
+    def send(self, message: EmailMessage) -> None:
+        with smtplib.SMTP_SSL(SMTP_HOST, 465, timeout=TIMEOUT) as smtp:
+            smtp.login(self.owner, self._password)
+            # Only ever to the owner: never a recipient read from mail or a model.
+            smtp.send_message(message, from_addr=self.owner, to_addrs=[self.owner])
+
+    def close(self) -> None:
+        imap, self._imap = self._imap, None
+        if imap is None:
+            return
+        try:
+            imap.logout()
+        except (imaplib.IMAP4.error, OSError):
+            pass

pcode/email_remote/outbound.py

@@ -0,0 +1,75 @@
+"""The messages pcode sends: always from and to the owner, replies going to the alias.
+
+Recipients are fixed here and nowhere else: `From` and `To` are the owner,
+`Reply-To` the live alias. Nothing from an incoming message's headers or from
+model output can change them. Each message carries the marker header and
+`Auto-Submitted`, so neither pcode nor a well-behaved client loops on it, and a
+"Start new task" `mailto:` to the alias with no reply headers, which is how a
+second independent session starts.
+"""
+
+from __future__ import annotations
+
+from email.message import EmailMessage
+from email.utils import formataddr, make_msgid
+from urllib.parse import quote
+
+from pcode.email_remote.parsing import MARKER_HEADER
+from pcode.email_remote.render import document
+
+NEW_TASK_SUBJECT = "New pcode task"
+
+
+def new_task_link(alias: str) -> str:
+    return f"mailto:{alias}?subject={quote(NEW_TASK_SUBJECT)}"
+
+
+def new_message_id(owner: str) -> str:
+    return make_msgid("pcode", domain=owner.rpartition("@")[2] or None)
+
+
+def reply_subject(subject: str) -> str:
+    subject = subject.strip() or "pcode"
+    return subject if subject.lower().startswith("re:") else f"Re: {subject}"
+
+
+def compose(
+    *,
+    owner: str,
+    alias: str,
+    subject: str,
+    body: str,
+    trailer: str = "",
+    in_reply_to: str = "",
+    references: list[str] | None = None,
+    auto: str = "auto-replied",
+    message_id: str = "",
+) -> EmailMessage:
+    """Plain text (the Markdown as written) with a rendered HTML copy.
+
+    `body` is Markdown; `trailer` is preformatted session detail shown small
+    under it. The footer is added here. `message_id` reuses one planned
+    earlier (a retry); otherwise one is made.
+    """
+    message = EmailMessage()
+    message["From"] = formataddr(("pcode", owner))
+    message["To"] = owner
+    message["Reply-To"] = alias
+    message["Subject"] = subject
+    message["Message-ID"] = message_id or new_message_id(owner)
+    if in_reply_to:
+        message["In-Reply-To"] = in_reply_to
+        message["References"] = " ".join([*(references or []), in_reply_to])
+    message["Auto-Submitted"] = auto
+    message[MARKER_HEADER] = "1"
+    link = new_task_link(alias)
+    footer = (
+        "Reply to this email to continue. To start a separate session, "
+        f"write to the address this email replies to, or open: {link}"
+    )
+    text = body.rstrip()
+    if trailer.strip():
+        text += f"\n\n---\n{trailer.strip()}"
+    message.set_content(f"{text}\n\n--\n{footer}\n")
+    message.add_alternative(document(body, trailer, link), subtype="html")
+    return message

pcode/email_remote/parsing.py

@@ -0,0 +1,226 @@
+"""One raw email, parsed: the headers acceptance needs, and the new text of its body.
+
+Only the standard library's parser reads the message. Headers are taken as
+parsed, never from the body. The body's new text is what the owner wrote above
+Gmail's quoted copy of the thread; anything doubtful (no text part, quoted
+text only, too long) yields a reason instead of text, and the listener asks
+for a clean resend rather than guessing.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from email import policy
+from email.message import EmailMessage
+from email.parser import BytesParser
+from email.utils import getaddresses
+from html.parser import HTMLParser
+
+# The new text a message may carry, and the whole message pcode will fetch.
+MAX_TEXT_BYTES = 64 * 1024
+MAX_MESSAGE_BYTES = 2 * 1024 * 1024
+
+# Marks every message pcode sends, so it never takes one of its own as input.
+MARKER_HEADER = "X-Pcode-Remote"
+
+# Why a message has no usable text; the listener answers each with a resend request.
+EMPTY, MALFORMED, TOO_LONG = "empty", "malformed", "too-long"
+
+_LIST_HEADERS = ("List-Id", "List-Unsubscribe", "List-Post", "Mailing-List")
+_BULK = {"bulk", "list", "junk"}
+# A Gmail attribution: "On Mon, 1 Jan 2026 at 10:00, Name <a@b.c> wrote:", which
+# Gmail wraps onto two lines when long.
+_ATTRIBUTION = re.compile(r"^On .+wrote:\s*$", re.DOTALL)
+# Lines mobile clients add, dropped only as the very last line of the new text.
+_SENT_FROM = re.compile(r"^(Sent from my \w+|Sent from Gmail Mobile|Get Outlook for \w+)$")
+
+
+@dataclass
+class Incoming:
+    """What the listener reads from one message."""
+
+    message_id: str
+    subject: str
+    to: list[str]
+    senders: list[str]
+    # Ancestry: References, then In-Reply-To, without repeats.
+    ancestry: list[str]
+    marker: bool
+    auto_submitted: str
+    resent: bool
+    sender_header: list[str]
+    list_mail: bool
+    report: bool
+    # The new text, or "" with `problem` saying why there is none.
+    text: str = ""
+    problem: str = ""
+    attachments: list[str] = field(default_factory=list)
+
+
+def parse(raw: bytes) -> Incoming:
+    """The headers of `raw`; the body is left for `read_body`, once accepted."""
+    message = BytesParser(policy=policy.default).parsebytes(raw, headersonly=True)
+    senders = _addresses(message, "From")
+    if len(message.get_all("From") or []) != 1:
+        # Two From headers are as conflicting as two mailboxes in one.
+        senders.append("(conflicting)")
+    content_type = message.get_content_type()
+    return Incoming(
+        message_id=str(message.get("Message-ID", "") or "").strip(),
+        subject=" ".join(str(message.get("Subject", "") or "").split()),
+        to=_addresses(message, "To"),
+        senders=senders,
+        ancestry=_ancestry(message),
+        marker=MARKER_HEADER in message,
+        auto_submitted=str(message.get("Auto-Submitted", "") or "").strip().lower(),
+        resent=any(key.lower().startswith("resent-") for key in message.keys()),
+        sender_header=_addresses(message, "Sender"),
+        list_mail=any(key in message for key in _LIST_HEADERS)
+        or str(message.get("Precedence", "")).strip().lower() in _BULK,
+        report=content_type in ("multipart/report", "message/delivery-status"),
+    )
+
+
+def read_body(raw: bytes, incoming: Incoming) -> Incoming:
+    """Fill in the new text (or why there is none) and the attachment names."""
+    try:
+        message = BytesParser(policy=policy.default).parsebytes(raw)
+        text, attachments = _body(message)
+    except (LookupError, ValueError, UnicodeError, AttributeError):
+        incoming.problem = MALFORMED
+        return incoming
+    incoming.attachments = attachments
+    if text is None:
+        incoming.problem = EMPTY if attachments else MALFORMED
+        return incoming
+    new = new_text(text)
+    if not new:
+        incoming.problem = EMPTY
+    elif len(new.encode()) > MAX_TEXT_BYTES:
+        incoming.problem = TOO_LONG
+    else:
+        incoming.text = new
+    return incoming
+
+
+def _addresses(message: EmailMessage, name: str) -> list[str]:
+    values = [str(value) for value in message.get_all(name) or []]
+    return [address.strip().lower() for _, address in getaddresses(values) if address.strip()]
+
+
+def _ancestry(message: EmailMessage) -> list[str]:
+    ids: list[str] = []
+    for name in ("References", "In-Reply-To"):
+        for value in message.get_all(name) or []:
+            for found in re.findall(r"<[^<>\s]+>", str(value)):
+                if found not in ids:
+                    ids.append(found)
+    return ids
+
+
+def _body(message: EmailMessage) -> tuple[str | None, list[str]]:
+    """The best text part (plain preferred, else HTML as text), and attachment names."""
+    attachments = []
+    plain = rich = None
+    for part in message.walk():
+        if part.is_multipart():
+            continue
+        kind = part.get_content_type()
+        if part.get_content_disposition() == "attachment" or kind not in (
+            "text/plain",
+            "text/html",
+        ):
+            attachments.append(part.get_filename() or kind)
+        elif kind == "text/plain" and plain is None:
+            plain = part
+        elif kind == "text/html" and rich is None:
+            rich = part
+    if plain is not None:
+        return str(plain.get_content()), attachments
+    if rich is not None:
+        return html_text(str(rich.get_content())), attachments
+    return None, attachments
+
+
+class _TextExtractor(HTMLParser):
+    """Visible text with line breaks, minus Gmail's quoted thread and anything active."""
+
+    BLOCKS = {"p", "div", "br", "li", "tr", "h1", "h2", "h3", "h4", "h5", "h6", "pre"}
+    SKIPPED = {"script", "style", "head", "title", "blockquote"}
+    VOID = {"br", "img", "hr", "meta", "link", "input", "wbr", "col", "source"}
+
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self.parts: list[str] = []
+        # Open elements, and the depth at which a skipped subtree began.
+        self.stack: list[str] = []
+        self.skip_from: int | None = None
+
+    def handle_starttag(self, tag, attrs):
+        classes = (dict(attrs).get("class") or "").split()
+        if self.skip_from is None and (
+            tag in self.SKIPPED or "gmail_quote" in classes or "gmail_signature" in classes
+        ):
+            self.skip_from = len(self.stack)
+        if tag in self.BLOCKS and self.skip_from is None:
+            self.parts.append("\n")
+        if tag not in self.VOID:
+            self.stack.append(tag)
+
+    def handle_endtag(self, tag):
+        if tag not in self.stack:
+            return
+        while self.stack and self.stack.pop() != tag:
+            pass
+        if self.skip_from is not None and len(self.stack) <= self.skip_from:
+            self.skip_from = None
+            return
+        if tag in self.BLOCKS and self.skip_from is None:
+            self.parts.append("\n")
+
+    def handle_data(self, data):
+        if self.skip_from is None:
+            self.parts.append(data)
+
+
+def html_text(markup: str) -> str:
+    """Text from HTML, fetching nothing and dropping the quoted thread."""
+    extractor = _TextExtractor()
+    extractor.feed(markup)
+    extractor.close()
+    text = "".join(extractor.parts).replace("\xa0", " ")
+    lines = [line.rstrip() for line in text.splitlines()]
+    return re.sub(r"\n{3,}", "\n\n", "\n".join(lines)).strip()
+
+
+def new_text(text: str) -> str:
+    """What the owner wrote: above Gmail's attribution and quote, above a `-- ` signature.
+
+    Conservative: a quote is cut only where an attribution line ("On ... wrote:")
+    is followed by `>` lines, so quoted code or a `>` the owner typed stays. A
+    signature is cut only at the standard `-- ` delimiter, not at any `--` line.
+    """
+    lines = text.replace("\r\n", "\n").replace("\r", "\n").split("\n")
+    lines = _before_quote(lines)
+    if "-- " in lines:
+        lines = lines[: lines.index("-- ")]
+    while lines and not lines[-1].strip():
+        lines.pop()
+    if lines and _SENT_FROM.match(lines[-1].strip()):
+        lines.pop()
+    return "\n".join(lines).strip()
+
+
+def _before_quote(lines: list[str]) -> list[str]:
+    for index, line in enumerate(lines):
+        if not line.startswith("On "):
+            continue
+        # The attribution may wrap onto the next line.
+        for span in (1, 2):
+            if not _ATTRIBUTION.match("\n".join(lines[index : index + span])):
+                continue
+            rest = [later for later in lines[index + span :] if later.strip()]
+            if rest and rest[0].startswith(">"):
+                return lines[:index]
+    return lines