bot.py

#!/usr/bin/env python3

"""
Telepatch - a pass-through bridge between Telegram and Telegraph.

The bot stores nothing. A Telegraph access_token is the entire identity,
so it is round-tripped through Telegram's own message payloads:

  - deep link      t.me/<bot>?start=<token>     -> opens the manage menu
  - callback_data  "<action>:<token>"           -> 62 of the allowed 64 bytes
  - ForceReply     token hidden in a text_link  -> recovered from the reply

There is no database, no file written, no persistence layer, and nothing
kept in memory between updates. See /privacy and the notes in main().
"""

import asyncio
import json
import logging
import os
import random
import re
import time
from concurrent.futures import ThreadPoolExecutor
from datetime import date
from html.parser import HTMLParser
from urllib.parse import parse_qsl, quote, urlencode

import requests

from dotenv import load_dotenv

from telegram import (
    ForceReply,
    InlineKeyboardButton,
    InlineKeyboardMarkup,
    MessageEntity,
    Update,
)
from telegram.constants import ParseMode
from telegram.ext import (
    Application,
    CallbackQueryHandler,
    CommandHandler,
    ContextTypes,
    MessageHandler,
    TypeHandler,
    filters,
)


load_dotenv()

log = logging.getLogger("telepatch")


# A Telegraph token is 60 hex characters; a bot token is digits, a colon,
# then 35 or so. Both travel through message payloads by design, so both
# will reach exception text eventually.
SECRETS = re.compile(r"\b[0-9a-fA-F]{60}\b|\b\d{6,12}:[A-Za-z0-9_-]{30,}\b")


class Redact(logging.Filter):
    """
    Strip credentials from every log record, at the logging layer rather
    than at each of the places one could leak. A token that reaches a log
    file has escaped the design, so the last gate has to be unconditional.
    """

    def filter(self, record):
        if isinstance(record.msg, str):
            record.msg = SECRETS.sub("[redacted]", record.msg)

        if record.args:
            args = record.args if isinstance(record.args, tuple) else (record.args,)
            record.args = tuple(
                SECRETS.sub("[redacted]", a) if isinstance(a, str) else a
                for a in args
            )

        return True


def config(name, default=None, required=False):
    """
    Read one setting, and fail at startup rather than on first use. A bot
    that starts and then breaks on somebody's first command is worse than
    one that refuses to start.
    """

    value = (os.environ.get(name) or "").strip() or default

    if required and not value:
        raise SystemExit(
            f"{name} is not set. Copy .env.example to .env, or set it in "
            "the service unit."
        )

    return value


TELEGRAM_TOKEN = config("TELEGRAM_TOKEN", required=True)

if not re.fullmatch(r"\d{6,12}:[A-Za-z0-9_-]{30,}", TELEGRAM_TOKEN):
    raise SystemExit(
        "TELEGRAM_TOKEN does not look like a BotFather token "
        "(digits, a colon, then the secret)."
    )

# Where errors and heartbeats go. Both optional: without them the bot runs
# exactly as before, which is what a laptop wants and a server does not.
OPERATOR_CHAT = config("OPERATOR_CHAT")
HEARTBEAT_URL = config("HEARTBEAT_URL")
HEARTBEAT_SECONDS = int(config("HEARTBEAT_SECONDS", "300"))
LOG_LEVEL = config("LOG_LEVEL", "INFO").upper()


# -----------------------
# Activity counters
# -----------------------

# What telepatch-observer publishes. Read the privacy section of
# docs/superpowers/specs/2026-08-01-observer-design.md before touching any
# of this - the guarantee it describes lives here, not in the observer.
#
# THE RULE: tally() takes one argument and that argument must be a string
# literal from COUNTED. No token, chat id, user id, title, path or category
# may ever reach it, and no f-string or variable may ever be passed to it.
#
# This is not a convention. tests/test_observer_tally.py walks the AST of
# this file, finds every tally() call site, and fails if any argument is
# not a literal in the set below. An edit that interpolates a variable
# fails the suite rather than quietly publishing somebody's identity.
#
# Counters are RAM only. They are written to tmpfs (see export_counters)
# and systemd deletes that directory when this unit stops, so nothing here
# survives a restart. That is the property /privacy will describe.
COUNTED = frozenset({
    "command.total",       # any /command, without recording which person
    "page.published",      # a createPage that succeeded
    "index.rebuilt",       # an index rewritten by insert_entry
    "telegraph.call",      # every Telegraph API request
    "telegraph.failed",    # ... and the ones that did not come back
    "error",               # anything that reached on_error
})

COUNTS = {}

STARTED = time.time()

# Where the observer reads them from. tmpfs, created by
# RuntimeDirectory=telepatch in the unit and destroyed with the service.
COUNTERS_PATH = config("COUNTERS_PATH", "/run/telepatch/counters.json")


def tally(event):
    """
    One event happened. Which one, and nothing else about it.

    The increment is the privacy mechanism: `+= 1` is irreversible and
    retains nothing about the update that caused it. An unrecognised name
    is dropped rather than counted under itself, so a bad edit that gets
    past the test still cannot invent a new public key at runtime.
    """

    if event in COUNTED:
        COUNTS[event] = COUNTS.get(event, 0) + 1


def export_counters():
    """
    Hand the current counts to the observer.

    Written to a temporary file and renamed, because the observer reads on
    its own timer with no lock between us - rename is atomic, so it sees
    either the previous snapshot or this one, never half of one.

    Fails silently on purpose. No /run/telepatch means either a laptop or a
    unit without RuntimeDirectory=, and neither is a reason to take the bot
    down. The observer reports the absence as "not exporting", which is
    honest and visible.
    """

    payload = {"since": STARTED, "events": dict(COUNTS)}
    temporary = COUNTERS_PATH + ".tmp"

    try:
        os.makedirs(os.path.dirname(COUNTERS_PATH), exist_ok=True)

        with open(temporary, "w") as handle:
            json.dump(payload, handle)

        # The unit sets UMask=0077, so this would land as 0600 and only be
        # readable by root or by this account. That works while the observer
        # runs as root and silently stops working the moment it does not -
        # exactly the assumption RuntimeDirectoryMode=0755 was chosen to
        # avoid. The file holds counts and nothing else; there is nothing
        # in it to protect.
        os.chmod(temporary, 0o644)

        os.replace(temporary, COUNTERS_PATH)

    except OSError as error:
        log.debug("counters.export.failed error=%s", error)


TELEGRAPH_API = "https://api.telegra.ph"

SOURCE_URL = "https://github.com/babbworks/telepatch"

# The static site that renders a master post. The path after the hash is a
# Telegraph page path, so no credential ever appears in a shared URL.
SITE_URL = os.environ.get("SITE_URL", "https://babbworks.github.io/telepatch/")

# Separates a title from its categories in the generated master post. Chosen
# so the master post still reads naturally on telegra.ph.
INDEX_SEP = " — "

# The browser editor. Same origin as the site; the token rides in the
# fragment, which is never sent to a server and is stripped from Referer.
EDITOR_URL = SITE_URL.rstrip("/") + "/edit.html"

# A page tagged with this becomes a top-bar link on the site instead of an
# index entry, and the word itself is hidden when categories are displayed.
NAV_CATEGORY = "nav"

# Two more reserved words. An entry tagged with either leaves the index and
# joins the menu behind the globe at the right of the bar: "site" for
# another Telepatch collection, "web" for anywhere else worth reaching.
# Added with /link like any other entry.
#
# Authored, never discovered. A reader cannot enumerate somebody's
# collections - getPageList needs the token - so the only way one site can
# point at another is for its publisher to say so.
SITE_CATEGORY = "site"
WEB_CATEGORY = "web"

RESERVED_CATEGORIES = (NAV_CATEGORY, SITE_CATEGORY, WEB_CATEGORY)

# Ceiling on how many pages /site will read, to bound the rebuild.
INDEX_LIMIT = 200

# Written into every master post so the bot can recognise its own work on a
# later run. Plain text with no link: the website only collects anchors, so
# this never shows up as an index entry.
#
# It matters because Telegraph has no deletePage. A /site that created a new
# page each time would litter the account permanently, and every stray index
# would then be listed as an article by the next rebuild.
MASTER_MARK = "Index generated by Telepatch."

# Telegraph pages cannot be deleted, so an index that has been superseded is
# retired instead. Both marks exclude a page from being listed as an article;
# only MASTER_MARK makes a page eligible to be rewritten.
RETIRED_MARK = "Retired Telepatch index."

INDEX_MARKS = (MASTER_MARK, RETIRED_MARK)

# One token may own several collections. Exactly one is the primary: the
# index /site enumerates the whole account into, and the only one that
# existed before this field did. Every other carries this on its marker
# line and is curated by hand, through /link, /repo and the extension.
#
# An index written before multiple collections existed has no such field
# and is therefore primary, which is what makes this change reversible:
# remove the feature and the primary is still the only thing anything
# looks for. docs/multiple-collections.md records the way back.
EXTRA_FIELD = "collection=extra"

# Stands in for the list when an account has nothing published. Named so the
# masthead reader can tell it apart from the publisher's own prose.
EMPTY_NOTICE = "Nothing published yet."

# How the website renders an article's byline. A site-wide choice, because
# Telegraph gives a page only author_name and author_url — there is nowhere
# to record a display preference per article. It rides on the marker line so
# the master post still has exactly one machine-readable sentence.
#
#   linked    the name is a link to the author URL
#   separate  the name is plain and the URL is shown beside it
#   plain     the name only; the URL is stored but never displayed
BYLINE_MODES = ("linked", "separate", "plain")
BYLINE_DEFAULT = "linked"


# Carrier URL for the hidden token in ForceReply prompts. Never visited -
# it exists only so the token rides along as a message entity.
CARRIER = "https://telepat.ch/t"

# Telegraph field limits, straight from the API docs.
LIMITS = {
    "short_name": 32,
    "author_name": 128,
    "author_url": 512,
}

FIELD_LABELS = {
    "short_name": "short name",
    "author_name": "author name",
    "author_url": "author URL",
}

# Single-letter action codes. "<action>:<token>" is 62 bytes and
# callback_data allows 64, so these cannot grow to two letters.
ACTION_FIELDS = {
    "s": "short_name",
    "a": "author_name",
    "u": "author_url",
}

TITLE_LIMIT = 256

# Tags Telegraph accepts in page content. Anything else is unwrapped and
# only its children survive.
TELEGRAPH_TAGS = {
    "a", "aside", "b", "blockquote", "br", "code", "em", "figcaption",
    "figure", "h3", "h4", "hr", "i", "iframe", "img", "li", "ol", "p",
    "pre", "s", "strong", "u", "ul", "video",
}


# -----------------------
# Helpers
# -----------------------

def normalize_url(url):
    """
    Ensure URLs include http:// or https://
    """

    if not url:
        return None

    url = url.strip()

    if not url:
        return None

    if not url.startswith(("http://", "https://")):
        url = "https://" + url

    return url


def is_clear(value):
    """
    Telegraph clears a field when sent an empty string. Let the user ask
    for that explicitly, since a ForceReply cannot be answered with nothing.
    """

    return value.strip().lower() in {"-", "none", "clear", "blank"}


def telegraph_path(text):
    """
    Reduce a telegra.ph URL to the path Telegraph's public endpoints want.
    Accepts a full URL or a bare path.
    """

    text = text.strip().split("?")[0].split("#")[0].rstrip("/")

    if not text:
        return None

    return text.rsplit("/", 1)[-1] or None


def carrier_link(field, token="", **extras):
    """
    A one-glyph link whose href secretly carries the field being edited, the
    access token, and anything else the next step needs. The reply handler
    reads it back out of the entity.

    Unlike callback_data this has no length limit, which is what makes a
    per-post byline possible without remembering anything.
    """

    query = f"?{urlencode(extras)}" if extras else ""

    return f'<a href="{CARRIER}#{field}:{token}{query}">⁠·</a>'


def read_carrier(message):
    """
    Recover (field, token, extras) from the message this reply is answering.
    Returns (None, None, {}) when the reply is not to one of our prompts.
    """

    source = message.reply_to_message

    if not source:
        return None, None, {}

    for entity in source.entities or []:

        if entity.type != MessageEntity.TEXT_LINK:
            continue

        if not entity.url or not entity.url.startswith(CARRIER):
            continue

        head, _, query = entity.url.partition("#")[2].partition("?")

        field, _, token = head.partition(":")

        # keep_blank_values matters: an empty author URL is a real value,
        # not an absent one.
        return field, token, dict(parse_qsl(query, keep_blank_values=True))

    return None, None, {}


# A Telegraph access token is 60 characters. Loose enough to survive a
# change of alphabet, tight enough not to match ordinary prose.
TOKEN_RE = re.compile(r"[A-Za-z0-9_-]{60}")


def find_token(message):
    """
    Recover a token from the message this one replies to, so the user never
    has to paste it.

    The identity card carries the token three ways - as a code span, inside
    the deep-link button, and as plain text - so replying to it with any
    command is enough. Checked in order of confidence.
    """

    source = getattr(message, "reply_to_message", None)

    if not source:
        return None

    markup = getattr(source, "reply_markup", None)

    if markup:
        for row in markup.inline_keyboard:
            for button in row:

                if not button.url or "?start=" not in button.url:
                    continue

                candidate = button.url.split("?start=", 1)[1]

                if TOKEN_RE.fullmatch(candidate):
                    return candidate

    for entity in source.entities or []:

        if entity.type != MessageEntity.TEXT_LINK or not entity.url:
            continue

        if entity.url.startswith(CARRIER):

            # Stop at the "?": a carrier may hold extras after the token,
            # and taking everything past the colon swallowed them into it.
            # The malformed token then had the extras appended a second
            # time when the next carrier was built.
            token = entity.url.partition("#")[2].partition(":")[2] \
                .partition("?")[0]

            if TOKEN_RE.fullmatch(token):
                return token

        if "?start=" in entity.url:

            candidate = entity.url.split("?start=", 1)[1]

            if TOKEN_RE.fullmatch(candidate):
                return candidate

    found = TOKEN_RE.search(source.text or "")

    return found.group(0) if found else None


