pytgcli 0.9.1__tar.gz → 0.10.0__tar.gz

{pytgcli-0.9.1 → pytgcli-0.10.0}/.github/workflows/ci.yml

@@ -10,7 +10,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
       - run: uv sync --group dev
       - run: uv run ruff check
       - run: uv run ruff format --check
@@ -22,7 +22,7 @@ jobs:
         python-version: ["3.12", "3.13"]
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
       - run: uv python install ${{ matrix.python-version }}
       - run: uv sync --group dev
       - run: uv run pytest

{pytgcli-0.9.1 → pytgcli-0.10.0}/.github/workflows/publish.yml

@@ -33,7 +33,7 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: ${{ github.ref_name }}
-      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
       - run: uv build
       - uses: actions/upload-artifact@v7
         with:
@@ -76,7 +76,7 @@ jobs:
         with:
           name: dist
           path: dist
-      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
       - run: uv publish --trusted-publishing always dist/*
 
   update-homebrew-tap:
@@ -88,14 +88,15 @@ jobs:
       contents: read
     env:
       TAP_REPO: tksohishi/homebrew-tap
-      TAP_TOKEN: ${{ secrets.TAP_GH_TOKEN }}
     steps:
-      - name: Validate tap token
-        run: |
-          if [ -z "${TAP_TOKEN}" ]; then
-            echo "TAP_GH_TOKEN is required to update homebrew-tap."
-            exit 1
-          fi
+      - name: Mint tap token
+        id: tap-token
+        uses: actions/create-github-app-token@v2
+        with:
+          app-id: ${{ secrets.TAP_APP_ID }}
+          private-key: ${{ secrets.TAP_APP_PRIVATE_KEY }}
+          owner: tksohishi
+          repositories: homebrew-tap
 
       - name: Resolve PyPI source artifact
         env:
@@ -121,7 +122,7 @@ jobs:
 
       - name: Update formula in tap repo
         run: |
-          git clone "https://x-access-token:${TAP_TOKEN}@github.com/${TAP_REPO}.git" tap-repo
+          git clone "https://x-access-token:${{ steps.tap-token.outputs.token }}@github.com/${TAP_REPO}.git" tap-repo
           python3 <<'PY'
           import os
           import re

{pytgcli-0.9.1 → pytgcli-0.10.0}/AGENTS.md

@@ -9,6 +9,7 @@ src/tgcli/
   client.py       # Telethon wrapper (search, read, context)
   config.py       # Config loading (TOML + env vars)
   formatting.py   # Pure output formatting functions (no I/O)
+  media.py        # Attachment safety rules: extension allowlist, magic bytes (stdlib only)
   session.py      # Keychain-backed StringSession via keyring (cross-platform)
   update.py       # Update checking, install method detection (stdlib only)
 tests/              # pytest + pytest-asyncio, Telethon fully mocked

{pytgcli-0.9.1 → pytgcli-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: pytgcli
-Version: 0.9.1
+Version: 0.10.0
 Summary: CLI tool to read Telegram messages from the terminal
 Project-URL: Repository, https://github.com/tksohishi/tgcli
 Author: Takeshi
@@ -91,6 +91,12 @@ tg read "Finance Team" -q "deadline" --from "Alice" --after 2025-01-01
 tg context "Finance Team" 12345
 ```
 
+### 5. Download Attachments
+
+```bash
+tg media "Finance Team" 12345 --out ./downloads
+```
+
 ## Use with AI Agents
 
 Once authenticated, any AI coding agent with shell access can use tgcli directly. A few examples:
@@ -152,6 +158,22 @@ Read recent messages from a chat. Returns JSONL by default, newest first.
 | `--before`     | Only messages before date (YYYY-MM-DD) |
 | `--pretty`     | Rich table output instead of JSONL     |
 
+JSONL fields: `id`, `text`, `chat_name`, `sender_name`, `sender_username`, `sender_id`, `date`, `reply_to_msg_id`, `media_type`, `media_filename`. `media_type` is `null` or one of `photo`, `document`, `video`, `voice`, `sticker`, `webpage`, `other`; `media_filename` is the document's original filename when present. `--pretty` marks attachments with a `[photo]`-style tag.
+
+### `tg media <chat> <message_id>`
+
+Download the attachment of one message. Prints a single JSON line with `id`, `path`, and `media_type`. Fails when the message has no downloadable media (webpage previews count as no media) or the id is not found.
+
+Only known media and document types are saved (images, video, audio, PDF, office files, text). Archives (zip, 7z, tar, gz, rar) need `--allow-archives`. Executables, scripts, installers, shortcuts, disk images, HTML, SVG, and XML are refused by extension and mime type. After the transfer, the file's leading and trailing bytes are checked too: Windows, ELF, and Mach-O binaries, shebang scripts, Windows shortcuts, cabinet and installer packages, DMG and ISO images, and archives or compound files renamed to a document extension are deleted and reported. Office documents with macros, RTF, and CSV are still saved; they are documents, not programs, so open them with the same care as any attachment. Attachments are refused before transfer when the reported size exceeds `--max-size` MB (default 100), and the transfer itself is cut off at that limit.
+
+tgcli chooses the saved filename itself: `<message_id>_<sanitized original name>`, or `<media_type>_<message_id>.<ext>` when the message has no filename. It downloads into a staging file it created, never overwrites an existing file, and never follows a symlink in the output directory.
+
+| Flag               | Description                            |
+|--------------------|----------------------------------------|
+| `--out`            | Directory to save into (default cwd)   |
+| `--allow-archives` | Also download zip/7z/tar/gz/rar files  |
+| `--max-size`       | Size limit in MB (default 100)         |
+
 ### `tg update`
 
 Upgrade tgcli to the latest version. Detects the install method and runs the right command (or tells you what to run for Homebrew installs).

{pytgcli-0.9.1 → pytgcli-0.10.0}/README.md

@@ -67,6 +67,12 @@ tg read "Finance Team" -q "deadline" --from "Alice" --after 2025-01-01
 tg context "Finance Team" 12345
 ```
 
+### 5. Download Attachments
+
+```bash
+tg media "Finance Team" 12345 --out ./downloads
+```
+
 ## Use with AI Agents
 
 Once authenticated, any AI coding agent with shell access can use tgcli directly. A few examples:
@@ -128,6 +134,22 @@ Read recent messages from a chat. Returns JSONL by default, newest first.
 | `--before`     | Only messages before date (YYYY-MM-DD) |
 | `--pretty`     | Rich table output instead of JSONL     |
 
+JSONL fields: `id`, `text`, `chat_name`, `sender_name`, `sender_username`, `sender_id`, `date`, `reply_to_msg_id`, `media_type`, `media_filename`. `media_type` is `null` or one of `photo`, `document`, `video`, `voice`, `sticker`, `webpage`, `other`; `media_filename` is the document's original filename when present. `--pretty` marks attachments with a `[photo]`-style tag.
+
+### `tg media <chat> <message_id>`
+
+Download the attachment of one message. Prints a single JSON line with `id`, `path`, and `media_type`. Fails when the message has no downloadable media (webpage previews count as no media) or the id is not found.
+
+Only known media and document types are saved (images, video, audio, PDF, office files, text). Archives (zip, 7z, tar, gz, rar) need `--allow-archives`. Executables, scripts, installers, shortcuts, disk images, HTML, SVG, and XML are refused by extension and mime type. After the transfer, the file's leading and trailing bytes are checked too: Windows, ELF, and Mach-O binaries, shebang scripts, Windows shortcuts, cabinet and installer packages, DMG and ISO images, and archives or compound files renamed to a document extension are deleted and reported. Office documents with macros, RTF, and CSV are still saved; they are documents, not programs, so open them with the same care as any attachment. Attachments are refused before transfer when the reported size exceeds `--max-size` MB (default 100), and the transfer itself is cut off at that limit.
+
+tgcli chooses the saved filename itself: `<message_id>_<sanitized original name>`, or `<media_type>_<message_id>.<ext>` when the message has no filename. It downloads into a staging file it created, never overwrites an existing file, and never follows a symlink in the output directory.
+
+| Flag               | Description                            |
+|--------------------|----------------------------------------|
+| `--out`            | Directory to save into (default cwd)   |
+| `--allow-archives` | Also download zip/7z/tar/gz/rar files  |
+| `--max-size`       | Size limit in MB (default 100)         |
+
 ### `tg update`
 
 Upgrade tgcli to the latest version. Detects the install method and runs the right command (or tells you what to run for Homebrew installs).

{pytgcli-0.9.1 → pytgcli-0.10.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pytgcli"
-version = "0.9.1"
+version = "0.10.0"
 description = "CLI tool to read Telegram messages from the terminal"
 readme = "README.md"
 license = "MIT"

{pytgcli-0.9.1 → pytgcli-0.10.0}/src/tgcli/cli.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import asyncio
+import json
 import os
 import subprocess
 from datetime import UTC, datetime
@@ -23,11 +24,13 @@ app = typer.Typer(
         "Read Telegram messages from the terminal.\n\n"
         "Default output is JSONL. Use --pretty for human-readable output.\n\n"
         "Message JSONL fields: id, text, chat_name, sender_name, "
-        "sender_username, sender_id, date, reply_to_msg_id. "
+        "sender_username, sender_id, date, reply_to_msg_id, media_type, "
+        "media_filename. "
         "sender_username may be null; sender_id is the most stable sender key.\n\n"
         "Common flow: `tg chats` to find chat names, `tg read <chat>` to fetch "
         "or filter messages, `tg context <chat> <message_id>` to inspect nearby "
-        "messages, `tg auth` for login and status."
+        "messages, `tg media <chat> <message_id>` to download an attachment, "
+        "`tg auth` for login and status."
     )
 )
 auth_app = typer.Typer(
@@ -290,8 +293,11 @@ def chats(
         "Read recent messages from a chat. Newest first by default (--head for "
         "oldest).\n\n"
         "Default JSONL includes id, text, chat_name, sender_name, "
-        "sender_username, sender_id, date, and reply_to_msg_id. "
-        "sender_username may be null; sender_id is the most stable sender key.\n\n"
+        "sender_username, sender_id, date, reply_to_msg_id, media_type, and "
+        "media_filename. sender_username may be null; sender_id is the most "
+        "stable sender key. media_type is null or one of photo, document, video, "
+        "voice, sticker, webpage, other; media_filename is the document's "
+        "original filename when present.\n\n"
         "--from accepts me, @username, bare username, numeric user ID, phone, "
         "or exact display name. Display names can be ambiguous; prefer username "
         "or numeric ID for automation.\n\n"
@@ -384,8 +390,9 @@ def read(
 @app.command(
     help=(
         "View a message with surrounding context.\n\n"
-        "Default JSONL uses the same message fields as `read` and adds boolean "
-        "flags such as target and replied_to on relevant lines."
+        "Default JSONL uses the same message fields as `read` (including "
+        "media_type and media_filename) and adds boolean flags such as target "
+        "and replied_to on relevant lines."
     )
 )
 def context(
@@ -439,3 +446,64 @@ def context(
                     replied_to=(msg.id == replied_to_id),
                 )
             )
+
+
+@app.command(
+    help=(
+        "Download the attachment of one message.\n\n"
+        "Prints a single JSON line with id, path, and media_type. Fails when "
+        "the message has no downloadable media (webpage previews count as "
+        "no media) or the id is not found. Executables, scripts, installers, "
+        "and files whose content is an executable in disguise are refused. "
+        "Archives (zip, 7z, tar, ...) are refused unless --allow-archives is set. "
+        "The file is saved under a name tgcli picks (<message_id>_<original name>, "
+        "or <media_type>_<message_id>.<ext>), never overwriting an existing file."
+    )
+)
+def media(
+    chat: str,
+    message_id: int,
+    out: Annotated[
+        str,
+        typer.Option("--out", help="Directory to save into (default: cwd)."),
+    ] = ".",
+    allow_archives: Annotated[
+        bool,
+        typer.Option("--allow-archives", help="Also download zip/7z/tar archives."),
+    ] = False,
+    max_size: Annotated[
+        int,
+        typer.Option("--max-size", help="Refuse attachments larger than this many MB."),
+    ] = 100,
+) -> None:
+    """Download the attachment of one message."""
+    from tgcli.client import create_client, download_media
+
+    os.makedirs(out, exist_ok=True)
+
+    async def _run():
+        client = create_client()
+        async with client:
+            return await download_media(
+                client,
+                chat,
+                message_id,
+                out,
+                allow_archives=allow_archives,
+                max_bytes=max_size * 1024 * 1024,
+            )
+
+    try:
+        path, media_type = asyncio.run(_run())
+    except SystemExit as e:
+        stderr.print(f"[red]Configuration error:[/red] {e}")
+        stderr.print("Run `tg auth` to set up.")
+        raise typer.Exit(1)
+    except UnauthorizedError:
+        stderr.print("[red]Not authenticated.[/red] Run `tg auth login` first.")
+        raise typer.Exit(2)
+    except Exception as e:
+        stderr.print(f"[red]Download failed:[/red] {e}")
+        raise typer.Exit(1)
+
+    print(json.dumps({"id": message_id, "path": path, "media_type": media_type}))

{pytgcli-0.9.1 → pytgcli-0.10.0}/src/tgcli/client.py

@@ -1,13 +1,34 @@
 from __future__ import annotations
 
+import os
 import re
+import shutil
+import zipfile
 from datetime import datetime
 
 from telethon import TelegramClient
 from telethon.sessions import StringSession
+from telethon.tl.types import (
+    DocumentAttributeAudio,
+    DocumentAttributeFilename,
+    DocumentAttributeSticker,
+    DocumentAttributeVideo,
+    MessageMediaDocument,
+    MessageMediaPhoto,
+    MessageMediaWebPage,
+)
 
 from tgcli.config import TelegramConfig, load_config
 from tgcli.formatting import ChatData, MessageData
+from tgcli.media import (
+    DEFAULT_MAX_BYTES,
+    HEAD_SIZE,
+    ISO_MARKER_OFFSET,
+    TAIL_SIZE,
+    content_reject_reason,
+    reject_reason,
+    target_filename,
+)
 from tgcli.session import load_session
 
 _USERNAME_RE = re.compile(r"^[A-Za-z][A-Za-z0-9_]{4,31}$")
@@ -116,7 +137,33 @@ async def _resolve_sender(client: TelegramClient, chat_entity, value: str):
     )
 
 
+def _media_info(media) -> tuple[str | None, str | None]:
+    """Classify a Telethon media object as (media_type, filename)."""
+    if media is None:
+        return None, None
+    if isinstance(media, MessageMediaPhoto):
+        return "photo", None
+    if isinstance(media, MessageMediaWebPage):
+        return "webpage", None
+    if not isinstance(media, MessageMediaDocument):
+        return "other", None
+
+    attrs = getattr(media.document, "attributes", None) or []
+    filename = next(
+        (a.file_name for a in attrs if isinstance(a, DocumentAttributeFilename)),
+        None,
+    )
+    if any(isinstance(a, DocumentAttributeSticker) for a in attrs):
+        return "sticker", filename
+    if any(isinstance(a, DocumentAttributeAudio) and a.voice for a in attrs):
+        return "voice", filename
+    if any(isinstance(a, DocumentAttributeVideo) for a in attrs):
+        return "video", filename
+    return "document", filename
+
+
 def _msg_to_data(msg, chat_name: str, sender) -> MessageData:
+    media_type, media_filename = _media_info(getattr(msg, "media", None))
     return MessageData(
         id=msg.id,
         text=msg.text or "",
@@ -126,6 +173,8 @@ def _msg_to_data(msg, chat_name: str, sender) -> MessageData:
         sender_username=_get_username(sender),
         sender_id=_get_sender_id(msg, sender),
         reply_to_msg_id=msg.reply_to.reply_to_msg_id if msg.reply_to else None,
+        media_type=media_type,
+        media_filename=media_filename,
     )
 
 
@@ -280,3 +329,136 @@ async def get_context(
             replied_to = _msg_to_data(reply_msg, chat_name, sender)
 
     return messages, message_id, replied_to
+
+
+async def download_media(
+    client: TelegramClient,
+    chat: str,
+    message_id: int,
+    out_dir: str,
+    *,
+    allow_archives: bool = False,
+    max_bytes: int = DEFAULT_MAX_BYTES,
+) -> tuple[str, str]:
+    """Download the attachment of one message into out_dir.
+
+    Returns (saved_path, media_type). Raises ValueError when the message
+    does not exist, has no downloadable media, or the attachment is refused
+    by the safety rules in tgcli.media.
+
+    The transfer goes into a staging file tgcli creates itself (so the
+    sender never picks the path), is inspected, and only then linked to
+    its final name. Anything that fails on the way is removed.
+    """
+    entity = await _resolve_entity(client, chat)
+    msg = await client.get_messages(entity, ids=message_id)
+    if msg is None:
+        raise ValueError(f"Message {message_id} not found in this chat.")
+
+    media = getattr(msg, "media", None)
+    media_type, filename = _media_info(media)
+    if media_type in (None, "webpage", "other"):
+        raise ValueError(f"Message {message_id} has no downloadable media.")
+
+    document = getattr(media, "document", None)
+    mime_type = getattr(document, "mime_type", None) if document else None
+    size = getattr(document, "size", None) if document else None
+    if isinstance(size, int) and size > max_bytes:
+        raise ValueError(
+            f"Refusing to download message {message_id}: "
+            f"{size} bytes exceeds the {max_bytes} byte limit."
+        )
+
+    name = target_filename(media_type, message_id, filename, mime_type)
+    reason = reject_reason(name, mime_type, allow_archives=allow_archives)
+    if reason:
+        raise ValueError(f"Refusing to download message {message_id}: {reason}.")
+
+    staged = os.path.join(out_dir, f".tgcli-{message_id}-{os.getpid()}.part")
+    try:
+        with open(staged, "xb") as f:
+            writer = _BoundedWriter(f, max_bytes)
+            await client.download_media(msg, file=writer)
+        if writer.written == 0:
+            raise ValueError(f"Message {message_id} has no downloadable media.")
+
+        with open(staged, "rb") as f:
+            head = f.read(HEAD_SIZE)
+            f.seek(ISO_MARKER_OFFSET)
+            iso_marker = f.read(5)
+            f.seek(0, os.SEEK_END)
+            f.seek(max(0, f.tell() - TAIL_SIZE))
+            tail = f.read(TAIL_SIZE)
+        zip_members = None
+        if zipfile.is_zipfile(staged):
+            try:
+                with zipfile.ZipFile(staged) as zf:
+                    zip_members = zf.namelist()
+            except zipfile.BadZipFile:
+                zip_members = None
+        reason = content_reject_reason(
+            name,
+            head=head,
+            tail=tail,
+            iso_marker=iso_marker,
+            zip_members=zip_members,
+            allow_archives=allow_archives,
+        )
+        if reason:
+            raise ValueError(f"Refusing to keep message {message_id}: {reason}.")
+
+        final = _copy_unique(staged, os.path.join(out_dir, name))
+    finally:
+        if os.path.lexists(staged):
+            os.remove(staged)
+    return final, media_type
+
+
+class _BoundedWriter:
+    """File wrapper that aborts the transfer once max_bytes is exceeded.
+
+    Telethon only needs write(), tell(), and flush(). The pre-transfer size
+    check relies on the server-reported size; this bounds what actually
+    lands on disk regardless of what the sender or server claims.
+    """
+
+    def __init__(self, f, max_bytes: int) -> None:
+        self._f = f
+        self._max = max_bytes
+        self.written = 0
+
+    def write(self, chunk) -> int:
+        self.written += len(chunk)
+        if self.written > self._max:
+            raise ValueError(f"transfer exceeded the {self._max} byte limit")
+        return self._f.write(chunk)
+
+    def tell(self) -> int:
+        return self._f.tell()
+
+    def flush(self) -> None:
+        self._f.flush()
+
+
+def _copy_unique(src: str, dest: str) -> str:
+    """Copy src to dest, adding a counter if dest already exists.
+
+    The destination is created with O_EXCL (and O_NOFOLLOW where the
+    platform has it), so an existing file or symlink of that name, even a
+    dangling one, is never overwritten or followed. A plain copy is used
+    instead of a hard link so exFAT and SMB output directories work.
+    """
+    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL
+    flags |= getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_BINARY", 0)
+    stem, ext = os.path.splitext(dest)
+    candidate = dest
+    for i in range(1, 1000):
+        try:
+            fd = os.open(candidate, flags, 0o644)
+        except FileExistsError:
+            candidate = f"{stem} ({i}){ext}"
+            continue
+        with os.fdopen(fd, "wb") as out, open(src, "rb") as inp:
+            shutil.copyfileobj(inp, out)
+        return candidate
+    raise ValueError(f"Too many files named like {os.path.basename(dest)}.")

{pytgcli-0.9.1 → pytgcli-0.10.0}/src/tgcli/formatting.py

@@ -4,6 +4,7 @@ import json
 from dataclasses import asdict, dataclass
 from datetime import datetime
 
+from rich.markup import escape
 from rich.table import Table
 from rich.text import Text
 
@@ -27,6 +28,8 @@ class MessageData:
     sender_username: str | None = None
     sender_id: int | None = None
     reply_to_msg_id: int | None = None
+    media_type: str | None = None
+    media_filename: str | None = None
 
 
 def _truncate(text: str, max_lines: int = 3) -> str:
@@ -50,6 +53,14 @@ def format_message_jsonl(msg: MessageData, **flags: bool) -> str:
     return json.dumps(d, ensure_ascii=False)
 
 
+def _message_cell(msg: MessageData) -> str:
+    text = escape(_truncate(msg.text))
+    if msg.media_type:
+        marker = escape(f"[{msg.media_type}]")
+        return f"{text} {marker}" if text else marker
+    return text
+
+
 def format_search_results(messages: list[MessageData]) -> Table:
     """Build a Rich Table for search results."""
     table = Table(show_header=True, header_style="bold")
@@ -61,9 +72,9 @@ def format_search_results(messages: list[MessageData]) -> Table:
     for msg in messages:
         table.add_row(
             msg.date.strftime("%Y-%m-%d %H:%M"),
-            msg.chat_name,
-            msg.sender_name,
-            _truncate(msg.text),
+            escape(msg.chat_name),
+            escape(msg.sender_name),
+            _message_cell(msg),
         )
 
     return table
@@ -120,7 +131,7 @@ def format_chats_table(chats: list[ChatData]) -> Table:
     for chat in chats:
         unread = str(chat.unread_count) if chat.unread_count else ""
         date = chat.date.strftime("%Y-%m-%d") if chat.date else ""
-        table.add_row(chat.name, chat.chat_type, unread, date)
+        table.add_row(escape(chat.name), chat.chat_type, unread, date)
 
     return table