mcgram 0.2.0__py3-none-any.whl

mcgram/__init__.py

@@ -0,0 +1,3 @@
+"""mcgram - notification bridge for Claude Code (Telegram + ntfy.sh)."""
+
+__version__ = "0.2.0"

mcgram/ask_registry.py

@@ -0,0 +1,140 @@
+"""Ask registry: open a question, await operator reply (button or freetext), or time out."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import secrets
+import time
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .tg_client import TelegramClient
+
+log = logging.getLogger("mcgram.ask")
+
+
+@dataclass
+class PendingAsk:
+    question_id: str
+    future: asyncio.Future
+    message_id: int
+    chat_id: int
+    options: list[str] | None
+    posted_at: float  # epoch seconds; only replies posted AFTER this resolve the ask
+
+
+def _build_keyboard(question_id: str, options: list[str]) -> dict[str, Any]:
+    """One button per row. callback_data encodes question_id + option index."""
+    rows = [
+        [{"text": opt, "callback_data": f"{question_id}:{idx}"}]
+        for idx, opt in enumerate(options)
+    ]
+    return {"inline_keyboard": rows}
+
+
+class AskRegistry:
+    """In-process map of open questions; handler resolves each on operator reply or timeout."""
+
+    def __init__(self) -> None:
+        self._pending: dict[str, PendingAsk] = {}
+
+    @property
+    def open_count(self) -> int:
+        return len(self._pending)
+
+    async def open(
+        self,
+        client: TelegramClient,
+        *,
+        chat_id: int,
+        question: str,
+        options: list[str] | None,
+        timeout_s: int,
+    ) -> dict[str, Any]:
+        q_id = "q_" + secrets.token_hex(4)
+        reply_markup = _build_keyboard(q_id, options) if options else None
+        msg = await client.send_message(chat_id, question, reply_markup=reply_markup)
+        loop = asyncio.get_running_loop()
+        fut: asyncio.Future = loop.create_future()
+        self._pending[q_id] = PendingAsk(
+            question_id=q_id,
+            future=fut,
+            message_id=msg["message_id"],
+            chat_id=chat_id,
+            options=options,
+            posted_at=time.time(),
+        )
+        try:
+            value, source = await asyncio.wait_for(fut, timeout=timeout_s)
+            await _strip_keyboard(client, chat_id, msg["message_id"])
+            return {"value": value, "source": source, "question_id": q_id}
+        except TimeoutError:
+            await _mark_timed_out(client, chat_id, msg["message_id"], question)
+            return {"value": "", "source": "timeout", "question_id": q_id}
+        finally:
+            self._pending.pop(q_id, None)
+
+    async def handle_update(self, update: dict[str, Any]) -> None:
+        if cq := update.get("callback_query"):
+            await self._handle_callback(cq)
+            return
+        if msg := update.get("message"):
+            self._handle_message(msg)
+
+    async def _handle_callback(self, cq: dict[str, Any]) -> None:
+        data = cq.get("data", "")
+        q_id, _, idx_str = data.partition(":")
+        pending = self._pending.get(q_id)
+        if pending and pending.options and idx_str.isdigit():
+            idx = int(idx_str)
+            if 0 <= idx < len(pending.options) and not pending.future.done():
+                pending.future.set_result((pending.options[idx], "button"))
+        # Always answer the callback so Telegram stops showing a spinner.
+        # The client reference travels via the registry's known client (passed at open()).
+        # Since handle_update lives on AppState, we look up the client via cq's bot wiring:
+        # in mcgram, the dispatcher passes the raw update; we don't have client here.
+        # The runtime injects an `_answer` hook below.
+        if self._answer_hook is not None:
+            try:
+                await self._answer_hook(cq["id"])
+            except Exception:
+                log.exception("answer_callback_query failed")
+
+    def _handle_message(self, msg: dict[str, Any]) -> None:
+        chat_id = msg.get("chat", {}).get("id")
+        text = msg.get("text") or ""
+        msg_ts = float(msg.get("date") or 0)
+        # Resolve the oldest pending ask in the same chat posted before this message.
+        candidates = sorted(
+            (p for p in self._pending.values() if p.chat_id == chat_id and msg_ts > p.posted_at),
+            key=lambda p: p.posted_at,
+        )
+        for p in candidates:
+            if not p.future.done():
+                p.future.set_result((text, "freetext"))
+                break
+
+    # Hook injected by server bootstrap so we can call answer_callback_query
+    # without making the registry import the client (avoids cycle in runtime).
+    _answer_hook: Any = None
+
+    def set_answer_hook(self, hook: Any) -> None:
+        self._answer_hook = hook
+
+
+async def _strip_keyboard(client: TelegramClient, chat_id: int, message_id: int) -> None:
+    try:
+        await client.edit_message_reply_markup(chat_id, message_id, reply_markup=None)
+    except Exception:
+        log.debug("edit_message_reply_markup failed (non-fatal)", exc_info=True)
+
+
+async def _mark_timed_out(
+    client: TelegramClient, chat_id: int, message_id: int, question: str
+) -> None:
+    try:
+        await client.edit_message_text(chat_id, message_id, f"{question}\n\n(timed out)")
+    except Exception:
+        log.debug("edit_message_text on timeout failed (non-fatal)", exc_info=True)

mcgram/audit.py

@@ -0,0 +1,144 @@
+"""JSONL audit logger with fsync, rotation, retention, and optional text redaction."""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import logging
+import os
+import threading
+import time
+from datetime import UTC, datetime, timedelta, tzinfo
+from pathlib import Path
+from typing import Any
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+log = logging.getLogger("mcgram.audit")
+
+_PRUNE_INTERVAL_S = 3600.0
+
+
+def _resolve_tz(name: str) -> tzinfo:
+    try:
+        return ZoneInfo(name)
+    except ZoneInfoNotFoundError:
+        log.warning("unknown timezone %r; falling back to UTC", name)
+        try:
+            return ZoneInfo("UTC")
+        except ZoneInfoNotFoundError:
+            return UTC
+
+
+class AuditLog:
+    """Thread-safe append-only JSONL writer.
+
+    Each record is one JSON line with `ts`, `tool`, `status` keys at minimum.
+    `fsync` is called per-write so a `kill -9` still preserves the audit trail.
+    """
+
+    def __init__(
+        self,
+        path: str | Path,
+        rotate_mb: int = 25,
+        timezone: str = "UTC",
+        redact_text: bool = False,
+        retention_days: int | None = None,
+    ) -> None:
+        self.path = str(Path(path).expanduser())
+        self.rotate_bytes = max(1, rotate_mb) * 1024 * 1024
+        self.redact_text = redact_text
+        self.retention_days = retention_days
+        self._tz = _resolve_tz(timezone)
+        self._lock = threading.Lock()
+        self._last_prune_ts = 0.0
+        Path(self.path).parent.mkdir(parents=True, exist_ok=True)
+        if retention_days:
+            with self._lock:
+                self._prune_old_entries()
+
+    def write(self, record: dict[str, Any]) -> None:
+        """Append a record. `ts` is set automatically if missing."""
+        rec = dict(record)
+        rec.setdefault("ts", datetime.now(self._tz).isoformat(timespec="seconds"))
+        if self.redact_text and "text" in rec:
+            text = rec["text"]
+            if isinstance(text, str):
+                rec["text_len"] = len(text)
+                rec["text"] = "<redacted>"
+        line = json.dumps(rec, ensure_ascii=False, default=str) + "\n"
+        with self._lock:
+            self._maybe_rotate()
+            self._maybe_prune()
+            with open(self.path, "a", encoding="utf-8") as f:
+                f.write(line)
+                f.flush()
+                os.fsync(f.fileno())
+
+    def _maybe_rotate(self) -> None:
+        try:
+            size = os.path.getsize(self.path)
+        except FileNotFoundError:
+            return
+        if size < self.rotate_bytes:
+            return
+        tail = f"{self.path}.3"
+        if os.path.exists(tail):
+            try:
+                os.remove(tail)
+            except OSError as e:
+                log.warning("rotate: failed to remove %s: %s", tail, e)
+                return
+        for i in (3, 2, 1):
+            src = self.path if i == 1 else f"{self.path}.{i - 1}"
+            dst = f"{self.path}.{i}"
+            if os.path.exists(src):
+                try:
+                    os.replace(src, dst)
+                except OSError as e:
+                    log.warning("rotate: %s -> %s failed: %s", src, dst, e)
+                    return
+
+    def _maybe_prune(self) -> None:
+        if not self.retention_days:
+            return
+        now = time.monotonic()
+        if now - self._last_prune_ts < _PRUNE_INTERVAL_S:
+            return
+        self._prune_old_entries()
+
+    def _prune_old_entries(self) -> None:
+        if not self.retention_days:
+            return
+        cutoff = datetime.now(self._tz) - timedelta(days=self.retention_days)
+        for path in (self.path, f"{self.path}.1", f"{self.path}.2", f"{self.path}.3"):
+            if os.path.exists(path):
+                _rewrite_newer_than(path, cutoff)
+        self._last_prune_ts = time.monotonic()
+
+
+def _rewrite_newer_than(path: str, cutoff: datetime) -> None:
+    tmp = f"{path}.tmp"
+    try:
+        with open(path, encoding="utf-8") as src:
+            kept = [line for line in src if _entry_newer_than(line, cutoff)]
+        with open(tmp, "w", encoding="utf-8") as dst:
+            dst.writelines(kept)
+            dst.flush()
+            os.fsync(dst.fileno())
+        os.replace(tmp, path)
+    except OSError as e:
+        log.warning("prune: rewrite %s failed: %s", path, e)
+        with contextlib.suppress(OSError):
+            os.remove(tmp)
+
+
+def _entry_newer_than(line: str, cutoff: datetime) -> bool:
+    """Keep entries with `ts >= cutoff`. Malformed lines kept (fail-safe)."""
+    try:
+        rec = json.loads(line)
+        ts = datetime.fromisoformat(rec["ts"])
+        if ts.tzinfo is None:
+            ts = ts.replace(tzinfo=cutoff.tzinfo)
+        return ts >= cutoff
+    except (json.JSONDecodeError, ValueError, KeyError, TypeError):
+        return True

mcgram/cli.py

@@ -0,0 +1,72 @@
+"""CLI dispatcher for mcgram. Lazy-imports heavy submodules for <500ms startup."""
+
+from __future__ import annotations
+
+import sys
+
+from . import __version__
+
+_HELP = """\
+mcgram — notification bridge MCP for Claude Code (Telegram + ntfy.sh).
+
+USAGE:
+  mcgram                          start the MCP stdio server (expects MCGRAM_CONFIG)
+  mcgram init [--force]           scaffold ~/.mcgram/ + install Claude Code skill
+  mcgram doctor                   check config + transport connectivity (sends test pings)
+  mcgram audit [opts]             analyze audit.jsonl (--since, --tool, --rejected, --tail)
+  mcgram channel list             list configured channels (both transports)
+  mcgram channel add NAME CHAT_ID add a Telegram channel
+  mcgram channel add-ntfy NAME    add a ntfy.sh channel (auto-generates topic)
+  mcgram channel remove NAME      remove a channel
+  mcgram install-skill [--force]  install / reinstall ~/.claude/skills/mcgram/SKILL.md
+  mcgram clear-lock               remove stale ~/.mcgram/.lock (use if MCP fails to start)
+  mcgram --version                print version
+  mcgram --help                   print this help
+"""
+
+
+def main() -> None:
+    args = sys.argv[1:]
+    if args:
+        first = args[0]
+        if first in {"-V", "--version", "version"}:
+            print(f"mcgram {__version__}")
+            return
+        if first in {"-h", "--help", "help"}:
+            sys.stdout.write(_HELP)
+            return
+        if first == "init":
+            from .cli_init import init_config
+            force = "--force" in args[1:]
+            sys.exit(init_config(force=force))
+        if first == "doctor":
+            from .cli_doctor import doctor
+            sys.exit(doctor())
+        if first == "audit":
+            from .cli_audit import main as audit_main
+            sys.exit(audit_main(args[1:]))
+        if first == "channel":
+            from .cli_channel import main as channel_main
+            sys.exit(channel_main(args[1:]))
+        if first == "install-skill":
+            from .skill_installer import install_skill
+            force = "--force" in args[1:]
+            sys.exit(install_skill(force=force))
+        if first == "clear-lock":
+            from pathlib import Path
+            lock = Path("~/.mcgram/.lock").expanduser()
+            if lock.exists():
+                lock.unlink()
+                print(f"removed  {lock}")
+            else:
+                print(f"no lock file at {lock} (already clean)")
+            sys.exit(0)
+        print(f"unknown argument: {first}. Try `mcgram --help`.", file=sys.stderr)
+        sys.exit(2)
+    # No args → run MCP stdio server.
+    from .server import main as server_main
+    server_main()
+
+
+if __name__ == "__main__":
+    main()

mcgram/cli_audit.py

@@ -0,0 +1,191 @@
+"""`mcgram audit` — analyze audit.jsonl (+ rotated backups). dbread-equivalent flags."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+import time
+from collections.abc import Iterator
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+_DUR_RE = re.compile(r"^\s*(\d+)\s*([smhd])\s*$", re.IGNORECASE)
+_UNIT_SECS = {"s": 1, "m": 60, "h": 3600, "d": 86400}
+
+
+def _parse_duration(s: str) -> timedelta:
+    m = _DUR_RE.match(s)
+    if not m:
+        raise ValueError(f"bad duration {s!r}; expected e.g. 1h, 30m, 7d")
+    return timedelta(seconds=int(m.group(1)) * _UNIT_SECS[m.group(2).lower()])
+
+
+def _rotated_paths(base: str) -> list[str]:
+    paths = [f"{base}.3", f"{base}.2", f"{base}.1", base]
+    return [p for p in paths if os.path.exists(p)]
+
+
+def _parse_ts(raw: str) -> datetime | None:
+    try:
+        return datetime.fromisoformat(raw)
+    except (ValueError, TypeError):
+        return None
+
+
+def _iter_entries(
+    base: str, *, since: timedelta | None = None, tool: str | None = None
+) -> Iterator[dict[str, Any]]:
+    cutoff = datetime.now(UTC) - since if since else None
+    for path in _rotated_paths(base):
+        try:
+            with open(path, encoding="utf-8") as f:
+                for line in f:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        rec = json.loads(line)
+                    except json.JSONDecodeError:
+                        continue
+                    if tool and rec.get("tool") != tool:
+                        continue
+                    if cutoff is not None:
+                        ts = _parse_ts(rec.get("ts", ""))
+                        if ts is None:
+                            continue
+                        if ts.tzinfo is None:
+                            ts = ts.replace(tzinfo=UTC)
+                        if ts < cutoff:
+                            continue
+                    yield rec
+        except OSError:
+            continue
+
+
+def _summarize(entries: list[dict[str, Any]]) -> dict[str, Any]:
+    status_counts: dict[str, int] = {}
+    reason_counts: dict[str, int] = {}
+    tool_counts: dict[str, int] = {}
+    for rec in entries:
+        status_counts[rec.get("status", "?")] = status_counts.get(rec.get("status", "?"), 0) + 1
+        tool_counts[rec.get("tool", "?")] = tool_counts.get(rec.get("tool", "?"), 0) + 1
+        if rec.get("status") == "rejected":
+            r = rec.get("reason", "unknown")
+            reason_counts[r] = reason_counts.get(r, 0) + 1
+    return {
+        "total": len(entries),
+        "status": status_counts,
+        "tool": tool_counts,
+        "rejected_reasons": reason_counts,
+    }
+
+
+def _fmt_summary(s: dict[str, Any]) -> str:
+    out = [f"Total entries: {s['total']}", "", "Status:"]
+    for k, n in sorted(s["status"].items(), key=lambda x: -x[1]):
+        out.append(f"  {k:<12} {n}")
+    out.append("")
+    out.append("By tool:")
+    for k, n in sorted(s["tool"].items(), key=lambda x: -x[1]):
+        out.append(f"  {k:<20} {n}")
+    if s["rejected_reasons"]:
+        out.append("")
+        out.append("Rejection reasons:")
+        for r, n in sorted(s["rejected_reasons"].items(), key=lambda x: -x[1]):
+            out.append(f"  {n:>5}  {r}")
+    return "\n".join(out)
+
+
+def _fmt_rejected(entries: list[dict[str, Any]]) -> str:
+    groups: dict[str, list[dict[str, Any]]] = {}
+    for rec in entries:
+        if rec.get("status") != "rejected":
+            continue
+        groups.setdefault(rec.get("reason", "unknown"), []).append(rec)
+    if not groups:
+        return "No rejections found."
+    out: list[str] = []
+    for reason, recs in sorted(groups.items(), key=lambda x: -len(x[1])):
+        out.append(f"[{len(recs)}] {reason}")
+        for r in recs[:5]:
+            out.append(f"    {r.get('ts','?')}  [{r.get('tool','?')}]  {r}")
+        if len(recs) > 5:
+            out.append(f"    ... +{len(recs) - 5} more")
+    return "\n".join(out)
+
+
+def _tail(base: str, tool: str | None) -> int:
+    path = base
+    pos = os.path.getsize(path) if os.path.exists(path) else 0
+    while True:
+        try:
+            size = os.path.getsize(path)
+        except FileNotFoundError:
+            time.sleep(1)
+            continue
+        if size < pos:
+            pos = 0
+        if size > pos:
+            with open(path, encoding="utf-8") as f:
+                f.seek(pos)
+                for line in f:
+                    if not line.strip():
+                        continue
+                    try:
+                        rec = json.loads(line)
+                    except json.JSONDecodeError:
+                        continue
+                    if tool and rec.get("tool") != tool:
+                        continue
+                    sys.stdout.write(line if line.endswith("\n") else line + "\n")
+                    sys.stdout.flush()
+                pos = f.tell()
+        time.sleep(1)
+
+
+def _default_audit_path() -> str:
+    env = os.environ.get("MCGRAM_AUDIT_PATH")
+    if env:
+        return str(Path(env).expanduser())
+    cfg = os.environ.get("MCGRAM_CONFIG")
+    if cfg:
+        try:
+            from .config import Settings
+            return Settings.load(cfg).audit.path
+        except Exception:
+            pass
+    return str(Path("~/.mcgram/audit.jsonl").expanduser())
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(prog="mcgram audit", description="Analyze audit.jsonl")
+    p.add_argument("--path", default=None, help="override audit.jsonl path")
+    p.add_argument("--since", help="e.g. 1h, 30m, 7d")
+    p.add_argument("--tool", help="filter by tool name")
+    p.add_argument("--rejected", action="store_true", help="show only rejections grouped")
+    p.add_argument("--tail", action="store_true", help="follow new entries")
+    args = p.parse_args(argv)
+
+    base = args.path or _default_audit_path()
+    if args.tail:
+        try:
+            return _tail(base, args.tool)
+        except KeyboardInterrupt:
+            return 0
+
+    since = _parse_duration(args.since) if args.since else None
+    entries = list(_iter_entries(base, since=since, tool=args.tool))
+    if not entries:
+        suffix = " (filtered)" if (since or args.tool) else ""
+        print(f"No audit entries found at {base}{suffix}")
+        return 0
+
+    if args.rejected:
+        print(_fmt_rejected(entries))
+    else:
+        print(_fmt_summary(_summarize(entries)))
+    return 0