def token_hint(command):
    """
    Shown when a command needs a token and none could be recovered. Points
    at the reply route first, since pasting is the thing to avoid.
    """

    return (
        "Reply to your pinned identity message with "
        f"<code>{command}</code> and Telepatch will pick up the token "
        "from it.\n\n"
        "You can also open it with the <b>Manage this identity</b> button "
        f"on that message, or paste it directly: <code>{command} &lt;token&gt;</code>"
    )


# -----------------------
# Telegraph API
# -----------------------

# One connection, reused. Every call used to open a fresh TCP and TLS
# handshake to the same host, which on a 200-page scan is 200 handshakes.
SESSION = requests.Session()
SESSION.headers["User-Agent"] = "Telepatch (+https://github.com/babbworks/telepatch)"

# Retried only where a repeat cannot do damage. createPage and
# createAccount are excluded on purpose: a timeout tells us nothing about
# whether the write landed, and Telegraph has no way to delete the second
# page. editPage is safe because writing the same content twice is the
# same as writing it once.
NEVER_RETRY = {"createPage", "createAccount"}

RETRIES = 3
BACKOFF = 0.4


def _post(method, **params):
    """
    Every Telegraph method is a flat POST returning {ok, result|error}.

    Blocking, on purpose - the async wrapper below is what handlers use.
    This form is kept for the pooled workers, which are already off the
    event loop and would only be paying for a second hop.
    """

    url = f"{TELEGRAPH_API}/{method}"
    data = {k: v for k, v in params.items() if v is not None}

    attempts = 1 if method in NEVER_RETRY else RETRIES
    last = None

    # Every Telegraph request in the process funnels through here,
    # including the pooled workers that call _post directly rather than
    # going through telegraph(). Counting at this one choke point is what
    # keeps every tally() argument a literal - the alternative was
    # tally("telegraph." + method) at three call sites, which is exactly
    # the dynamic key the AST test exists to forbid.
    tally("telegraph.call")

    for attempt in range(attempts):

        try:
            response = SESSION.post(url, data=data, timeout=10)

            # Telegraph answering "no" is an answer, not a failure. Only a
            # broken conversation is worth trying again.
            if response.status_code < 500:
                payload = response.json()

                if not payload.get("ok"):
                    raise RuntimeError(payload.get("error", "unknown Telegraph error"))

                if method == "createPage":
                    tally("page.published")

                return payload["result"]

            last = RuntimeError(f"Telegraph returned {response.status_code}")

        except (requests.RequestException, ValueError) as error:
            last = error

        if attempt + 1 < attempts:
            time.sleep(BACKOFF * (2 ** attempt) + random.random() * 0.1)

    tally("telegraph.failed")

    log.warning("telegraph.failed method=%s attempts=%s error=%s",
                method, attempts, last)

    raise last if last else RuntimeError("Telegraph did not answer")


async def telegraph(method, **params):
    """
    What handlers call. requests is blocking and the bot now serves several
    people at once, so every call goes to a worker thread rather than
    stopping the event loop for up to ten seconds.
    """

    started = time.monotonic()

    try:
        return await asyncio.to_thread(_post, method, **params)

    finally:
        spent = (time.monotonic() - started) * 1000
        if spent > 1500:
            log.info("telegraph.slow method=%s ms=%.0f", method, spent)


async def get_account_info(access_token):
    """
    Note for publishing: createPage does NOT inherit the account's
    author_name / author_url. Only the telegra.ph web editor reads those.
    Any publish path must call this first and forward both explicitly,
    or the article renders with an empty byline and just a date.
    """

    return await telegraph(
        "getAccountInfo",
        access_token=access_token,
        fields='["short_name","author_name","author_url","page_count"]',
    )


# -----------------------
# Content conversion
# -----------------------

class _NodeBuilder(HTMLParser):
    """
    Turn Telegram's own HTML rendering of a message into Telegraph nodes.

    Using message.text_html means the bold, italics, links and code the
    user typed survive into the article - Telegram has already resolved
    its entities into markup, so there is no offset arithmetic to get wrong.
    """

    def __init__(self):

        super().__init__(convert_charrefs=True)

        self.root = []
        self.stack = [self.root]

    def handle_starttag(self, tag, attrs):

        if tag not in TELEGRAPH_TAGS:
            # Unsupported wrapper (span, tg-spoiler, tg-emoji): keep the
            # children, drop the tag, and mirror the stack so the matching
            # end tag still pops something.
            self.stack.append(self.stack[-1])
            return

        node = {"tag": tag, "children": []}

        href = dict(attrs).get("href")

        if tag == "a" and href:
            node["attrs"] = {"href": href}

        self.stack[-1].append(node)
        self.stack.append(node["children"])

    def handle_startendtag(self, tag, attrs):

        if tag in TELEGRAPH_TAGS:
            self.stack[-1].append({"tag": tag})

    def handle_endtag(self, tag):

        if len(self.stack) > 1:
            self.stack.pop()

    def handle_data(self, data):

        self.stack[-1].append(data)


# Telegraph's own /upload endpoint is closed to third parties (HTTP 400),
# so images have to be hotlinked from wherever they already live. Telegraph
# stores whatever src it is given and never validates it.
IMAGE_RE = re.compile(r"\.(jpe?g|png|gif|webp)(?:[?#]|$)", re.I)

TELEGRAPH_FILE = "telegra.ph/file/"

EMBED_PROVIDERS = (
    (re.compile(r"^https?://(?:www\.)?(?:youtube\.com|youtu\.be)/", re.I), "youtube"),
    (re.compile(r"^https?://(?:www\.)?vimeo\.com/", re.I), "vimeo"),
    (re.compile(r"^https?://(?:www\.)?(?:twitter\.com|x\.com)/", re.I), "twitter"),
)


def media_node(url, caption):
    """
    Build a <figure> for an image or a supported embed, or None if the URL
    is just an ordinary link that should stay inline.
    """

    if IMAGE_RE.search(url) or TELEGRAPH_FILE in url:
        inner = {"tag": "img", "attrs": {"src": url}}

    else:
        for pattern, provider in EMBED_PROVIDERS:

            if not pattern.match(url):
                continue

            # Telegraph's embed resolver predates the rename.
            target = url.replace("//x.com/", "//twitter.com/")

            inner = {
                "tag": "iframe",
                "attrs": {
                    "src": f"/embed/{provider}?url={quote(target, safe='')}"
                },
            }
            break

        else:
            return None

    children = [inner]

    if caption:
        children.append({"tag": "figcaption", "children": caption})

    return {"tag": "figure", "children": children}


def leading_url(para):
    """
    Return (url, caption_nodes) when a paragraph opens with a bare URL.

    Telegram auto-links URLs, so the first node is usually an <a>. Anything
    after the URL on that line becomes the caption, which makes the natural
    gesture - paste a link, type a few words - do the obvious thing.
    """

    if not para:
        return None, []

    first = para[0]

    if isinstance(first, dict):

        if first.get("tag") != "a":
            return None, []

        return first.get("attrs", {}).get("href"), list(para[1:])

    stripped = first.lstrip()

    if not stripped.startswith(("http://", "https://")):
        return None, []

    url, _, rest = stripped.partition(" ")

    caption = ([rest] if rest.strip() else []) + list(para[1:])

    return url, caption


# Telegram has no heading format of its own, so /post borrows Markdown's.
# h3 and h4 are the only headings Telegraph accepts, and they are what the
# website builds an article's contents from.
HEADING_RE = re.compile(r"^(#{1,3})\s+")


def as_heading(para):
    """
    Promote a paragraph opening with # to a heading. # and ## give h3, ###
    gives h4 - Telegraph offers nothing above h3, and the page title already
    occupies that level.
    """

    if not para or not isinstance(para[0], str):
        return None

    match = HEADING_RE.match(para[0].lstrip())

    if not match:
        return None

    tag = "h4" if len(match.group(1)) == 3 else "h3"

    # Strip the marker but keep any bold or links that followed it.
    first = para[0].lstrip()[match.end():]

    children = ([first] if first else []) + list(para[1:])

    if not any(
        not isinstance(c, str) or c.strip() for c in children
    ):
        return None

    return {"tag": tag, "children": children}


QUOTE_RE = re.compile(r"^>\s+")

# Block-level tags that must not end up wrapped in a <p>.
BLOCK_TAGS = {
    "blockquote", "pre", "aside", "h3", "h4", "ul", "ol", "hr", "figure",
}


def as_quote(para):
    """
    A paragraph opening with "> " becomes a blockquote.

    Telegram's own quote formatting already arrives as <blockquote>; this is
    for people who type the marker instead. A blockquote at the top of an
    article is read as its intro by the website, so the two authoring routes
    - the bot and the Telegraph editor - produce the same thing.
    """

    if not para or not isinstance(para[0], str):
        return None

    match = QUOTE_RE.match(para[0].lstrip())

    if not match:
        return None

    first = para[0].lstrip()[match.end():]
    children = ([first] if first else []) + list(para[1:])

    if not any(not isinstance(c, str) or c.strip() for c in children):
        return None

    return {"tag": "blockquote", "children": children}


def as_block(para):
    """
    Let a paragraph that is nothing but one block-level element through
    unwrapped. Telegram sends quotes and code blocks as real elements, and
    burying them in a <p> is neither valid nor what Telegraph renders well.
    """

    real = [n for n in para if not isinstance(n, str) or n.strip()]

    if len(real) != 1 or isinstance(real[0], str):
        return None

    return real[0] if real[0].get("tag") in BLOCK_TAGS else None


def as_media(para):
    """
    Promote a paragraph to a figure when it is just a media URL.
    """

    url, caption = leading_url(para)

    if not url:
        return None

    while caption and isinstance(caption[0], str) and not caption[0].strip():
        caption.pop(0)

    if caption and isinstance(caption[0], str):
        caption[0] = caption[0].lstrip(" -–—:")

    return media_node(url, caption)


def to_content(text_html):
    """
    Build a Telegraph content array, breaking into paragraphs on blank lines.

    Splitting happens only inside plain text nodes, so a bold run that
    straddles a blank line simply stays in one paragraph rather than
    producing broken markup.
    """

    builder = _NodeBuilder()
    builder.feed(text_html)
    # close() flushes anything the parser held back - text ending in a bare
    # "<" looks like the start of a tag and stays buffered otherwise.
    builder.close()

    paragraphs = []
    current = []

    for node in builder.root:

        if not isinstance(node, str):
            current.append(node)
            continue

        chunks = re.split(r"\n\s*\n", node)

        for index, chunk in enumerate(chunks):

            if index:
                paragraphs.append(current)
                current = []

            # Single newlines stay as line breaks within the paragraph.
            lines = chunk.split("\n")

            for line_index, line in enumerate(lines):

                if line_index:
                    current.append({"tag": "br"})

                if line:
                    current.append(line)

    paragraphs.append(current)

    content = []

    for para in paragraphs:

        if not any(not isinstance(n, str) or n.strip() for n in para):
            continue

        para = trim(para)

        content.append(
            as_heading(para) or as_quote(para) or as_media(para)
            or as_block(para) or {"tag": "p", "children": para}
        )

    return content or [{"tag": "p", "children": [""]}]


def trim(para):
    """
    Drop leading and trailing line breaks and blank strings.

    A stray newline - the blank line after the category line, say - would
    otherwise leave a <br> at the front of the paragraph, which hides the
    "#" or ">" marker from the classifiers and renders as an empty line.
    """

    def spare(node):
        if isinstance(node, str):
            return not node.strip()
        return isinstance(node, dict) and node.get("tag") == "br"

    out = list(para)

    while out and spare(out[0]):
        out.pop(0)

    while out and spare(out[-1]):
        out.pop()

    return out


def parse_categories(line):
    """
    Read line two as a category list, or return None to treat it as body.

    Deliberately narrow so ordinary prose is never swallowed: no sentence
    punctuation, and either one single word or a comma-separated list whose
    items are short.
    """

    line = (line or "").strip()

    if not line or len(line) > 80:
        return None

    if any(mark in line for mark in ".!?:;"):
        return None

    items = [item.strip() for item in line.split(",")]

    if any(not item for item in items):
        return None

    if len(items) == 1 and len(items[0].split()) > 1:
        return None

    if any(len(item.split()) > 3 for item in items):
        return None

    return items


def split_post(message):
    """
    Line one is the title. Line two is categories when it looks like a list.
    Everything after is the body.

    Categories are stored as an <aside> at the top of the page, which
    Telegraph renders as a centred italic subtitle and which the website can
    read straight back out. Returns (title, categories, content).
    """

    raw = (message.text or "").strip()

    if not raw:
        raise ValueError("Send a title on the first line, then the body.")

    lines = raw.split("\n")

    title = lines[0].strip()

    if not title:
        raise ValueError("The first line must be the title.")

    if len(title) > TITLE_LIMIT:
        raise ValueError(f"Title is too long (max {TITLE_LIMIT} characters).")

    categories = parse_categories(lines[1]) if len(lines) > 1 else None

    # text_html has the same line structure as text - tags never add newlines.
    html_lines = (message.text_html or "").split("\n")

    body_html = "\n".join(html_lines[2:] if categories else html_lines[1:])

    if not body_html.strip():
        raise ValueError(
            "That was only a title. Add the body on the lines below it."
        )

    content = to_content(body_html)

    if categories:
        content.insert(
            0, {"tag": "aside", "children": [", ".join(categories)]}
        )

    return title, categories, content


