mail-notify 1.0.0__py3-none-any.whl

ccmail/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

ccmail/__main__.py

@@ -0,0 +1,13 @@
+import sys
+
+if len(sys.argv) > 1 and sys.argv[1] == "hook":
+    # fast path: avoid importing the CLI machinery on every hook call
+    from .hookclient import main as _main
+elif len(sys.argv) > 1 and sys.argv[1] == "wake":
+    from .wakeclient import main as _main
+elif len(sys.argv) > 1 and sys.argv[1] == "trace-hook":
+    from .tracer import main as _main
+else:
+    from .cli import main as _main
+
+sys.exit(_main())

ccmail/ack.py

@@ -0,0 +1,178 @@
+"""Instant acknowledgement mail for an accepted e-mail reply: what was received, where it is queued and an
+indicative time. The estimate comes from the observed length of earlier turns of the same chat (median of
+the last ones) and from the session's state; it is an indication, not a promise."""
+import statistics
+
+from . import render
+from .i18n import pick
+
+LISTEN_PERIOD_S = 3 * 3600  # keep in step with server.LISTEN_PERIOD_S: how long an idle chat is listening
+
+
+def _fmt(sec: float, settings=None) -> str:
+    T = lambda it, en: pick(settings, it, en)  # noqa: E731
+    sec = max(0, int(sec))
+    if sec < 90:
+        return T("meno di 2 minuti", "less than 2 minutes") if sec >= 30 else T("pochi secondi", "a few seconds")
+    m = round(sec / 60)
+    if m < 60:
+        return T(f"circa {m} min", f"about {m} min")
+    h, rem = divmod(m, 60)
+    return T(f"circa {h} h", f"about {h} h") + (f" {rem:02d} min" if rem else "")
+
+
+def typical_turn_s(db, session_id, project_dir=None):
+    """Median duration of the last completed turns of this chat (or project), or None if unknown."""
+    def durations(rows):
+        out, start = [], None
+        for r in rows:
+            if r["event"] == "UserPromptSubmit":
+                start = r["received_at"]
+            elif r["event"] == "Stop" and start is not None:
+                d = r["received_at"] - start
+                if 5 <= d <= 4 * 3600:
+                    out.append(d)
+                start = None
+        return out
+
+    rows = db.q("SELECT event, received_at FROM events WHERE session_id=? AND event IN ('UserPromptSubmit','Stop') "
+                "ORDER BY id DESC LIMIT 60", (session_id,))
+    d = durations(list(reversed(rows)))[-8:]
+    if len(d) < 2 and project_dir:
+        rows = db.q("SELECT e.event, e.received_at FROM events e JOIN sessions s ON s.session_id=e.session_id "
+                    "WHERE s.project_dir=? AND e.event IN ('UserPromptSubmit','Stop') ORDER BY e.id DESC LIMIT 80",
+                    (project_dir,))
+        d = durations(list(reversed(rows)))[-8:]
+    return statistics.median(d) if d else None
+
+
+def eta(db, session_id, now, parked=None, settings=None) -> dict:
+    """{'state': str, 'when': str, 'typical': str|None} describing where a message for `session_id` will land.
+
+    `parked`: True/False if the daemon knows whether that chat's wake hook is really waiting (so a delivery
+    "within seconds" is only promised when it is true); None when unknown."""
+    T = lambda it, en: pick(settings, it, en)  # noqa: E731
+    s = db.one("SELECT * FROM sessions WHERE session_id=?", (session_id,))
+    typical = typical_turn_s(db, session_id, (s or {}).get("project_dir"))
+    typ = (T(f"Di solito i turni di questa chat durano {_fmt(typical, settings)}.",
+             f"Turns in this chat usually take {_fmt(typical, settings)}.") if typical else None)
+    if not s:
+        return {"state": T("sessione non più nota", "session no longer known"), "typical": typ,
+                "when": T("Resta in coda (fino a 24 ore) e arriva al prossimo evento di quella chat.",
+                          "It stays queued (up to 24 hours) and arrives at that chat's next event.")}
+    state, last = s.get("state"), s.get("last_event_at") or now
+    if state == "ended":
+        return {"state": T("la sessione è chiusa", "the session is closed"), "typical": typ,
+                "when": T("Resta in coda (fino a 24 ore) e arriva quando la chat riparte.",
+                          "It stays queued (up to 24 hours) and arrives when the chat starts again.")}
+    if state == "active":
+        started = s.get("turn_start_at") or last
+        el = max(0, now - started)
+        # in-turn delivery: it rides on Claude's next tool call, it does not wait for the end of the turn
+        when = T("Claude lo legge al suo prossimo passo (dopo il prossimo strumento che usa): di solito entro pochi "
+                 "secondi; se sta eseguendo un comando lungo, quando quel comando finisce.",
+                 "Claude reads it at its next step (after the next tool it uses): usually within a few seconds; "
+                 "if it is running a long command, when that command ends.")
+        if typical and el >= typical:
+            when += T(" Il turno è già più lungo del solito.", " This turn is already longer than usual.")
+        return {"state": T(f"Claude sta lavorando da {_fmt(el, settings)}",
+                           f"Claude has been working for {_fmt(el, settings)}"), "when": when, "typical": typ}
+    # idle: the wake hook is parked for it
+    if now - last > LISTEN_PERIOD_S:
+        return {"state": T(f"la chat è ferma da {_fmt(now - last, settings)}",
+                           f"the chat has been idle for {_fmt(now - last, settings)}"), "typical": typ,
+                "when": T("Arriva al prossimo evento della chat (la sua attesa automatica era già scaduta).",
+                          "It arrives at the chat's next event (its automatic wait had already expired).")}
+    st = (T("Claude è in attesa di processi in background", "Claude is waiting for background processes")
+          if s.get("bg_tasks") else T("Claude è fermo", "Claude is idle"))
+    if parked is False:
+        # honest: the message cannot be pushed because nothing is waiting for it in that chat
+        return {"state": st + T(", ma la chat non è in ascolto", ", but the chat is not listening"), "typical": typ,
+                "when": T("Resta in coda e arriva al prossimo evento di quella chat (appena scrivi lì o Claude si "
+                          "ferma). Il suo hook di risveglio non risulta attivo: succede se la chat è stata aperta "
+                          "prima dell'installazione degli hook o dopo un riavvio del demone.",
+                          "It stays queued and arrives at that chat's next event (as soon as you write there or "
+                          "Claude stops). Its wake-up hook is not active: this happens when the chat was opened "
+                          "before the hooks were installed or after a daemon restart.")}
+    if parked is None:
+        return {"state": st, "typical": typ,
+                "when": T("Consegna immediata se la chat è in ascolto; altrimenti al prossimo evento della chat.",
+                          "Immediate delivery if the chat is listening; otherwise at the chat's next event.")}
+    return {"state": st + T(" e in ascolto", " and listening"),  "typical": typ,
+            "when": T("Consegnato entro pochi secondi: Claude riparte da solo e poi risponde.",
+                      "Delivered within a few seconds: Claude restarts by itself and then answers.")}
+
+
+def build_claude_ack(db, settings, session_id, text, now, project="", chat_title="", parked=None, ref=None):
+    T = lambda it, en: pick(settings, it, en)  # noqa: E731
+    e = eta(db, session_id, now, parked, settings)
+    lines = render.header(project, settings, session_id, chat_title)
+    parts = ["\n".join(lines),
+             render._section(T("Ricevuto", "Received"),
+                             T("La tua risposta è stata verificata e messa in coda per Claude:",
+                               "Your reply was verified and queued for Claude:"),
+                             "  «" + render.clean_line(text, 160) + "»"),
+             render._section(T("Quando arriva", "When it arrives"),
+                             T(f"Stato: {e['state']}.", f"State: {e['state']}."), "", e["when"])]
+    if e["typical"]:
+        parts[-1] += "\n\n" + e["typical"]
+    parts.append(render._section(T("Poi", "Next"),
+                                 T("Quando Claude finisce, ricevi la sua email di fine turno (se supera le "
+                                   "soglie impostate).",
+                                   "When Claude finishes you receive its end-of-turn e-mail (if it passes the "
+                                   "thresholds you set).")))
+    if ref:  # replying to this confirmation works exactly like replying to the original notification
+        parts.append(render.manage_section(ref, bool(settings.get("inbound_to_claude")), settings))
+    return (T(f"[Claude Code] {render.clean_line(project or '?', 60)}: risposta ricevuta e messa in coda",
+              f"[Claude Code] {render.clean_line(project or '?', 60)}: reply received and queued"),
+            "\n\n".join(parts) + "\n")
+
+
+def build_rejection(settings, reason: str, typed: str, project_name: str = "", ref=None):
+    """Mail in the usual layout whose OUTCOME says that a verified reply was discarded, and why."""
+    from .redact import redact
+    T = lambda it, en: pick(settings, it, en)  # noqa: E731
+    why, fix = {
+        "no_session": (T("non so a quale chat inoltrarla: la email a cui hai risposto non è legata a una chat "
+                         "(o la chat non c'è più).",
+                         "I do not know which chat to forward it to: the e-mail you replied to is not tied to a "
+                         "chat (or the chat no longer exists)."),
+                       T("Rispondi a una notifica recente della chat, oppure scrivi direttamente in chat.",
+                         "Reply to a recent notification of the chat, or write in the chat directly.")),
+        "no_ref": (T("la email non contiene un riferimento «Rif: ccm-…» valido, oppure è più vecchio di 14 giorni.",
+                     "the e-mail has no valid «Rif: ccm-…» reference, or it is older than 14 days."),
+                   T("Rispondi a una email recente di ccmail senza cancellare la riga «Rif:».",
+                     "Reply to a recent ccmail e-mail without deleting the «Rif:» line.")),
+        "to_claude_off": (T("la consegna delle risposte a Claude è disattivata nelle impostazioni.",
+                            "delivering replies to Claude is switched off in the settings."),
+                          T("Attiva «Le risposte arrivano a Claude» nell'app web, oppure usa OFF / ON / PAUSA.",
+                            "Turn on «Replies reach Claude» in the web app, or use OFF / ON / PAUSE.")),
+    }.get(reason, (reason, ""))
+    name = render.clean_line(project_name or "ccmail", 60)
+    ctx = [T(f"Progetto: {name}", f"Project: {name}"), f"Account: {render.account_label(settings)}"]
+    outcome = [T("Risposta scartata: ", "Reply discarded: ") + why]
+    if typed:
+        outcome += ["", T("Il tuo testo:", "Your text:"), "«" + render.clean_line(redact(typed), 300) + "»"]
+    parts = ["\n".join(ctx), render._section(T("Esito", "Outcome"), *outcome),
+             render._section(T("Cosa fare", "What to do"), fix)]
+    if ref:
+        parts.append(render.manage_section(ref, bool(settings.get("inbound_to_claude")), settings))
+    return (T(f"[Claude Code] {name}: risposta scartata", f"[Claude Code] {name}: reply discarded"),
+            "\n\n".join(parts) + "\n")
+
+
+def build_command_ack(settings, command: str, project_name: str, detail: str, ref=None):
+    T = lambda it, en: pick(settings, it, en)  # noqa: E731
+    revert = {"off": T("Per riaccenderlo rispondi ON a una email di ccmail, oppure usa la webapp.",
+                       "To turn it back on reply ON to a ccmail e-mail, or use the web app."),
+              "on": T("Le notifiche di questo progetto sono di nuovo attive.",
+                      "Notifications for this project are active again."),
+              "pause": T("Passato il tempo indicato le notifiche riprendono da sole.",
+                         "After the indicated time notifications resume by themselves.")}.get(command, "")
+    name = render.clean_line(project_name or "ccmail", 60)
+    parts = ["\n".join([T(f"Progetto: {name}", f"Project: {name}"), f"Account: {render.account_label(settings)}"]),
+             render._section(T("Comando eseguito", "Command executed"), detail, "", revert)]
+    if ref:
+        parts.append(render.manage_section(ref, bool(settings.get("inbound_to_claude")), settings))
+    return T(f"[Claude Code] {name}: comando eseguito", f"[Claude Code] {name}: command executed"), \
+        "\n\n".join(parts) + "\n"