def node_text(node):
    """
    Flatten a Telegraph node back to plain text.
    """

    if isinstance(node, str):
        return node

    if not isinstance(node, dict):
        return ""

    return "".join(node_text(child) for child in node.get("children", []))


def page_categories(content):
    """
    Pull categories back out of a fetched page - the inverse of split_post.
    """

    for node in content or []:

        if not isinstance(node, dict):
            continue

        if node.get("tag") != "aside":
            continue

        text = node_text(node)

        return [item.strip() for item in text.split(",") if item.strip()]

    return []


# Roughly the pace of unhurried reading. Only ever shown rounded to minutes,
# so the exact figure matters less than being in the right neighbourhood.
WORDS_PER_MINUTE = 200

EXCERPT_LIMIT = 180


def page_words(content):
    """
    Word count for the whole article, categories and captions included -
    the difference is well below the rounding.
    """

    return len(" ".join(node_text(n) for n in content or []).split())


def page_excerpt(content, limit=EXCERPT_LIMIT):
    """
    The opening of the article, for the index.

    Skips the category aside and any leading image, since neither reads as
    a first sentence, and cuts on a word boundary.
    """

    parts = []
    total = 0

    for node in content or []:

        if not isinstance(node, dict):
            continue

        if node.get("tag") in ("aside", "figure", "h3", "h4"):
            continue

        text = " ".join(node_text(node).split())

        if not text:
            continue

        parts.append(text)
        total += len(text)

        if total > limit:
            break

    text = " ".join(parts)

    if len(text) <= limit:
        return text

    return text[:limit].rsplit(" ", 1)[0].rstrip(",.;:—– ") + "…"


# -----------------------
# Input parsing
# -----------------------

def parse_new_fields(text):
    """
    Turn one comma-separated message into (short_name, author_name, author_url).

    The user sends everything at once so the bot never has to hold partial
    state, e.g.  "mypub, Jane Doe, jane.example"

    Commas are strict separators, so names cannot contain them. Only the
    short name is required. Since short_name is private and an unset
    author_name publishes a bare date with no byline, the short name is
    reused as the byline when none is given.
    """

    parts = [part.strip() for part in text.split(",")]

    if len(parts) > 3:
        raise ValueError(
            "Too many commas. Send exactly:\n"
            "short name, author name, author url\n\n"
            "Commas cannot appear inside a name."
        )

    parts += [""] * (3 - len(parts))

    short_name, author_name, author_url = parts

    if not short_name:
        raise ValueError("A short name is required.")

    for field, value in (
        ("short_name", short_name),
        ("author_name", author_name),
        ("author_url", author_url),
    ):
        if len(value) > LIMITS[field]:
            raise ValueError(
                f"That {FIELD_LABELS[field]} is too long "
                f"(max {LIMITS[field]} characters)."
            )

    # An empty author_name renders as a byline-less page, so fall back to
    # the short name rather than publishing under nothing.
    return short_name, author_name or short_name, author_url


# -----------------------
# Views
# -----------------------

async def send_menu(target, token, note=None):
    """
    Read the account and offer one button per writable field. Every button
    re-supplies the token, so pressing one needs no server-side memory.
    """

    try:
        info = await get_account_info(token)

    except Exception as error:
        await target.reply_text(f"That token did not work:\n{error}")
        return

    # Telegram splits a row's width evenly between its buttons and offers no
    # width control, so long labels get a row to themselves rather than being
    # truncated. Short labels pair up.
    keyboard = InlineKeyboardMarkup([
        [
            InlineKeyboardButton("New post", callback_data=f"p:{token}"),
            InlineKeyboardButton("Post anonymous", callback_data=f"P:{token}"),
        ],
        [
            InlineKeyboardButton(
                "Post with a different byline", callback_data=f"c:{token}"
            ),
        ],
        [
            InlineKeyboardButton("My pages", callback_data=f"l:{token}"),
            InlineKeyboardButton("Build site", callback_data=f"g:{token}"),
        ],
        [
            InlineKeyboardButton("Upload image", callback_data=f"e:{token}"),
            InlineKeyboardButton("Write in browser", callback_data=f"W:{token}"),
        ],
        [
            InlineKeyboardButton("Short name", callback_data=f"s:{token}"),
            InlineKeyboardButton("Author name", callback_data=f"a:{token}"),
        ],
        [
            InlineKeyboardButton("Author URL", callback_data=f"u:{token}"),
            InlineKeyboardButton("Revoke token", callback_data=f"r:{token}"),
        ],
    ])

    lines = []

    if note:
        lines += [note, ""]

    lines += [
        "<b>Your Telepatch identity</b>",
        "",
        f"Short name: <b>{info.get('short_name') or '-'}</b> (private)",
        f"Byline: <b>{info.get('author_name') or '-'}</b>",
        f"Author URL: <b>{info.get('author_url') or '-'}</b>",
        f"Published pages: <b>{info.get('page_count', 0)}</b>",
    ]

    await target.reply_text(
        "\n".join(lines),
        parse_mode=ParseMode.HTML,
        reply_markup=keyboard,
    )


async def prompt_for(message, field, token):
    """
    Ask for one value with ForceReply, hiding the token in the prompt itself.
    """

    label = FIELD_LABELS[field]

    hint = (
        "This one cannot be empty, and it stays private."
        if field == "short_name"
        else "Send <code>-</code> to clear it."
    )

    await message.reply_text(
        f"Reply with the new {label}.\n{hint}{carrier_link(field, token)}",
        parse_mode=ParseMode.HTML,
        reply_markup=ForceReply(
            selective=True,
            input_field_placeholder=f"new {label}",
        ),
    )


async def prompt_revise(message, token, path):
    """
    editPage replaces the whole article, so ask for the whole thing.
    """

    try:
        page = await telegraph("getPage", path=path, return_content="false")

    except Exception as error:
        await message.reply_text(f"Could not find that page:\n{error}")
        return

    await message.reply_text(
        f"Revising <b>{page.get('title') or path}</b>\n\n"
        "Reply with the replacement: title on the first line, body below. "
        "This replaces the whole article - there is no partial edit.\n\n"
        f"Byline stays as <b>{page.get('author_name') or '(none)'}</b>."
        + carrier_link("revise", token, path=path),
        parse_mode=ParseMode.HTML,
        reply_markup=ForceReply(
            selective=True,
            input_field_placeholder="Title, then the body",
        ),
    )


async def prompt_byline(message, token):
    """
    Collect a byline that applies to the next post only. Nothing on the
    account changes - the values ride to the publish step in the carrier.
    """

    await message.reply_text(
        "Reply with the byline for this one post:\n\n"
        "<code>author name, author url</code>\n\n"
        "The URL is optional. Your saved byline is not changed."
        + carrier_link("byline", token),
        parse_mode=ParseMode.HTML,
        reply_markup=ForceReply(
            selective=True,
            input_field_placeholder="author name, author url",
        ),
    )


async def prompt_post(message, token, anonymous=False, override=None, site=None):
    """
    A ForceReply message cannot also carry an inline keyboard, so the
    browser-authoring link goes inline in the text as a hyperlink.
    """

    if anonymous:
        note = "This post will carry <b>no byline</b> - just a date."

    elif override:
        note = f"Byline for this post: <b>{override[0] or '(none)'}</b>"

    else:
        note = "This post will carry your saved byline."

    extras = {}

    if override:
        extras = {"n": override[0], "u": override[1]}

    # Which collection this is being written for. The carrier is a hidden
    # link with no length limit, so a path rides along freely - unlike a
    # button, where an action and a token already fill the 64 bytes.
    if site:
        extras["site"] = site
        note += "\n\nIt will be added to the collection you replied to."

    # The Telepatch editor needs nothing but the token, which is already
    # here. Telegraph's own editor needs a signed-in auth_url, which is a
    # round trip - and it expires in five minutes, so fetching it now for
    # a link most posts never follow would waste the call and the link.
    # /manage offers it on demand instead.
    browser = (
        "\n\nPrefer a real editor? "
        f'<a href="{EDITOR_URL}#{token}">Write in the Telepatch editor</a>.'
    )

    await message.reply_text(
        "Reply with your post.\n\n"
        "<b>First line is the title.</b> Everything below it is the body. "
        "Bold, italics and links you type here are kept.\n\n"
        "An image URL on its own line becomes a picture - add words after "
        "it for a caption. YouTube, Vimeo and Twitter links become embeds.\n\n"
        "A line starting <code>##</code> becomes a heading, and headings "
        "build the contents list on your site.\n\n"
        f"{note}"
        + carrier_link("anon" if anonymous else "post", token, **extras)
        + browser,
        parse_mode=ParseMode.HTML,
        disable_web_page_preview=True,
        reply_markup=ForceReply(
            selective=True,
            input_field_placeholder="Title, then the body",
        ),
    )


# -----------------------
# Commands
# -----------------------

async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """
    Bare /start welcomes. /start <token> is the deep link coming home.
    """

    if context.args:
        await send_menu(update.message, context.args[0].strip())
        return

    await update.message.reply_text(
        "<b>Welcome to Telepatch.</b>\n\n"

        "/new - create a Telepatch identity\n\n"

        "Once you have one, its message gets pinned in this chat. "
        "<b>Reply to that pinned message</b> with any of these and the "
        "token is picked up automatically:\n\n"

        "/post - publish an article\n"
        "/howto - how to write a post, in brief\n"
        "/pages - list what you have published\n"
        "/revise - rewrite a post (reply to its Published message)\n"
        "/site - build your public website index\n"
        "/manage - change your byline or revoke\n\n"

        "No identity needed at all:\n"
        "/views &lt;url&gt; - title, byline and views for any Telegraph page\n\n"

        "/privacy - what this bot keeps (nothing)\n"
        "/about - set your site's introduction\n"
        "/footer - set your site's footer\n"
        "/link - add a GitHub page to your index\n"
        "/repo - add a GitHub repository, as a dashboard\n"
        "/collections - list your collections\n"
        "/newsite - start another collection\n"
        "/unfile - take an entry out of a collection\n"
        "/retire - take a collection out of service\n"
        "/byline - how bylines show on your site\n"
        "/telepatch - about Telepatch",

        parse_mode=ParseMode.HTML,
    )


async def about(update: Update, context: ContextTypes.DEFAULT_TYPE):

    await update.message.reply_text(
        "Telepatch is a lightweight publishing bridge between Telegram, "
        "Telegraph, and the open web.\n\n"
        f"Source: {SOURCE_URL}"
    )