ccmail/activity.py

@@ -0,0 +1,136 @@
+"""Read model for the Attività view: projects -> chats -> latest session, with an honest state label.
+
+States never claim more than the evidence supports (a stale 'idle' is not "waiting for you").
+"""
+import json
+import time
+
+from .db import leaf_name, norm_dir
+
+WORKING_QUIET_S = 5 * 60       # working but no event for this long: say so
+WORKING_STALE_S = 30 * 60      # 'active' without any event for this long: no longer trust it
+QUIET_AFTER_S = 6 * 3600       # idle for this long: "inattiva", not "in attesa di te"
+APP_AHEAD_S = 120              # the app saw activity this much newer than our last hook event
+PSEUDO_CHAT_WINDOW_S = 7 * 86400
+PSEUDO_CHAT_LIMIT = 15
+
+
+def _mins(sec) -> str:
+    m = int(sec // 60)
+    return f"{m} min" if m < 60 else f"{m // 60} h {m % 60:02d} min"
+
+
+def display_state(sess, chat, now):
+    """-> (code, label, detail). `sess` is the chat's latest session row or None."""
+    if chat and chat.get("archived"):
+        return "archived", "Archiviata", "La chat è archiviata nell'app."
+    if not sess:
+        return "none", "Nessun evento ricevuto", "ccmail non ha ancora visto eventi di questa chat."
+    last = sess.get("last_event_at") or 0
+    age = now - last
+    app_last = (chat or {}).get("last_activity") or 0
+    st = sess.get("state")
+    if st == "ended":
+        return "ended", "Terminata", "La sessione è stata chiusa."
+    if st == "active":
+        if age > WORKING_STALE_S:
+            return "stale", "Nessun segnale", f"Risultava al lavoro ma non arriva nulla da {_mins(age)}."
+        if age > WORKING_QUIET_S:
+            return "working", "Al lavoro", f"Nessun evento da {_mins(age)}: forse sta eseguendo un comando lungo."
+        return "working", "Al lavoro", "Claude sta lavorando."
+    # idle: Claude finished its turn
+    if app_last - last > APP_AHEAD_S:
+        return ("unknown", "Stato non certo",
+                "L'app ha registrato attività più recente di quella vista dagli hook (hook non ricevuti?).")
+    if sess.get("heartbeat_pending"):
+        return "checking", "Controllo periodico", "Claude è stato risvegliato per controllare i processi."
+    if sess.get("bg_tasks") and age > QUIET_AFTER_S:  # old knowledge: do not claim the tasks still run
+        return ("quiet", "Inattiva", f"Ferma da {_mins(age)}; l'ultimo stato noto indicava "
+                f"{sess['bg_tasks']} processo/i in background.")
+    if sess.get("bg_tasks"):
+        n = sess["bg_tasks"]
+        return ("bg", "Attende i processi in background",
+                ("1 processo in corso" if n == 1 else f"{n} processi in corso")
+                + ": Claude non aspetta una tua risposta.")
+    if age > QUIET_AFTER_S:
+        return "quiet", "Inattiva", f"Ferma da {_mins(age)}."
+    return "waiting", "In attesa di te", "Claude ha finito il turno."
+
+
+def _session_view(s):
+    return {
+        "session_id": s["session_id"], "short": s["session_id"][:8], "first_seen": s["first_seen"],
+        "last_event_at": s["last_event_at"], "last_sent_at": s["last_sent_at"],
+        "turn_start_at": s["turn_start_at"], "bg_tasks": s["bg_tasks"],
+        "bg_ids": json.loads(s.get("bg_ids") or "[]"),
+    }
+
+
+DEFAULT_CHAT_LIMIT = 5
+
+
+def projects_tree(db, now=None, app_available=False, chat_limit=DEFAULT_CHAT_LIMIT) -> dict:
+    """chat_limit: how many (non-archived) chats to return per project, newest first; 0 = all.
+    Archived chats are returned separately in `archived` and never count towards the limit."""
+    now = now or time.time()
+    projects, order = {}, []
+
+    def proj(key, name):
+        if key not in projects:
+            row = db.one("SELECT enabled FROM projects WHERE project_dir=?", (key,))
+            projects[key] = {"project_dir": key, "name": name or leaf_name(key), "enabled": True if row is None
+                             else bool(row["enabled"]), "last_activity": None, "chats": []}
+            order.append(key)
+        return projects[key]
+
+    for r in db.q("SELECT * FROM projects"):
+        p = proj(r["project_dir"], r["name"])
+        p["enabled"] = bool(r["enabled"])
+    sessions = db.q("SELECT * FROM sessions ORDER BY last_event_at DESC")
+    by_chat = {}
+    for s in sessions:
+        if s.get("chat_id"):
+            by_chat.setdefault(s["chat_id"], []).append(s)
+    for c in db.q("SELECT * FROM chats"):
+        p = proj(c["project_dir"], leaf_name(c["cwd"]))
+        ss = by_chat.get(c["chat_id"], [])
+        latest = ss[0] if ss else None
+        code, label, detail = display_state(latest, c, now)
+        act = max([x for x in (c["last_activity"], latest and latest["last_event_at"]) if x] or [0]) or None
+        p["chats"].append({"chat_id": c["chat_id"], "title": c["title"] or "(senza titolo)",
+                           "archived": bool(c["archived"]), "last_activity": act, "state": code,
+                           "state_label": label, "state_detail": detail,
+                           "session": _session_view(latest) if latest else None, "sessions_seen": len(ss)})
+    # sessions that do not belong to any app chat (plain CLI): one pseudo-chat each, recent ones only
+    seen = {}
+    for s in sessions:
+        if s.get("chat_id") or now - (s["last_event_at"] or 0) > PSEUDO_CHAT_WINDOW_S:
+            continue
+        key = s.get("project_dir") or norm_dir(s.get("cwd"))
+        if not key:
+            continue
+        p = proj(key, s.get("project"))
+        if seen.get(key, 0) >= PSEUDO_CHAT_LIMIT:
+            continue
+        seen[key] = seen.get(key, 0) + 1
+        code, label, detail = display_state(s, None, now)
+        p["chats"].append({"chat_id": None, "title": f"Sessione {s['session_id'][:8]} (fuori dall'app)",
+                           "archived": False, "last_activity": s["last_event_at"], "state": code,
+                           "state_label": label, "state_detail": detail, "session": _session_view(s),
+                           "sessions_seen": 1})
+    out = []
+    for key in order:
+        p = projects[key]
+        everything = sorted(p["chats"], key=lambda c: -(c["last_activity"] or 0))
+        live = [c for c in everything if not c["archived"]]
+        archived = [c for c in everything if c["archived"]]
+        if not everything:
+            continue
+        p["last_activity"] = max([c["last_activity"] for c in (live or archived) if c["last_activity"]] or [0]) or None
+        p["chats_total"] = len(live)
+        p["chats"] = live[:chat_limit] if chat_limit else live
+        p["chats_hidden"] = len(live) - len(p["chats"])
+        p["archived"] = archived
+        out.append(p)
+    out.sort(key=lambda p: -(p["last_activity"] or 0))
+    return {"projects": out, "app_metadata": app_available, "chat_limit": chat_limit, "generated_at": now}

ccmail/auth.py

@@ -0,0 +1,67 @@
+"""Local auth: a file token for hooks/CLI (Bearer), and cookie sessions + CSRF for the web app."""
+import hmac
+import secrets
+import threading
+import time
+
+from . import paths
+
+SESSION_TTL = 8 * 3600
+NONCE_TTL = 60
+
+
+def load_or_create_token() -> str:
+    p = paths.token_path()
+    if p.exists():
+        t = p.read_text(encoding="utf-8").strip()
+        if len(t) >= 32:
+            return t
+    t = secrets.token_urlsafe(32)
+    p.write_text(t, encoding="utf-8")
+    paths.restrict_acl(p)
+    return t
+
+
+def read_token():
+    try:
+        return paths.token_path().read_text(encoding="utf-8").strip() or None
+    except OSError:
+        return None
+
+
+class Auth:
+    def __init__(self, token: str):
+        self.token = token
+        self._lock = threading.Lock()
+        self._nonces = {}
+        self._sessions = {}
+
+    def check_bearer(self, header) -> bool:
+        if not header or not header.startswith("Bearer "):
+            return False
+        return hmac.compare_digest(header[7:].strip().encode(), self.token.encode())
+
+    def new_nonce(self) -> str:
+        n = secrets.token_urlsafe(24)
+        with self._lock:
+            self._nonces = {k: v for k, v in self._nonces.items() if v > time.time()}
+            self._nonces[n] = time.time() + NONCE_TTL
+        return n
+
+    def redeem_nonce(self, n: str):
+        """Single use. Returns (session_id, csrf) or None."""
+        with self._lock:
+            exp = self._nonces.pop(n, 0)
+            if exp < time.time():
+                return None
+            sid, csrf = secrets.token_urlsafe(32), secrets.token_urlsafe(24)
+            self._sessions[sid] = (time.time() + SESSION_TTL, csrf)
+            return sid, csrf
+
+    def session_csrf(self, sid):
+        with self._lock:
+            exp, csrf = self._sessions.get(sid or "", (0, None))
+            if exp < time.time():
+                self._sessions.pop(sid or "", None)
+                return None
+            return csrf

ccmail/autostart.py

@@ -0,0 +1,142 @@
+"""Start the daemon at logon, per operating system, for the current user only (never elevated).
+
+Windows  Task Scheduler (schtasks, ONLOGON, limited)
+macOS    LaunchAgent in ~/Library/LaunchAgents
+Linux    systemd user unit; falls back to an XDG autostart .desktop entry when systemd --user is not usable
+
+The text generators are pure functions so they can be tested on any machine.
+"""
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+TASK_NAME = "ccmail"
+LABEL = "com.ccmail.daemon"
+UNIT = "ccmail.service"
+
+
+def daemon_argv() -> list:
+    exe = sys.executable
+    if os.name == "nt":
+        w = os.path.join(os.path.dirname(exe), "pythonw.exe")
+        if os.path.exists(w):
+            exe = w
+    return [exe, "-m", "ccmail", "daemon"]
+
+
+def launchd_plist(argv: list) -> str:
+    items = "\n".join(f"    <string>{_xml(a)}</string>" for a in argv)
+    return ('<?xml version="1.0" encoding="UTF-8"?>\n'
+            '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" '
+            '"http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n'
+            '<plist version="1.0">\n<dict>\n'
+            f"  <key>Label</key>\n  <string>{LABEL}</string>\n"
+            f"  <key>ProgramArguments</key>\n  <array>\n{items}\n  </array>\n"
+            "  <key>RunAtLoad</key>\n  <true/>\n"
+            "  <key>KeepAlive</key>\n  <dict>\n    <key>SuccessfulExit</key>\n    <false/>\n  </dict>\n"
+            "</dict>\n</plist>\n")
+
+
+def systemd_unit(argv: list) -> str:
+    cmd = " ".join(_sd_quote(a) for a in argv)
+    return ("[Unit]\nDescription=ccmail - Claude Code e-mail notifications\n\n"
+            f"[Service]\nExecStart={cmd}\nRestart=on-failure\nRestartSec=5\n\n"
+            "[Install]\nWantedBy=default.target\n")
+
+
+def desktop_entry(argv: list) -> str:
+    cmd = " ".join(_sd_quote(a) for a in argv)
+    return ("[Desktop Entry]\nType=Application\nName=ccmail\nComment=Claude Code e-mail notifications\n"
+            f"Exec={cmd}\nX-GNOME-Autostart-enabled=true\nNoDisplay=true\n")
+
+
+def _xml(s: str) -> str:
+    return s.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+
+
+def _sd_quote(s: str) -> str:
+    return '"' + s.replace("\\", "\\\\").replace('"', '\\"') + '"' if (" " in s or '"' in s) else s
+
+
+def plist_path() -> Path:
+    return Path.home() / "Library" / "LaunchAgents" / f"{LABEL}.plist"
+
+
+def unit_path() -> Path:
+    base = Path(os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config")
+    return base / "systemd" / "user" / UNIT
+
+
+def desktop_path() -> Path:
+    base = Path(os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config")
+    return base / "autostart" / "ccmail.desktop"
+
+
+def _run(cmd) -> bool:
+    try:
+        flags = getattr(subprocess, "CREATE_NO_WINDOW", 0)
+        return subprocess.run(cmd, capture_output=True, timeout=30, creationflags=flags).returncode == 0
+    except (OSError, subprocess.SubprocessError):
+        return False
+
+
+def _systemd_usable() -> bool:
+    return bool(shutil.which("systemctl")) and _run(["systemctl", "--user", "show-environment"])
+
+
+def enable() -> str:
+    """Returns the mechanism used ('task-scheduler', 'launchd', 'systemd', 'xdg-autostart') or '' on failure."""
+    argv = daemon_argv()
+    if os.name == "nt":
+        cmd = ["schtasks", "/Create", "/TN", TASK_NAME, "/SC", "ONLOGON", "/RL", "LIMITED", "/F",
+               "/TR", f'"{argv[0]}" -m ccmail daemon']
+        return "task-scheduler" if _run(cmd) else ""
+    if sys.platform == "darwin":
+        p = plist_path()
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(launchd_plist(argv), encoding="utf-8")
+        uid = str(os.getuid())
+        _run(["launchctl", "bootout", f"gui/{uid}", str(p)])
+        return "launchd" if _run(["launchctl", "bootstrap", f"gui/{uid}", str(p)]) else ""
+    if _systemd_usable():
+        u = unit_path()
+        u.parent.mkdir(parents=True, exist_ok=True)
+        u.write_text(systemd_unit(argv), encoding="utf-8")
+        if _run(["systemctl", "--user", "daemon-reload"]) and _run(["systemctl", "--user", "enable", "--now", UNIT]):
+            return "systemd"
+    d = desktop_path()
+    d.parent.mkdir(parents=True, exist_ok=True)
+    d.write_text(desktop_entry(argv), encoding="utf-8")
+    return "xdg-autostart"
+
+
+def disable() -> bool:
+    ok = False
+    if os.name == "nt":
+        return _run(["schtasks", "/Delete", "/TN", TASK_NAME, "/F"])
+    if sys.platform == "darwin":
+        p = plist_path()
+        if p.exists():
+            _run(["launchctl", "bootout", f"gui/{os.getuid()}", str(p)])
+            p.unlink()
+            ok = True
+        return ok
+    if unit_path().exists():
+        _run(["systemctl", "--user", "disable", "--now", UNIT])
+        unit_path().unlink()
+        _run(["systemctl", "--user", "daemon-reload"])
+        ok = True
+    if desktop_path().exists():
+        desktop_path().unlink()
+        ok = True
+    return ok
+
+
+def is_enabled() -> bool:
+    if os.name == "nt":
+        return _run(["schtasks", "/Query", "/TN", TASK_NAME])
+    if sys.platform == "darwin":
+        return plist_path().exists()
+    return unit_path().exists() or desktop_path().exists()