async def howto(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """
    The whole writing surface on one screen. Kept to a line or two per idea -
    anything longer stops being a reference and starts being documentation.
    """

    await update.message.reply_text(
        "<b>Writing a post</b>\n"
        "Reply to your pinned identity with /post.\n"
        "Line 1 is the title. Line 2 is categories if it reads like a list. "
        "Everything after is the body.\n\n"

        "<code>On the price of tin\n"
        "tin, industry\n\n"
        "&gt; What the ledgers say, against the usual account.\n\n"
        "The price held steady, then moved sharply.\n\n"
        "## What moved it\n\n"
        "Three things did.</code>\n\n"

        "<b>Formatting</b>\n"
        "Bold, italics, underline, strikethrough, links, code and quotes: "
        "type them in Telegram and they carry over.\n"
        "<code>#</code> or <code>##</code> starts a heading, "
        "<code>###</code> a subheading. Two or more build a contents list.\n"
        "A <code>&gt;</code> line right after the categories becomes the "
        "article's intro, shown under the title.\n\n"

        "<b>Pictures and video</b>\n"
        "An image URL alone on a line becomes a picture; words after it "
        "become the caption.\n"
        "YouTube, Vimeo and Twitter links alone on a line become embeds.\n"
        "No uploads here - /manage, then Upload image, opens the Telegraph "
        "editor. Best on a laptop.\n\n"

        "<b>Bylines</b>\n"
        "/manage offers New post for your saved byline, Post anonymous for "
        "none, or a different byline for one post.\n\n"

        "<b>Changing things afterwards</b>\n"
        "/revise - reply to a post's Published message to rewrite it.\n"
        "/about and /footer - the introduction and footer on your site.\n"
        "/site - refresh the index after publishing.\n"
        "/link - add a GitHub file or outward link to your index.\n"
        "/repo - add a whole repository: its files, and its README.",

        parse_mode=ParseMode.HTML,
    )


async def privacy(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """
    Claims a skeptic can check against the source, not vague reassurance.
    """

    await update.message.reply_text(
        "<b>What Telepatch keeps: nothing.</b>\n\n"

        "There is no database and no file is ever written. The bot holds "
        "nothing in memory between messages.\n\n"

        "Your Telegraph access token is your identity. Telepatch never "
        "stores it. It travels back and forth inside the Telegram messages "
        "themselves - in the button you press and the message you reply to. "
        "That is why every action starts from a message in this chat: there "
        "is nowhere else for it to come from.\n\n"

        "<b>What this does not protect you from</b>\n"
        "Telegram sees every message here, including your token, and keeps "
        "your chat history. Telegraph sees whatever you publish. Telepatch "
        "cannot change either of those.\n\n"

        "<b>Your short name is private.</b> It never appears on a published "
        "page - only your byline does, and you can publish with no byline "
        "at all.\n\n"

        "<b>Images are hotlinked, not copied.</b> Telepatch never receives "
        "or stores your files. An image URL in a post stays pointed at "
        "whoever hosts it, which means that host sees the IP address of "
        "everyone who reads your article. Uploading through the Telegraph "
        "editor instead keeps it on telegra.ph.\n\n"

        "/views needs no token at all, so you can use it without handing "
        "this bot any credential.\n\n"

        f"Read the code: {SOURCE_URL}",

        parse_mode=ParseMode.HTML,
        disable_web_page_preview=True,
    )


def token_for(update, context):
    """
    Prefer a pasted token, fall back to whatever the reply points at.

    A pasted token is recognised by its shape, never by its position.
    Several commands take words in the same place - /site and /newsite a
    title, /byline a mode - and taking the first of them as a token sent
    Telegraph the word "Browser" and got back ACCESS_TOKEN_INVALID.
    """

    if context.args:

        first = context.args[0].strip()

        if TOKEN_RE.fullmatch(first):
            return first

    return find_token(update.message)


def command_words(context):
    """
    The words after a command, with a pasted token dropped from the front
    so it cannot end up inside a title.
    """

    args = list(context.args or [])

    if args and TOKEN_RE.fullmatch(args[0].strip()):
        args = args[1:]

    return " ".join(args).strip()


async def manage(update: Update, context: ContextTypes.DEFAULT_TYPE):

    token = token_for(update, context)

    if not token:
        await update.message.reply_text(
            token_hint("/manage"),
            parse_mode=ParseMode.HTML,
        )
        return

    await send_menu(update.message, token)


async def post(update: Update, context: ContextTypes.DEFAULT_TYPE):

    token = token_for(update, context)

    if not token:
        await update.message.reply_text(
            token_hint("/post"),
            parse_mode=ParseMode.HTML,
        )
        return

    # Replying to a collection writes for that collection. Replying to the
    # identity writes for the primary, which lists everything anyway.
    _, _, extras = read_carrier(update.message)

    await prompt_post(update.message, token, site=extras.get("site"))


async def new(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """
    Accepts everything inline (/new a, b, c) or prompts for one comma line.
    """

    if context.args:
        await create_identity(update.message, " ".join(context.args))
        return

    await update.message.reply_text(
        "Send all three at once, separated by commas:\n\n"
        "<code>short name, author name, author url</code>\n\n"
        "Example:\n"
        "<code>mypub, Jane Doe, jane.example</code>\n\n"
        "Only the short name is required, and it stays private. "
        "The author name is the byline shown on your articles - "
        "leave it out and the short name is used instead."
        + carrier_link("new"),
        parse_mode=ParseMode.HTML,
        reply_markup=ForceReply(
            selective=True,
            input_field_placeholder="short name, author, url",
        ),
    )


async def find_site(update, context, command):
    """
    The index path for a command that edits it. Replying to the pinned Site
    message supplies it for free; otherwise it has to be hunted for.
    Returns (token, path) with either possibly None, having already replied.
    """

    token = token_for(update, context)

    if not token:
        await update.message.reply_text(
            token_hint(command),
            parse_mode=ParseMode.HTML,
        )
        return None, None

    _, _, extras = read_carrier(update.message)

    path = extras.get("site")

    if not path:
        notice = await update.message.reply_text("Finding your index…")
        scanned = await asyncio.to_thread(scan_pages, token)
        indexes = list_indexes(scanned)

        if not indexes:
            await notice.edit_text(
                f"You have no index yet. Run /site first, then {command}."
            )
            return token, None

        # With several collections there is no safe guess to make. /about
        # and /footer overwrite prose, so picking the wrong one destroys
        # writing rather than merely surprising somebody.
        if len(indexes) > 1:
            await notice.edit_text(
                f"You have {len(indexes)} collections, so {command} needs to "
                "know which one.\n\nRun /collections and reply to the one you "
                f"mean with {command}.",
            )
            return token, None

        await notice.delete()
        path = indexes[0]["path"]

    return token, path


async def about_site(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """
    Set the introduction that appears above the index on your site.
    """

    token, path = await find_site(update, context, "/about")

    if not path:
        return

    await update.message.reply_text(
        "Reply with the introduction for your site.\n\n"
        "It appears under the title, above your list of posts. "
        "Bold, italics and links are kept.\n\n"
        "Send <code>-</code> to remove it."
        + carrier_link("about", token, site=path),
        parse_mode=ParseMode.HTML,
        reply_markup=ForceReply(
            selective=True,
            input_field_placeholder="a sentence or two",
        ),
    )


async def link_cmd(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """
    Add an entry to the index that is not a Telegraph page.

    A GitHub link is rendered by the website as an article, read live at
    the moment someone opens it. Any other link is listed and opens
    outward. Either way the entry is an ordinary item in the master post's
    list, so /site keeps it.
    """

    token, path = await find_site(update, context, "/link")

    if not path:
        return

    await update.message.reply_text(
        "Reply with the entry, a line at a time:\n\n"
        "<code>https://github.com/owner/repo\n"
        "How this site is built\n"
        "code, live\n\n"
        "A sentence for the index.</code>\n\n"
        "Line 1 the address, line 2 the title, line 3 categories if it "
        "reads like a list, anything after that the excerpt.\n\n"
        "A GitHub repository opens as a dashboard — overview, code, issues, "
        "releases and activity. A file link means that file."
        + carrier_link("link", token, site=path),
        parse_mode=ParseMode.HTML,
        disable_web_page_preview=True,
        reply_markup=ForceReply(
            selective=True,
            input_field_placeholder="address, title, categories",
        ),
    )


async def add_external(message, token, path):
    """
    Splice one entry into the index list, dated today so it sorts newest.
    """

    lines = [line.strip() for line in (message.text or "").split("\n")]
    lines = [line for line in lines if line or True]

    url = normalize_url(lines[0]) if lines else None

    # normalize_url will happily put https:// in front of anything, so the
    # result has to look like a host before it goes into somebody's index.
    if not url or not re.match(r"^https?://[^\s/]+\.[^\s/]+", url):
        await message.reply_text(
            "The first line needs to be a web address, like\n"
            "<code>https://github.com/owner/repo</code>",
            parse_mode=ParseMode.HTML,
        )
        return

    title = lines[1].strip() if len(lines) > 1 else ""

    if not title:
        await message.reply_text("The second line needs to be a title.")
        return

    categories = parse_categories(lines[2]) if len(lines) > 2 else None

    rest = lines[(3 if categories else 2):]
    excerpt = " ".join(part for part in rest if part).strip()

    kind = "read live from GitHub" if "github.com" in url else "an outward link"

    await splice_entry(message, token, path, url, title, categories, excerpt, kind)


def insert_entry(token, path, url, title, categories, excerpt, minutes=0):
    """
    Put one entry at the top of an index list, dated today so it sorts
    newest. Raises rather than replying, so it can be used from a command
    that has its own message to send.

    editPage replaces a page wholesale, so everything else the index
    carries - masthead, footer, byline mode, whether it is a curated
    collection, author fields - is read first and written back with it.
    """

    page = _post("getPage", path=path, return_content="true")

    head, middle, foot = split_master(page.get("content"))

    listing = middle[0] if middle and middle[0].get("tag") == "ul" else None

    if listing is None:
        listing = {"tag": "ul", "children": []}
        middle = [listing]

    children = [
        {"tag": "a", "attrs": {"href": url}, "children": [title]}
    ]

    meta = INDEX_SEP + date.today().isoformat()

    # Reading time only when it is ours to claim: we counted the words of a
    # page published here, and cannot honestly guess at somebody else's.
    if minutes:
        meta += f" · {minutes} min"

    if categories:
        meta += " · " + ", ".join(categories)

    children.append(meta)

    if excerpt:
        children.append({"tag": "br"})
        children.append(excerpt)

    listing.setdefault("children", []).insert(
        0, {"tag": "li", "children": children}
    )

    _post(
        "editPage",
        access_token=token,
        path=path,
        title=page["title"],
        content=json.dumps(
            head + middle + foot + [kept_marker(page.get("content"))]
        ),
        author_name=page.get("author_name") or "",
        author_url=page.get("author_url") or "",
    )

    tally("index.rebuilt")

    return page["title"]


async def splice_entry(message, token, path, url, title, categories, excerpt, kind):
    """
    insert_entry, with the replies a command needs around it.
    """

    try:
        await asyncio.to_thread(
            insert_entry, token, path, url, title, categories, excerpt
        )

    except Exception as error:
        await message.reply_text(f"Could not add it:\n{error}")
        return

    await message.reply_text(
        f"<b>{title}</b> added to your index - {kind}.\n\n"
        f"{SITE_URL}#{path}\n\n"
        "Reply to this message with /link or /repo to add another."
        + carrier_link("page", token, site=path),
        parse_mode=ParseMode.HTML,
        disable_web_page_preview=True,
    )


# A bare "owner/repo", or any github.com address for one. Verified against
# the API afterwards, so this only has to recognise the shape.
GH_REPO_RE = re.compile(
    r"^(?:https?://)?(?:www\.)?(?:github\.com/)?"
    r"([A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?)/([A-Za-z0-9._-]+?)(?:\.git)?/?$"
)


def github_repo(line):
    """(owner, repo) from a bare name or a github.com address, else None."""

    match = GH_REPO_RE.match((line or "").strip())
    return (match.group(1), match.group(2)) if match else None


def github_about(owner, repo):
    """
    What GitHub says the repository is for.

    Returns (description, exists). Anonymous calls are limited to sixty an
    hour, so anything other than a clear 404 is treated as "it is there,
    but we could not read the description" - a rate limit is no reason to
    refuse somebody their own repository.
    """

    try:
        response = requests.get(
            f"https://api.github.com/repos/{owner}/{repo}",
            headers={"Accept": "application/vnd.github+json"},
            timeout=10,
        )

    except Exception:
        return None, True

    if response.status_code == 404:
        return None, False

    if response.status_code != 200:
        return None, True

    return (response.json().get("description") or "").strip() or None, True


async def repo_cmd(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """
    Add a GitHub repository to the index.

    The website shows a repository as its file listing with the README
    underneath, both read at the moment somebody opens the page, so the
    entry stays current without anyone republishing it.
    """

    token, path = await find_site(update, context, "/repo")

    if not path:
        return

    await update.message.reply_text(
        "Reply with the repository:\n\n"
        "<code>babbworks/telepatch</code>\n\n"
        "That line on its own is enough - the name and description come "
        "from GitHub. To write them yourself, add more lines:\n\n"
        "<code>babbworks/telepatch\n"
        "How this site is built\n"
        "code, live\n\n"
        "A sentence for the index.</code>"
        + carrier_link("repo", token, site=path),
        parse_mode=ParseMode.HTML,
        disable_web_page_preview=True,
        reply_markup=ForceReply(
            selective=True,
            input_field_placeholder="owner/repo",
        ),
    )


async def add_repo(message, token, path):
    """
    Check the repository is really there, then splice it into the index.
    """

    lines = [line.strip() for line in (message.text or "").split("\n")]
    found = github_repo(lines[0]) if lines else None

    if not found:
        await message.reply_text(
            "The first line needs to be a repository, like\n"
            "<code>babbworks/telepatch</code>",
            parse_mode=ParseMode.HTML,
        )
        return

    owner, repo = found
    description, exists = github_about(owner, repo)

    if not exists:
        await message.reply_text(
            f"GitHub has no public repository called {owner}/{repo}."
        )
        return

    title = (lines[1] if len(lines) > 1 else "") or repo
    categories = parse_categories(lines[2]) if len(lines) > 2 else None

    rest = lines[(3 if categories else 2):]
    excerpt = " ".join(part for part in rest if part).strip() or description or ""

    await splice_entry(
        message, token, path,
        f"https://github.com/{owner}/{repo}",
        title, categories, excerpt,
        "its overview, code, issues, releases and activity, read live from GitHub",
    )


async def byline_site(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """
    Choose how the website shows an article's byline.

    Site-wide rather than per-article: a Telegraph page has room for a name
    and a URL and nothing else, so there is no per-page slot for a display
    choice. It lives on the master post's marker line instead.
    """

    token, path = await find_site(update, context, "/byline")

    if not path:
        return

    try:
        page = await telegraph("getPage", path=path, return_content="true")

    except Exception as error:
        await update.message.reply_text(f"Could not find your index:\n{error}")
        return

    current = read_byline(page.get("content"))
    wanted = context.args[0].lower().strip() if context.args else ""

    if wanted not in BYLINE_MODES:
        await update.message.reply_text(
            f"Byline is <b>{current}</b>.\n\n"
            "<code>/byline linked</code> - the name links to the author URL\n"
            "<code>/byline separate</code> - the name plain, URL shown beside it\n"
            "<code>/byline plain</code> - the name only\n\n"
            "This applies to every article on your site.",
            parse_mode=ParseMode.HTML,
        )
        return

    head, middle, foot = split_master(page.get("content"))

    try:
        await telegraph(
            "editPage",
            access_token=token,
            path=path,
            title=page["title"],
            content=json.dumps(
                head + middle + foot
                + [kept_marker(page.get("content"), wanted)]
            ),
            author_name=page.get("author_name") or "",
            author_url=page.get("author_url") or "",
        )

    except Exception as error:
        await update.message.reply_text(f"Could not save it:\n{error}")
        return

    await update.message.reply_text(
        f"Bylines are now <b>{wanted}</b>.\n\n{SITE_URL}#{path}"
        + carrier_link("page", token, site=path),
        parse_mode=ParseMode.HTML,
        disable_web_page_preview=True,
    )


async def footer_site(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """
    Set the note that appears at the foot of every page on your site.
    """

    token, path = await find_site(update, context, "/footer")

    if not path:
        return

    await update.message.reply_text(
        "Reply with the footer for your site.\n\n"
        "It appears at the bottom of every page, above the Telepatch line. "
        "Bold, italics and links are kept.\n\n"
        "Send <code>-</code> to remove it."
        + carrier_link("footer", token, site=path),
        parse_mode=ParseMode.HTML,
        reply_markup=ForceReply(
            selective=True,
            input_field_placeholder="a line or two",
        ),
    )


async def set_footer(message, token, path):
    """
    Replace the closing note, leaving the masthead and the generated list
    alone. Two requests rather than a full rescan.
    """

    try:
        page = await telegraph("getPage", path=path, return_content="true")

    except Exception as error:
        await message.reply_text(f"Could not find your index:\n{error}")
        return

    text = message.text.strip()

    footer = [] if is_clear(text) else to_content(message.text_html or text)

    head, middle, _ = split_master(page.get("content"))

    content = head + middle + footer + [
        kept_marker(page.get("content"))
    ]

    try:
        await telegraph(
            "editPage",
            access_token=token,
            path=path,
            title=page["title"],
            content=json.dumps(content),
            author_name=page.get("author_name") or "",
            author_url=page.get("author_url") or "",
        )

    except Exception as error:
        await message.reply_text(f"Could not save it:\n{error}")
        return

    await message.reply_text(
        ("Footer removed." if not footer else "Footer saved.")
        + f"\n\n{SITE_URL}#{path}\n\n"
        "Reply to this message with /footer to change it again."
        + carrier_link("page", token, site=path),
        parse_mode=ParseMode.HTML,
        disable_web_page_preview=True,
    )


async def set_masthead(message, token, path):
    """
    Replace the introduction, leaving the generated list untouched. Splicing
    rather than rebuilding keeps this to two requests instead of hundreds.
    """

    try:
        page = await telegraph("getPage", path=path, return_content="true")

    except Exception as error:
        await message.reply_text(f"Could not find your index:\n{error}")
        return

    text = message.text.strip()

    masthead = [] if is_clear(text) else to_content(message.text_html or text)

    _, middle, foot = split_master(page.get("content"))
    rest = middle + foot + [kept_marker(page.get("content"))]

    try:
        await telegraph(
            "editPage",
            access_token=token,
            path=path,
            title=page["title"],
            content=json.dumps(masthead + rest),
            author_name=page.get("author_name") or "",
            author_url=page.get("author_url") or "",
        )

    except Exception as error:
        await message.reply_text(f"Could not save it:\n{error}")
        return

    await message.reply_text(
        ("Introduction removed." if not masthead else "Introduction saved.")
        + f"\n\n{SITE_URL}#{path}\n\n"
        "Reply to this message with /about to change it again."
        + carrier_link("page", token, site=path),
        parse_mode=ParseMode.HTML,
        disable_web_page_preview=True,
    )


async def site(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """
    /site builds the master post. Replying to a previous Site message finds
    it and rewrites it in place; otherwise a new one is created.

    Any words after the command become the site title, which otherwise
    defaults to the short name - the one use that makes it public, and only
    because the publisher chose to.
    """

    token = token_for(update, context)

    if not token:
        await update.message.reply_text(
            token_hint("/site"),
            parse_mode=ParseMode.HTML,
        )
        return

    _, _, extras = read_carrier(update.message)

    # A pasted token is dropped, so "/site <token> A Name" names the site
    # rather than calling it after the token.
    title = command_words(context) or None

    # A rebuild trusts what the index already recorded. That is wrong only
    # for a page edited outside the bot, so there has to be a way to say so.
    refresh = bool(title) and title.lower() in ("refresh", "rescan")

    if refresh:
        title = None

    await rebuild_site(
        update.message,
        token,
        master_path=extras.get("site"),
        title=title,
        refresh=refresh,
    )


async def collections_cmd(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """
    List every collection on this identity.

    One message each rather than one message with buttons: callback_data is
    capped at 64 bytes and an action plus a token already uses 62, so a
    path cannot ride along with it. Each message carries its own path in a
    hidden link instead, which is what makes it repliable.
    """

    token = token_for(update, context)

    if not token:
        await update.message.reply_text(
            token_hint("/collections"), parse_mode=ParseMode.HTML
        )
        return

    notice = await update.message.reply_text("Reading your account…")

    try:
        scanned = await asyncio.to_thread(scan_pages, token)

    except Exception as error:
        await notice.edit_text(f"Could not read your pages:\n{error}")
        return

    indexes = list_indexes(scanned)

    if not indexes:
        await notice.edit_text(
            "You have no collections yet. Run /site to build your first."
        )
        return

    # Edited rather than deleted and replaced: two API calls become one,
    # and the chat stops flickering.
    await notice.edit_text(
        f"<b>{len(indexes)} collection{'' if len(indexes) == 1 else 's'}.</b>\n"
        "Reply to any of these with /about, /footer, /byline, /link, /repo, "
        "/post or /site.",
        parse_mode=ParseMode.HTML,
    )

    for at, index in enumerate(indexes):

        kind = ("curated - entries are added by hand" if index["extra"]
                else "primary - /site enumerates everything you publish here")

        # Telegram allows about one message a second to a chat before it
        # starts issuing flood waits. One message each is deliberate - a
        # path cannot ride in a button, at 62 of the allowed 64 bytes -
        # but sending them all at once was not.
        if at:
            await asyncio.sleep(1.1)

        await update.message.reply_text(
            f"<b>{index['title']}</b>\n{kind}\n\n"
            f"{SITE_URL}#{index['path']}"
            + carrier_link("page", token, site=index["path"]),
            parse_mode=ParseMode.HTML,
            disable_web_page_preview=True,
        )


async def newsite(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """
    Start a second collection on this identity.

    It begins empty and stays that way until something is put in it. Only
    the primary enumerates the account, or every collection would hold the
    same thing.
    """

    token = token_for(update, context)

    if not token:
        await update.message.reply_text(
            token_hint("/newsite"), parse_mode=ParseMode.HTML
        )
        return

    title = command_words(context)

    if not title:
        await update.message.reply_text(
            "Give the collection a name:\n\n"
            "<code>/newsite Reading notes</code>",
            parse_mode=ParseMode.HTML,
        )
        return

    try:
        info = await get_account_info(token)

    except Exception as error:
        await update.message.reply_text(f"That token did not work:\n{error}")
        return

    content = [
        {"tag": "ul", "children": []},
        marker_node(BYLINE_DEFAULT, extra=True),
    ]

    try:
        page = await telegraph(
            "createPage",
            access_token=token,
            title=title,
            content=json.dumps(content),
            author_name=info.get("author_name") or info.get("short_name") or "",
            author_url=info.get("author_url") or "",
        )

    except Exception as error:
        await update.message.reply_text(f"Could not create it:\n{error}")
        return

    sent = await update.message.reply_text(
        f"<b>{title}</b> is live, and empty.\n\n"
        f"{SITE_URL}#{page['path']}\n\n"
        "Reply to this message with /link or /repo to put something in it, "
        "or /about and /footer to give it an introduction.\n\n"
        "It is curated: /site will not fill it from your published pages."
        + carrier_link("page", token, site=page["path"]),
        parse_mode=ParseMode.HTML,
        disable_web_page_preview=True,
    )

    try:
        await sent.pin(disable_notification=True)

    except Exception:
        pass


async def unfile(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """
    Take one entry out of a collection.

    Filing is exclusive, so this is the only way back: without it a stray
    /link would hide a page from the primary index for good, short of
    editing Telegraph by hand. It also serves as the way to drop a GitHub
    or outward entry, which nothing else could do.

    Replying to a Published message needs no argument at all - that
    message carries both the collection and the page.
    """

    _, _, extras = read_carrier(update.message)

    wanted = command_words(context)
    target = telegraph_path(wanted) if wanted else extras.get("path")

    token, path = await find_site(update, context, "/unfile")

    if not path:
        return

    if not target and not wanted:
        await update.message.reply_text(
            "Reply to a <b>Published</b> message with /unfile, or give the "
            "address of the entry:\n\n"
            "<code>/unfile https://telegra.ph/Some-Page-07-28</code>",
            parse_mode=ParseMode.HTML,
        )
        return

    try:
        page = await telegraph("getPage", path=path, return_content="true")

    except Exception as error:
        await update.message.reply_text(f"Could not find that collection:\n{error}")
        return

    head, middle, foot = split_master(page.get("content"))

    listing = middle[0] if middle and middle[0].get("tag") == "ul" else None

    if listing is None:
        await update.message.reply_text(
            f"<b>{page['title']}</b> has nothing in it yet.",
            parse_mode=ParseMode.HTML,
        )
        return

    kept = []
    removed = None

    for item in listing.get("children") or []:

        href = entry_href(item)

        # Matched either as a telegra.ph page or as the exact address of an
        # outward entry, so one command covers both kinds.
        hit = href and (
            (target and telegraph_path(href) == target)
            or (wanted and href.rstrip("/") == wanted.rstrip("/"))
        )

        if hit and removed is None:
            removed = node_text(item).split(INDEX_SEP)[0].strip()
            continue

        kept.append(item)

    if removed is None:
        await update.message.reply_text(
            f"Nothing in <b>{page['title']}</b> points at that.",
            parse_mode=ParseMode.HTML,
        )
        return

    listing["children"] = kept

    try:
        await telegraph(
            "editPage",
            access_token=token,
            path=path,
            title=page["title"],
            content=json.dumps(
                head + middle + foot + [kept_marker(page.get("content"))]
            ),
            author_name=page.get("author_name") or "",
            author_url=page.get("author_url") or "",
        )

    except Exception as error:
        await update.message.reply_text(f"Could not save it:\n{error}")
        return

    back = ""

    if is_extra(page.get("content")) and target:
        back = ("\n\nIt is no longer filed, so /site will list it in your "
                "primary index again.")

    await update.message.reply_text(
        f"<b>{removed}</b> removed from {page['title']}.{back}"
        + carrier_link("page", token, site=path),
        parse_mode=ParseMode.HTML,
        disable_web_page_preview=True,
    )


async def retire(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """
    Take a collection out of service.

    Telegraph cannot delete a page, so the marker is replaced instead. A
    retired index is skipped by everything that looks for one, and is
    still never listed as an article. The page itself stays where it is.
    """

    token, path = await find_site(update, context, "/retire")

    if not path:
        return

    try:
        page = await telegraph("getPage", path=path, return_content="true")

    except Exception as error:
        await update.message.reply_text(f"Could not find it:\n{error}")
        return

    content = page.get("content")

    if not is_extra(content):
        await update.message.reply_text(
            "That is your primary collection, so it cannot be retired - "
            "everything you publish is listed there.\n\n"
            "Run /collections and reply to a curated one instead."
        )
        return

    head, middle, foot = split_master(content)

    try:
        await telegraph(
            "editPage",
            access_token=token,
            path=path,
            title=page["title"],
            content=json.dumps(
                head + middle + foot
                + [{"tag": "p", "children": [RETIRED_MARK]}]
            ),
            author_name=page.get("author_name") or "",
            author_url=page.get("author_url") or "",
        )

    except Exception as error:
        await update.message.reply_text(f"Could not retire it:\n{error}")
        return

    await update.message.reply_text(
        f"<b>{page['title']}</b> is retired.\n\n"
        "It no longer appears in /collections and nothing will write to it. "
        "The page itself still exists - Telegraph cannot delete one - so its "
        "link keeps working for anyone who has it.\n\n"
        f"{SITE_URL}#{path}",
        parse_mode=ParseMode.HTML,
        disable_web_page_preview=True,
    )


async def revise(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """
    Path comes from an argument, from the carrier on a Published message,
    or from any telegra.ph URL in the message being replied to.
    """

    token = token_for(update, context)

    path = telegraph_path(" ".join(context.args)) if context.args else None

    source = update.message.reply_to_message

    if not path and source:

        _, _, extras = read_carrier(update.message)

        path = extras.get("path")

        if not path:
            found = re.search(r"https?://telegra\.ph/\S+", source.text or "")
            path = telegraph_path(found.group(0)) if found else None

    if not token or not path:
        await update.message.reply_text(
            "Reply to a <b>Published</b> message with <code>/revise</code> "
            "and Telepatch finds both the page and the token.\n\n"
            "Otherwise: reply to your pinned identity with "
            "<code>/revise &lt;telegra.ph url&gt;</code>.",
            parse_mode=ParseMode.HTML,
        )
        return

    await prompt_revise(update.message, token, path)


async def pages(update: Update, context: ContextTypes.DEFAULT_TYPE):

    token = token_for(update, context)

    if not token:
        await update.message.reply_text(
            token_hint("/pages"),
            parse_mode=ParseMode.HTML,
        )
        return

    await send_pages(update.message, token)


async def views(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """
    Public endpoint - no access token involved at any point. Accepts a URL
    as an argument, or a reply to any message containing one.

    getPage carries the view count as well as the title and byline, so this
    single command covers both "how is it doing" and "what is public here".
    """

    text = " ".join(context.args) if context.args else ""

    if not text and update.message.reply_to_message:
        text = update.message.reply_to_message.text or ""

    found = re.search(r"https?://telegra\.ph/\S+", text)

    path = telegraph_path(found.group(0) if found else text)

    if not path:
        await update.message.reply_text(
            "Send <code>/views &lt;telegra.ph url&gt;</code>, or reply to a "
            "message containing one.\n\n"
            "No token needed - this reads only what is already public.",
            parse_mode=ParseMode.HTML,
        )
        return

    try:
        page = await telegraph("getPage", path=path, return_content="false")

    except Exception as error:
        await update.message.reply_text(f"Could not read that page:\n{error}")
        return

    await update.message.reply_text(
        f"<b>{page.get('title') or '-'}</b>\n"
        f"Byline: {page.get('author_name') or '(none)'}\n"
        f"Views: <b>{page.get('views', 0)}</b>\n\n"
        f"{page.get('url')}",
        parse_mode=ParseMode.HTML,
        disable_web_page_preview=True,
    )


# -----------------------
# Actions
# -----------------------

async def create_identity(message, text):
    """
    Create the account and hand back a deep link that reopens the menu.
    """

    try:
        short_name, author_name, author_url = parse_new_fields(text)

    except ValueError as error:
        await message.reply_text(str(error))
        return

    try:
        account = await telegraph(
            "createAccount",
            short_name=short_name,
            author_name=author_name,
            author_url=normalize_url(author_url),
        )

    except Exception as error:
        await message.reply_text(f"Unable to create identity:\n{error}")
        return

    await send_token(message, account["access_token"], account)


async def send_token(message, token, info=None, revoked=False):
    """
    Hand a token back with a deep link that reopens the manage menu.
    This message is the only copy that will ever exist.
    """

    me = await message.get_bot().get_me()

    keyboard = InlineKeyboardMarkup([[
        InlineKeyboardButton(
            "Manage this identity",
            url=f"https://t.me/{me.username}?start={token}",
        )
    ]])

    lines = (
        ["<b>Token revoked. Here is your new one.</b>", ""]
        if revoked
        else ["<b>Your Telepatch identity is ready.</b>", ""]
    )

    if info:
        lines += [
            f"Short name: <b>{info.get('short_name') or '-'}</b> (private)",
            f"Byline: <b>{info.get('author_name') or '-'}</b>",
            f"Author URL: <b>{info.get('author_url') or '-'}</b>",
            "",
        ]

    lines += [
        "Access token:",
        f"<code>{token}</code>",
        "",
        "This message is the only copy of your token. Telepatch does not "
        "keep it - without it the identity cannot be recovered, so save it "
        "somewhere safe.",
        "",
        "You will not need to paste it. <b>Reply to this message</b> with "
        "/post, /pages or /manage and Telepatch reads the token from it.",
    ]

    sent = await message.reply_text(
        "\n".join(lines),
        parse_mode=ParseMode.HTML,
        reply_markup=keyboard,
    )

    # Pin it so the identity stays reachable without scrolling. Statelessness
    # means the token has to live somewhere findable, and Telegram's pin list
    # is exactly that - owned by the user, not the bot. Several identities
    # simply produce several pins, so nothing is unpinned here.
    try:
        await sent.pin(disable_notification=True)

    except Exception:
        # Pinning needs rights the bot may not have outside a private chat.
        pass


async def send_pages(target, token):

    try:
        result = await telegraph(
            "getPageList",
            access_token=token,
            limit=50,
        )

    except Exception as error:
        await target.reply_text(f"That token did not work:\n{error}")
        return

    items = result.get("pages", [])

    if not items:
        await target.reply_text("Nothing published from this identity yet.")
        return

    lines = [f"<b>{result.get('total_count', len(items))} published</b>", ""]

    for page in items:
        lines.append(
            f'• <a href="{page["url"]}">{page.get("title") or page["path"]}</a>'
            f' - {page.get("views", 0)} views'
            f' · <a href="{EDITOR_URL}#{token}/{page["path"]}">edit</a>'
        )

    await target.reply_text(
        "\n".join(lines),
        parse_mode=ParseMode.HTML,
        disable_web_page_preview=True,
    )


async def send_editor(target, token, path=None):
    """
    The Telepatch editor: Telegraph's formatting and nothing else, with the
    contents list building itself as headings appear.
    """

    url = f"{EDITOR_URL}#{token}" + (f"/{path}" if path else "")

    await target.reply_text(
        "<b>Write in your browser</b>\n\n"
        "Only the formatting Telegraph accepts, an overview line above the "
        "contents, and the contents list building itself as you add "
        "headings.\n\n"
        "The link carries your access token. It is never sent to a server, "
        "but it will sit in that browser's history - use your own machine.\n\n"
        f"{url}",
        parse_mode=ParseMode.HTML,
        disable_web_page_preview=True,
    )


async def send_editor_link(target, token):
    """
    Telegraph refuses uploads from anywhere but its own editor session, so
    the only way to get a telegra.ph-hosted image is to log the user in.
    auth_url does exactly that, and expires after five minutes.
    """

    try:
        info = await telegraph(
            "getAccountInfo",
            access_token=token,
            fields='["auth_url"]',
        )

    except Exception as error:
        await target.reply_text(f"That token did not work:\n{error}")
        return

    await target.reply_text(
        "<b>To use a Telegraph-hosted image</b>\n\n"
        "Telegraph only accepts uploads from its own editor, so open the "
        "link below, drag your image into the page, then copy the "
        "<code>telegra.ph/file/…</code> address it becomes.\n\n"
        "Paste that address on its own line in your post and Telepatch "
        "turns it into an image.\n\n"
        "<b>Best on a laptop</b> - the editor wants drag and drop, and is "
        "awkward on a phone.\n\n"
        "<b>This link expires in 5 minutes</b> and signs you in as this "
        "identity, so do not forward it.\n\n"
        f"{info.get('auth_url')}",
        parse_mode=ParseMode.HTML,
        disable_web_page_preview=True,
    )


async def on_photo(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """
    Explain rather than fail silently. Refusing to host the file is a
    feature here, so say so.
    """

    await update.message.reply_text(
        "<b>Telepatch cannot host images</b>, and does not keep your files.\n\n"
        "Telegraph only accepts uploads from its own editor, and Telegram's "
        "file links cannot be used publicly.\n\n"
        "Two ways to add a picture:\n\n"
        "1. Open /manage and press <b>Upload image</b> for a link to the "
        "Telegraph editor, where uploads work (best on a laptop).\n"
        "2. Paste any image URL on its own line in your post.\n\n"
        "YouTube, Vimeo and Twitter links on their own line become embeds.",
        parse_mode=ParseMode.HTML,
    )


async def publish(message, token, anonymous, override=None, site=None):
    """
    createPage does not inherit account defaults, so the byline is read
    and forwarded here - or deliberately withheld when anonymous, or
    replaced for this page only when an override rode in on the carrier.
    """

    try:
        title, categories, content = split_post(message)

    except ValueError as error:
        await message.reply_text(str(error))
        return

    author_name = ""
    author_url = ""

    if anonymous:
        # Skip the account read entirely so the byline is never even fetched.
        pass

    elif override is not None:
        author_name, author_url = override

    else:

        try:
            info = await get_account_info(token)

        except Exception as error:
            await message.reply_text(f"That token did not work:\n{error}")
            return

        author_name = info.get("author_name") or info.get("short_name") or ""
        author_url = info.get("author_url") or ""

    try:
        page = await telegraph(
            "createPage",
            access_token=token,
            title=title,
            author_name=author_name,
            author_url=author_url,
            content=json.dumps(content),
        )

    except Exception as error:
        await message.reply_text(f"Could not publish:\n{error}")
        return

    byline = author_name or "no byline"

    tagline = f" · {', '.join(categories)}" if categories else ""

    # A curated collection is not enumerated by /site, so a page written
    # for one has to be put there now or it would never appear.
    added = ""

    if site:
        try:
            words = page_words(content)

            index_title = await asyncio.to_thread(
                insert_entry,
                token, site, page["url"], title, categories,
                page_excerpt(content),
                max(1, round(words / WORDS_PER_MINUTE)),
            )
            added = f"\nAdded to <b>{index_title}</b>."

        except Exception as error:
            added = (
                f"\nCould not add it to that collection: {error}\n"
                "The page itself is published and safe."
            )

    extras = {"path": page["path"]}

    if site:
        extras["site"] = site

    # The carrier here means a reply of "/revise" to this message needs no
    # arguments - both the token and the page path come out of it.
    await message.reply_text(
        f"<b>Published.</b> ({byline}{tagline}){added}\n\n{page['url']}\n\n"
        "Reply to this message with /revise to change it."
        + carrier_link("page", token, **extras),
        parse_mode=ParseMode.HTML,
        disable_web_page_preview=True,
    )

    await send_menu(message, token)


ISO_DATE = re.compile(r"\d{4}-\d{2}-\d{2}")


# " — 2026-07-28 · 6 min · tin, industry", written by build_index. Every
# part after the date is optional, because /link entries claim no reading
# time and not everything is categorised.
# As lenient as the website, which has always accepted a dot, a bullet, a
# comma or nothing at all. The bot used to insist on the dot, so an index
# written by hand with commas read back with no date - and /site re-dated
# every entry to today. The separator is punctuation, not syntax.
ENTRY_META = re.compile(
    r"(\d{4}-\d{2}-\d{2})"
    r"(?:\s*[·•,]?\s*(\d+)\s*min)?"
    r"(?:\s*[·•,]?\s*(.+?))?\s*$"
)


def read_index_entries(content):
    """
    Recover everything an existing index recorded, keyed by page path.

    The index is not just a rendering of the account - it is the only place
    the publication date exists at all, and it already holds the reading
    time, categories and excerpt that /site would otherwise refetch every
    page to recompute. Reading it back is derivation from the authoritative
    source, not a cache of one.
    """

    found = {}

    def walk(nodes):

        for node in nodes or []:

            if not isinstance(node, dict):
                continue

            kids = node.get("children") or []

            anchor = next(
                (k for k in kids
                 if isinstance(k, dict) and k.get("tag") == "a"),
                None,
            )

            if anchor and (anchor.get("attrs") or {}).get("href"):

                href = anchor["attrs"]["href"]
                path = telegraph_path(href)

                # Everything before the <br> is machine-read - date,
                # reading time, categories - and everything after it is the
                # excerpt. Joining every string child instead put the
                # excerpt on the end of the last category.
                at = next(
                    (i for i, k in enumerate(kids)
                     if isinstance(k, dict) and k.get("tag") == "br"),
                    len(kids),
                )

                meta = "".join(k for k in kids[:at] if isinstance(k, str))
                excerpt = "".join(
                    k for k in kids[at + 1:] if isinstance(k, str)
                ).strip()

                stamp = ENTRY_META.search(meta)

                if stamp and path and "github.com" not in href:
                    found[path] = {
                        "title": node_text(anchor).strip(),
                        "url": href,
                        "date": stamp.group(1),
                        "minutes": int(stamp.group(2)) if stamp.group(2) else 0,
                        "categories": [
                            c.strip() for c in (stamp.group(3) or "").split(",")
                            if c.strip()
                        ],
                        "excerpt": excerpt,
                    }

                continue

            walk(kids)

    walk(content)

    return found


def read_index_dates(content):
    """
    Just the dates, for callers that want nothing else.
    """

    return {p: e["date"] for p, e in read_index_entries(content).items()}


def is_index(content):
    """
    True if this page is one of our generated indexes, current or retired.
    Such pages are never listed as articles.
    """

    text = " ".join(node_text(n) for n in content or [])

    return any(mark in text for mark in INDEX_MARKS)


# Enough to hide the latency, few enough to stay a polite guest. An
# unbounded burst at a free API on somebody else's behalf is a bad way to
# introduce yourself, and the limits are not documented.
SCAN_WORKERS = 8


def scan_pages(token, known=None, have=None):
    """
    Every page on the account, with content where content is needed.

    The bot holds the token, so it can enumerate pages the public API will
    not. One pass serves both jobs that need it - finding the existing
    index, and building the new one.

    `known` is what the current index already records. A page listed there
    needs no fetch: its title, date, reading time, categories and excerpt
    were computed last time and written down, and re-deriving them is the
    single most expensive thing this bot does. A page in that list is also
    provably not an index, since indexes are never listed as entries.

    Runs in a worker thread, and fans out inside it.
    """

    known = known or {}
    have = have or {}

    listing = _post("getPageList", access_token=token, limit=INDEX_LIMIT)
    pages = listing.get("pages", [])

    wanted = [
        p for p in pages
        if p["path"] not in known and p["path"] not in have
    ]

    def fetch(page):
        try:
            return _post("getPage", path=page["path"], return_content="true")

        except Exception:
            # A page that will not load simply gets no categories.
            return {}

    fetched = {}

    if wanted:
        workers = min(SCAN_WORKERS, len(wanted))

        with ThreadPoolExecutor(max_workers=workers) as pool:
            for page, full in zip(wanted, pool.map(fetch, wanted)):
                fetched[page["path"]] = full.get("content")

    log.info("scan.done pages=%s fetched=%s reused=%s",
             len(pages), len(wanted), len(pages) - len(wanted))

    return [
        (page, have.get(page["path"], fetched.get(page["path"])))
        for page in pages
    ]


def pick_master(scanned):
    """
    The primary index, if any. getPageList is newest first, so the first
    hit is the current one.

    Curated collections are skipped: /site enumerates the account into the
    primary alone, and an account that has never made a second collection
    behaves exactly as it did before they existed.
    """

    for page, content in scanned:

        text = " ".join(node_text(n) for n in content or [])

        if MASTER_MARK in text and RETIRED_MARK not in text \
                and EXTRA_FIELD not in text:
            return page["path"], page.get("title")

    return None, None


def list_indexes(scanned):
    """
    Every live index on the account, the primary first.
    """

    found = []

    for page, content in scanned:

        text = " ".join(node_text(n) for n in content or [])

        if MASTER_MARK not in text or RETIRED_MARK in text:
            continue

        found.append({
            "path": page["path"],
            "title": page.get("title") or page["path"],
            "extra": EXTRA_FIELD in text,
        })

    found.sort(key=lambda index: index["extra"])

    return found


def read_masthead(content):
    """
    The publisher's own prose from the top of the master post.

    /site regenerates the whole page, so an introduction typed by hand would
    vanish on the next rebuild unless it is read back first. Same principle
    as the dates: the master post is the record, and the bot remembers
    nothing between runs.
    """

    return split_master(content)[0]


def split_master(content):
    """
    Split a master post into (masthead, list, footer).

    The generated list sits in the middle; the publisher's own prose sits
    above it and below it. Splitting three ways lets either be replaced
    without regenerating the other or the list between them.
    """

    nodes = list(content or [])
    at = None

    for i, node in enumerate(nodes):

        if not isinstance(node, dict):
            continue

        if node.get("tag") == "ul" or node_text(node).strip() == EMPTY_NOTICE:
            at = i
            break

    if at is None:
        return nodes, [], []

    def keep(node):
        return not any(m in node_text(node) for m in INDEX_MARKS)

    return (
        [n for n in nodes[:at] if keep(n)],
        [nodes[at]],
        [n for n in nodes[at + 1:] if keep(n)],
    )


# Used only to decide "is this href even a candidate for being one of our
# own pages" before comparing its path against own_paths in read_external.
# Deliberately narrower than a general URL check - a false match here just
# means one more href gets a (cheap) path comparison, but a false miss
# would treat a genuine telegra.ph page as an outward link.
TELEGRAPH_HOST_RE = re.compile(r"^https?://(www\.)?telegra\.ph/", re.IGNORECASE)


def read_external(content, own_paths=None):
    """
    Index entries that point outside this account, kept verbatim.

    /site regenerates the list from getPageList, which only knows this
    account's Telegraph pages. A GitHub link added by hand, or a /link
    entry pointing at a *different* Telegraph account's page - another
    Telepatch publication, say - would be wiped on the next rebuild
    otherwise, so both are read back first, the same read-before-write the
    dates, masthead and footer already need.

    A telegra.ph href only counts as "ours" - and so is left for the
    ordinary scan to regenerate, not kept here - when its path is actually
    in own_paths. Any other telegra.ph page is exactly as external as a
    GitHub link; the host alone was never a safe test for that.
    """

    own_paths = own_paths or set()
    kept = []

    for node in split_master(content)[1]:

        if not isinstance(node, dict) or node.get("tag") != "ul":
            continue

        for item in node.get("children", []):

            if not isinstance(item, dict):
                continue

            kids = item.get("children", [])

            anchor = next(
                (k for k in kids
                 if isinstance(k, dict) and k.get("tag") == "a"),
                None,
            )

            if not anchor:
                continue

            href = (anchor.get("attrs") or {}).get("href", "")

            if not href or href.startswith("/"):
                continue

            if TELEGRAPH_HOST_RE.match(href) and telegraph_path(href) in own_paths:
                continue

            text = "".join(k for k in kids if isinstance(k, str))
            found = ISO_DATE.search(text)

            kept.append({"node": item, "date": found.group(0) if found else ""})

    return kept


def read_byline(content):
    """
    The byline mode recorded on the marker line, or the default.
    """

    for node in content or []:

        text = node_text(node)

        if MASTER_MARK not in text:
            continue

        found = re.search(r"byline=(\w+)", text)

        if found and found.group(1) in BYLINE_MODES:
            return found.group(1)

    return BYLINE_DEFAULT


def marker_node(mode=BYLINE_DEFAULT, extra=False):
    """
    The one line the bot writes for itself, carrying the site's settings.
    """

    fields = f"byline={mode}"

    if extra:
        fields += f" {EXTRA_FIELD}"

    return {"tag": "p", "children": [f"{MASTER_MARK} {fields}"]}


def is_retired(content):
    """
    True if this page has been taken out of service, however that was
    done. /retire replaces the marker outright, but retiring by hand in
    the Telegraph editor leaves the original line and adds this one beside
    it, so the whole page is checked rather than the marker alone.
    """

    return any(RETIRED_MARK in node_text(node) for node in content or [])


def kept_marker(content, mode=None):
    """
    The marker line for a page being rewritten.

    Five different commands rewrite an index and each one rebuilds this
    line. Every one of them has to carry across what it did not come to
    change, or editing the footer of a collection would quietly demote it
    to the primary - or bring a retired one back, since split_master
    strips both marks and only one would be written back.
    """

    if is_retired(content):
        return {"tag": "p", "children": [RETIRED_MARK]}

    return marker_node(mode or read_byline(content), extra=is_extra(content))


def is_extra(content):
    """
    True for a curated collection, False for the primary or for anything
    that is not an index at all.
    """

    for node in content or []:

        text = node_text(node)

        if MASTER_MARK in text:
            return EXTRA_FIELD in text

    return False


def read_footer(content):
    """
    The publisher's own closing note, kept across rebuilds like the masthead.
    """

    return split_master(content)[2]


def entry_href(item):
    """
    The address an index entry points at, or None if it is not an entry.
    """

    if not isinstance(item, dict) or item.get("tag") != "li":
        return None

    for child in item.get("children") or []:

        if isinstance(child, dict) and child.get("tag") == "a":
            return (child.get("attrs") or {}).get("href")

    return None


def claimed_paths(scanned):
    """
    The pages filed into a curated collection.

    The primary is the inbox and a collection is a folder: filing a page
    moves it. Membership needs no marker of its own because it is already
    written down - in the list of the collection that claims it - and
    scan_pages has fetched every one of those lists already.

    Retired collections claim nothing, or retiring one would strand its
    pages outside every index.
    """

    filed = set()

    for _, content in scanned:

        text = " ".join(node_text(n) for n in content or [])

        if MASTER_MARK not in text or RETIRED_MARK in text:
            continue

        if EXTRA_FIELD not in text:
            continue

        _, middle, _ = split_master(content)
        listing = middle[0] if middle and middle[0].get("tag") == "ul" else None

        for item in (listing or {}).get("children") or []:

            href = entry_href(item)
            path = telegraph_path(href) if href else None

            # Only pages on telegra.ph can be filed. A GitHub or outward
            # entry was never in the account listing to begin with.
            if path and "github.com" not in (href or ""):
                filed.add(path)

    return filed


def build_index(scanned, master_path=None, known_dates=None,
                masthead=None, footer=None, byline=BYLINE_DEFAULT,
                external=None, filed=None, known=None):
    """
    Lay the account's articles out as the content of one master post.

    Every generated index is skipped, not just the one being rewritten -
    otherwise a stray index from an earlier run appears as an article.
    Pages filed into a curated collection are skipped too: they have been
    moved, not copied.
    """

    known_dates = known_dates or {}
    known = known or {}
    filed = filed or set()
    today = date.today().isoformat()

    entries = []

    for page, content in scanned:

        if page["path"] == master_path or is_index(content):
            continue

        if page["path"] in filed:
            continue

        # Not fetched this time, because the index already recorded it.
        # Safe by construction: only entries appear in that record, and an
        # index is never listed as an entry.
        recorded = known.get(page["path"]) if content is None else None

        if recorded:
            entries.append({
                "title": page.get("title") or recorded["title"],
                "url": page["url"],
                "path": page["path"],
                "categories": recorded["categories"],
                "date": known_dates.get(page["path"], recorded["date"]),
                "excerpt": recorded["excerpt"],
                "minutes": recorded["minutes"],
            })
            continue

        categories = page_categories(content)
        is_nav = NAV_CATEGORY in [c.lower() for c in categories]

        words = page_words(content)

        entries.append(
            {
                "title": page.get("title") or page["path"],
                "url": page["url"],
                "path": page["path"],
                "categories": categories,
                # First time a page is indexed it is dated today, and that
                # date is carried forward by every later rebuild.
                "date": known_dates.get(page["path"], today),
                # Nav pages never appear in the index, so they get neither.
                "excerpt": "" if is_nav else page_excerpt(content),
                "minutes": 0 if is_nav else max(1, round(words / WORDS_PER_MINUTE)),
            }
        )

    # getPageList is newest first, so a stable sort by date keeps that order
    # within a day while putting newer days on top.
    entries.sort(key=lambda e: e["date"], reverse=True)

    items = []

    for entry in entries:

        children = [
            {
                "tag": "a",
                "attrs": {"href": entry["url"]},
                "children": [entry["title"]],
            }
        ]

        # Everything before the <br> is machine-read: date, reading time,
        # categories. Everything after is the excerpt. Both halves still
        # read as an ordinary sentence on telegra.ph.
        meta = INDEX_SEP + entry["date"]

        if entry["minutes"]:
            meta += f" · {entry['minutes']} min"

        if entry["categories"]:
            meta += " · " + ", ".join(entry["categories"])

        children.append(meta)

        if entry["excerpt"]:
            children.append({"tag": "br"})
            children.append(entry["excerpt"])

        items.append({"date": entry["date"], "node": {"tag": "li", "children": children}})

    # Hand-added entries pointing elsewhere keep their place by date.
    items.extend(external or [])
    items.sort(key=lambda i: i["date"], reverse=True)
    items = [i["node"] for i in items]

    content = list(masthead or [])

    content.append(
        {"tag": "ul", "children": items} if items
        else {"tag": "p", "children": [EMPTY_NOTICE]}
    )

    content.extend(footer or [])
    content.append(marker_node(byline))

    return entries, content


async def rebuild_site(message, token, master_path=None, title=None,
                       refresh=False):
    """
    Create the master post, or rewrite it in place when one already exists.

    A rebuild reads back what the last one wrote rather than recomputing
    it, so the work scales with what has been published since - not with
    what the account holds. /site refresh forces the full pass, which is
    what an article edited outside the bot needs.
    """

    notice = await message.reply_text(
        "Reading your pages…" if master_path else "Building your index…"
    )

    try:
        info = await get_account_info(token)

    except Exception as error:
        await notice.edit_text(f"That token did not work:\n{error}")
        return

    # The index has to be read before the scan, because it is what makes
    # the scan cheap. Without a path there is nothing to read, so the first
    # rebuild of an account is a full pass whatever happens.
    recorded, have = {}, {}

    if master_path and not refresh:
        try:
            current = await telegraph(
                "getPage", path=master_path, return_content="true"
            )
            recorded = read_index_entries(current.get("content"))
            # Already in hand; the scan should not ask for it again.
            have[master_path] = current.get("content")

        except Exception:
            # Unreadable index: fall back to reading everything.
            recorded, have = {}, {}

    try:
        scanned = await asyncio.to_thread(scan_pages, token, recorded, have)

    except Exception as error:
        await notice.edit_text(f"Could not read your pages:\n{error}")
        return

    # Rewrite the existing index rather than adding another. Telegraph cannot
    # delete pages, so creating one per run would litter the account forever.
    found_path, found_title = pick_master(scanned)

    if not master_path:
        master_path = found_path

    existing_title = next(
        (p.get("title") for p, _ in scanned if p["path"] == master_path),
        None,
    )

    # A rebuild keeps the name it already has unless a new one is given.
    site_title = (
        title or existing_title or info.get("short_name") or "Telepatch"
    )

    # Read what the old page recorded before overwriting it: the dates, and
    # any introduction the publisher wrote above the list.
    old = next((c for p, c in scanned if p["path"] == master_path), None)

    known_dates = read_index_dates(old)
    masthead = read_masthead(old)
    footer = read_footer(old)

    # A curated collection is a list somebody made on purpose. Enumerating
    # the account into it would replace their choices with everything.
    curated = is_extra(old)
    filed_count = 0

    if curated:
        head, middle, foot = split_master(old)
        content = head + middle + foot + [kept_marker(old)]

        # Shaped like build_index's entries so the summary can count them.
        listed = (middle[0].get("children") if middle else None) or []
        entries = [
            {"categories": []} for node in listed
            if isinstance(node, dict) and node.get("tag") == "li"
        ]

    else:
        filed = claimed_paths(scanned)
        own_paths = {page["path"] for page, _ in scanned}

        entries, content = build_index(
            scanned, master_path, known_dates, masthead, footer,
            read_byline(old), read_external(old, own_paths), filed, recorded
        )

        # Said out loud, always. A page quietly missing from a rebuild that
        # was run for some other reason is how trust in this goes.
        filed_count = sum(
            1 for page, page_content in scanned
            if page["path"] in filed and not is_index(page_content)
        )

    byline = info.get("author_name") or info.get("short_name") or ""

    try:
        if master_path:
            page = await telegraph(
                "editPage",
                access_token=token,
                path=master_path,
                title=site_title,
                content=json.dumps(content),
                author_name=byline,
                author_url=info.get("author_url") or "",
            )

        else:
            page = await telegraph(
                "createPage",
                access_token=token,
                title=site_title,
                content=json.dumps(content),
                author_name=byline,
                author_url=info.get("author_url") or "",
            )

    except Exception as error:
        await notice.edit_text(f"Could not save the index:\n{error}")
        return

    nav = sum(1 for e in entries if NAV_CATEGORY in
              [c.lower() for c in e["categories"]])

    tags = sorted({
        c for e in entries for c in e["categories"]
        if c.lower() not in RESERVED_CATEGORIES
    })

    await notice.delete()

    sent = await message.reply_text(
        f"<b>{site_title}</b> is live.\n"
        + ("Rewrote your existing index.\n" if master_path else
           "New index created.\n")
        + "\n"
        f"{SITE_URL}#{page['path']}\n\n"
        + (f"{len(entries)} entries · curated by hand\n" if curated else
           f"{len(entries) - nav} posts · {nav} nav pages · "
           f"{len(tags)} categories\n"
           + (f"{filed_count} filed in collections, left out\n"
              if filed_count else ""))
        + (f"{', '.join(tags)}\n" if tags else "")
        + "\nAnyone can open that link - it carries no token.\n"
        "Reply to this message with /site after publishing to refresh it."
        + carrier_link("page", token, site=page["path"]),
        parse_mode=ParseMode.HTML,
        disable_web_page_preview=True,
    )

    try:
        await sent.pin(disable_notification=True)

    except Exception:
        pass


async def revise_page(message, token, path):
    """
    editPage clears author_name and author_url when they are not sent, so
    the current byline is read back and re-supplied. Omitting it would
    silently strip the byline off an existing article.
    """

    try:
        title, categories, content = split_post(message)

    except ValueError as error:
        await message.reply_text(str(error))
        return

    try:
        current = await telegraph("getPage", path=path, return_content="false")

    except Exception as error:
        await message.reply_text(f"Could not find that page:\n{error}")
        return

    try:
        page = await telegraph(
            "editPage",
            access_token=token,
            path=path,
            title=title,
            content=json.dumps(content),
            author_name=current.get("author_name") or "",
            author_url=current.get("author_url") or "",
        )

    except Exception as error:
        await message.reply_text(f"Could not update:\n{error}")
        return

    await message.reply_text(
        f"<b>Updated.</b>\n\n{page['url']}\n\n"
        "Reply to this message with /revise to change it again."
        + carrier_link("page", token, path=path),
        parse_mode=ParseMode.HTML,
        disable_web_page_preview=True,
    )


# -----------------------
# Buttons and replies
# -----------------------

async def on_button(update: Update, context: ContextTypes.DEFAULT_TYPE):

    query = update.callback_query

    await query.answer()

    action, _, token = query.data.partition(":")

    if action in ACTION_FIELDS:
        await prompt_for(query.message, ACTION_FIELDS[action], token)
        return

    if action == "p":
        await prompt_post(query.message, token)
        return

    if action == "P":
        await prompt_post(query.message, token, anonymous=True)
        return

    if action == "c":
        await prompt_byline(query.message, token)
        return

    if action == "l":
        await send_pages(query.message, token)
        return

    if action == "e":
        await send_editor_link(query.message, token)
        return

    if action == "g":
        await rebuild_site(query.message, token)
        return

    if action == "W":
        await send_editor(query.message, token)
        return

    if action == "r":

        await query.message.reply_text(
            "Revoking invalidates this token and issues a new one. "
            "Any copy you have saved stops working.",
            reply_markup=InlineKeyboardMarkup([[
                InlineKeyboardButton("Revoke", callback_data=f"R:{token}"),
                InlineKeyboardButton("Cancel", callback_data=f"m:{token}"),
            ]]),
        )
        return

    if action == "R":

        try:
            account = await telegraph("revokeAccessToken", access_token=token)

        except Exception as error:
            await query.message.reply_text(f"Could not revoke:\n{error}")
            return

        await send_token(query.message, account["access_token"], revoked=True)
        return

    if action == "m":
        await send_menu(query.message, token)


async def on_reply(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """
    Replies to our own prompts. The field and token come back out of the
    prompt message, so nothing had to be remembered in between.
    """

    field, token, extras = read_carrier(update.message)

    if not field:
        return

    if field == "new":
        await create_identity(update.message, update.message.text.strip())
        return

    if field == "byline":

        name, _, url = update.message.text.strip().partition(",")

        if not name.strip():
            await update.message.reply_text("Give a name for the byline.")
            return

        await prompt_post(
            update.message,
            token,
            override=(name.strip(), normalize_url(url) or ""),
        )
        return

    if field == "revise":
        await revise_page(update.message, token, extras.get("path", ""))
        return

    if field == "about":
        await set_masthead(update.message, token, extras.get("site", ""))
        return

    if field == "footer":
        await set_footer(update.message, token, extras.get("site", ""))
        return

    if field == "link":
        await add_external(update.message, token, extras.get("site", ""))
        return

    if field == "repo":
        await add_repo(update.message, token, extras.get("site", ""))
        return

    if field in ("post", "anon"):

        override = ("n" in extras) and (extras.get("n", ""), extras.get("u", ""))

        await publish(
            update.message,
            token,
            anonymous=field == "anon",
            override=override or None,
            site=extras.get("site"),
        )
        return

    if field not in LIMITS:
        return

    text = update.message.text.strip()

    value = "" if is_clear(text) else text

    if field == "author_url" and value:
        value = normalize_url(value) or ""

    if field == "short_name" and not value:
        await update.message.reply_text("A short name is required.")
        return

    if len(value) > LIMITS[field]:
        await update.message.reply_text(
            f"That {FIELD_LABELS[field]} is too long "
            f"(max {LIMITS[field]} characters)."
        )
        return

    try:
        # Omitted fields are preserved by Telegraph, so send only this one.
        await telegraph("editAccountInfo", access_token=token, **{field: value})

    except Exception as error:
        await update.message.reply_text(f"Could not update:\n{error}")
        return

    await send_menu(
        update.message,
        token,
        note=f"Updated {FIELD_LABELS[field]}.",
    )


# -----------------------
# Main
# -----------------------

async def register_commands(app):
    """
    Populate the in-app command menu so the surface is discoverable.
    """

    await app.bot.set_my_commands([
        ("new", "Create a Telepatch identity"),
        ("post", "Publish - reply to your pinned identity"),
        ("howto", "How to write a post, in brief"),
        ("pages", "List your pages - reply to your pinned identity"),
        ("revise", "Rewrite a post - reply to its Published message"),
        ("site", "Build or refresh your public index"),
        ("about", "Set the introduction on your site"),
        ("footer", "Set the footer on your site"),
        ("link", "Add a GitHub or outward entry to your index"),
        ("repo", "Add a GitHub repository, as a dashboard"),
        ("collections", "List your collections"),
        ("newsite", "Start another collection on this identity"),
        ("unfile", "Take an entry out of a collection"),
        ("byline", "How bylines show: linked, separate, plain"),
        ("manage", "Byline, URL, revoke - reply to your pinned identity"),
        ("views", "Views for any page: /views <url>"),
        ("privacy", "What this bot keeps (nothing)"),
        ("telepatch", "About Telepatch"),
    ])


async def count_command(update, context):
    """
    One tally per command, and nothing else.

    Deliberately does not record *which* command. A per-command breakdown
    is a second dimension, and dimensions are how aggregate counts turn
    back into individual records - see the privacy notes in the design
    spec. The page shows a total, so a total is all that is counted.
    """

    message = getattr(update, "effective_message", None)
    text = getattr(message, "text", None) or ""

    if text.startswith("/"):
        tally("command.total")


async def on_error(update, context):
    """
    Anything a handler did not expect. Without this an exception vanishes
    and the person who typed the command is left looking at nothing.
    """

    log.exception("handler.failed", exc_info=context.error)

    # The class of the exception is deliberately not recorded. Exception
    # names are not a closed set - a Telegraph error string or a URL can
    # end up in one - and a public counter keyed on arbitrary text is the
    # exact shape COUNTED exists to prevent.
    tally("error")

    message = getattr(update, "effective_message", None)

    if message:
        try:
            await message.reply_text(
                "Something went wrong at our end. Nothing was changed - "
                "try again, and if it keeps happening the problem is "
                "probably Telegraph rather than you."
            )
        except Exception:
            pass

    if OPERATOR_CHAT:
        try:
            await context.bot.send_message(
                OPERATOR_CHAT,
                f"Telepatch error: {type(context.error).__name__}: {context.error}"[:3500],
            )
        except Exception:
            pass


def notify(state):
    """
    sd_notify, by hand. It is one datagram to a unix socket, which is less
    code than taking a dependency for it - and a no-op anywhere systemd is
    not watching, so the laptop behaves exactly as before.
    """

    address = os.environ.get("NOTIFY_SOCKET")

    if not address:
        return

    try:
        import socket

        if address.startswith("@"):          # abstract namespace
            address = "\0" + address[1:]

        with socket.socket(socket.AF_UNIX, socket.SOCK_DGRAM) as sock:
            sock.connect(address)
            sock.sendall(state.encode())

    except Exception as error:
        log.debug("notify.failed state=%s error=%s", state, error)


TICKERS = []


def every(seconds, work, app):
    """
    A repeating task. PTB's own job queue needs APScheduler, which is a
    dependency and a scheduler for something that is two lines of asyncio.
    """

    async def loop():
        while True:
            await asyncio.sleep(seconds)

            try:
                await work(app)

            except Exception:
                log.exception("ticker.failed")

    # Held, because asyncio only keeps a weak reference to a bare task.
    TICKERS.append(asyncio.create_task(loop()))


async def watchdog(app):
    """
    A bot that has stopped polling looks perfectly healthy to
    Restart=always, because the process is still there. This pings only
    while the updater reports itself running, so a wedged poller stops the
    pings and systemd restarts it.
    """

    if app.updater is not None and app.updater.running:
        notify("WATCHDOG=1")


async def heartbeat(app):
    """
    A dead man's switch. Long polling opens no port, so nothing outside can
    check whether this is alive - it has to say so itself, and silence is
    what raises the alarm.
    """

    await asyncio.to_thread(SESSION.get, HEARTBEAT_URL, timeout=10)


async def export_tick(app):
    """
    Publish the counters for telepatch-observer to read.

    Goes to a thread because it touches the filesystem, and the event loop
    serves everyone's commands. It is a tiny write to tmpfs, but "tiny" and
    "never blocks" are different promises.
    """

    await asyncio.to_thread(export_counters)


async def on_start(app):
    await register_commands(app)

    notify("READY=1")

    # systemd states the interval in microseconds and expects a ping
    # comfortably inside it; half is the documented convention.
    window = int(os.environ.get("WATCHDOG_USEC", 0)) / 1_000_000

    if window:
        every(window / 2, watchdog, app)

    if HEARTBEAT_URL:
        every(HEARTBEAT_SECONDS, heartbeat, app)

    # Faster than the observer samples (120s) so it always has something
    # current to read, and cheap enough that the interval does not matter -
    # this is a few hundred bytes to tmpfs.
    every(60, export_tick, app)

    log.info("telepatch.started watchdog=%s heartbeat=%s operator=%s",
             f"{window:.0f}s" if window else "off",
             bool(HEARTBEAT_URL), bool(OPERATOR_CHAT))


def main():
    logging.basicConfig(
        level=getattr(logging, LOG_LEVEL, logging.INFO),
        format="%(asctime)s %(levelname)s %(name)s %(message)s",
    )

    # Applied to the handlers, so it catches records from every logger -
    # including httpx, which logs request URLs containing access tokens.
    for handler in logging.getLogger().handlers:
        handler.addFilter(Redact())

    logging.getLogger("httpx").setLevel(logging.WARNING)
    logging.getLogger("telegram").setLevel(logging.WARNING)

    app = (
        Application.builder()
        .token(TELEGRAM_TOKEN)
        # Without this, updates are handled strictly one at a time and a
        # single /site freezes everyone else's /post for its duration.
        .concurrent_updates(True)
        .post_init(on_start)
        .build()
    )

    app.add_error_handler(on_error)

    # Group -1 runs before the command handlers and does not consume the
    # update, so this counts without changing what anything else sees. One
    # insertion point instead of twenty CommandHandler wrappers, and
    # nothing about which command or which person is recorded - see
    # COUNTED at the top of this file.
    app.add_handler(TypeHandler(Update, count_command, block=False), group=-1)

    app.add_handler(CommandHandler("start", start))
    app.add_handler(CommandHandler("howto", howto))
    app.add_handler(CommandHandler("privacy", privacy))
    app.add_handler(CommandHandler("telepatch", about))
    app.add_handler(CommandHandler("new", new))
    app.add_handler(CommandHandler("manage", manage))
    app.add_handler(CommandHandler("post", post))
    app.add_handler(CommandHandler("pages", pages))
    app.add_handler(CommandHandler("revise", revise))
    app.add_handler(CommandHandler("site", site))
    app.add_handler(CommandHandler("collections", collections_cmd))
    app.add_handler(CommandHandler("newsite", newsite))
    app.add_handler(CommandHandler("retire", retire))
    app.add_handler(CommandHandler(["unfile", "unlink"], unfile))
    app.add_handler(CommandHandler("about", about_site))
    app.add_handler(CommandHandler("footer", footer_site))
    app.add_handler(CommandHandler("byline", byline_site))
    app.add_handler(CommandHandler("link", link_cmd))
    app.add_handler(CommandHandler("repo", repo_cmd))
    app.add_handler(CommandHandler("views", views))

    app.add_handler(CallbackQueryHandler(on_button))

    app.add_handler(MessageHandler(filters.PHOTO | filters.Document.IMAGE, on_photo))

    app.add_handler(
        MessageHandler(
            filters.REPLY & filters.TEXT & ~filters.COMMAND,
            on_reply,
        )
    )

    # Only one process may poll a token at a time, so a deploy has to stop
    # before it starts. Dropping pending updates on boot means a restart
    # does not replay whatever queued up while it was down.
    app.run_polling(drop_pending_updates=True)


if __name__ == "__main__":
    main()