pytgcli 0.10.0__tar.gz → 0.11.0__tar.gz

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

@@ -91,7 +91,7 @@ jobs:
     steps:
       - name: Mint tap token
         id: tap-token
-        uses: actions/create-github-app-token@v2
+        uses: actions/create-github-app-token@v3
         with:
           app-id: ${{ secrets.TAP_APP_ID }}
           private-key: ${{ secrets.TAP_APP_PRIVATE_KEY }}

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pytgcli
-Version: 0.10.0
+Version: 0.11.0
 Summary: CLI tool to read Telegram messages from the terminal
 Project-URL: Repository, https://github.com/tksohishi/tgcli
 Author: Takeshi
@@ -24,13 +24,13 @@ Description-Content-Type: text/markdown
 
 # ✈️ tgcli — Telegram for your terminal and your AI agents.
 
-Give AI agents (Claude Code, Codex, Cursor, etc.) direct access to your Telegram conversations. Structured JSONL output, minimal command surface, fuzzy name resolution. Works equally well for humans with `--pretty`.
+Give AI agents (Claude Code, Codex, Cursor, etc.) direct access to your Telegram conversations. Structured JSONL output, minimal command surface, partial chat name matching. Works equally well for humans with `--pretty`.
 
 ## Features
 
 - **JSONL by default** — one JSON object per line; agents parse it natively, scripts pipe it freely
 - **Minimal surface** — a handful of commands; easy for agents to discover and invoke
-- **Fuzzy resolution** — chat and user names match by display name (no numeric IDs required)
+- **Chat name resolution**: exact display names take priority; a unique substring also matches
 - **`--pretty` for humans** — Rich tables when you want to read output yourself
 - **Agent-friendly session storage** — Telethon session key stored in a local `0600` file by default; keychain remains available as a legacy option
 
@@ -116,9 +116,12 @@ The agent runs `tg read "Alice" -q "deployment" --after 2025-02-14` and surfaces
 **Pipe into scripts:**
 
 ```bash
+set -o pipefail
 tg read "Alerts" --limit 100 | jq 'select(.text | test("ERROR"))'
 ```
 
+`pipefail` preserves a failed `tg read` exit status when `jq` succeeds. A chat lookup failure exits with code 1 and writes a human-readable error plus one JSON error line to stderr. Agents should check the exit status before treating empty stdout as “no messages.”
+
 No wrapper libraries or API adapters needed. The structured output and simple command surface mean agents can use tgcli out of the box.
 
 ## Commands
@@ -138,16 +141,41 @@ Explicit subcommands:
 
 List your Telegram chats. Returns JSONL by default.
 
+Each JSON object includes `id`, the Telethon dialog entity's numeric ID. Pass it to `read`, `context`, or `media` to skip name matching entirely:
+
+```bash
+tg chats --filter "Alice"
+tg read 123456789 --limit 20
+```
+
 | Flag       | Description                  |
 |------------|------------------------------|
-| `--filter` | Fuzzy filter by chat name    |
-| `--limit`  | Max chats to list (default 100) |
+| `--filter` | Case-insensitive substring filter by chat name |
+| `--limit`  | Max dialogs to scan before filtering (default 100) |
 | `--pretty` | Rich table output instead of JSONL |
 
+Increase `--limit` if a chat is outside the scanned set.
+
 ### `tg read <chat>`
 
 Read recent messages from a chat. Returns JSONL by default, newest first.
 
+`<chat>` accepts a display name, `@username`, phone number, `me`, or numeric ID. Display names use case-insensitive exact matching first, then substring matching. A single substring match resolves automatically, so `tg read "Alice Morgan"` can open a DM named `Alice Morgan | Example Team`. It prints `Resolved "Alice Morgan" -> "Alice Morgan | Example Team"` on stderr, keeping stdout clean for pipes. Exact matches produce no resolution notice. Multiple substring matches fail with candidate names listed one per line. If no candidates exist, the error suggests `tg chats --filter`.
+
+These lookup rules also apply to `context` and `media`. Numeric IDs, including negative group/channel IDs, skip name matching entirely. Put `--` before a negative positional ID so the CLI does not parse it as an option:
+
+```bash
+tg read --limit 20 -- -1001234567890
+```
+
+Lookup failures exit with code 1 and print both a human-readable message and a single JSON line to stderr. For an ambiguous name, the JSON looks like:
+
+```json
+{"error": "chat_not_found", "query": "Alice", "candidates": ["Alice Morgan | Example Team", "Alice Chen"]}
+```
+
+When no substring matches, similar spellings are offered as suggestions without opening a chat. `candidates` is an empty list when there are no suggestions.
+
 | Flag           | Description                            |
 |----------------|----------------------------------------|
 | `--query`/`-q` | Filter messages by text                |

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

@@ -1,12 +1,12 @@
 # ✈️ tgcli — Telegram for your terminal and your AI agents.
 
-Give AI agents (Claude Code, Codex, Cursor, etc.) direct access to your Telegram conversations. Structured JSONL output, minimal command surface, fuzzy name resolution. Works equally well for humans with `--pretty`.
+Give AI agents (Claude Code, Codex, Cursor, etc.) direct access to your Telegram conversations. Structured JSONL output, minimal command surface, partial chat name matching. Works equally well for humans with `--pretty`.
 
 ## Features
 
 - **JSONL by default** — one JSON object per line; agents parse it natively, scripts pipe it freely
 - **Minimal surface** — a handful of commands; easy for agents to discover and invoke
-- **Fuzzy resolution** — chat and user names match by display name (no numeric IDs required)
+- **Chat name resolution**: exact display names take priority; a unique substring also matches
 - **`--pretty` for humans** — Rich tables when you want to read output yourself
 - **Agent-friendly session storage** — Telethon session key stored in a local `0600` file by default; keychain remains available as a legacy option
 
@@ -92,9 +92,12 @@ The agent runs `tg read "Alice" -q "deployment" --after 2025-02-14` and surfaces
 **Pipe into scripts:**
 
 ```bash
+set -o pipefail
 tg read "Alerts" --limit 100 | jq 'select(.text | test("ERROR"))'
 ```
 
+`pipefail` preserves a failed `tg read` exit status when `jq` succeeds. A chat lookup failure exits with code 1 and writes a human-readable error plus one JSON error line to stderr. Agents should check the exit status before treating empty stdout as “no messages.”
+
 No wrapper libraries or API adapters needed. The structured output and simple command surface mean agents can use tgcli out of the box.
 
 ## Commands
@@ -114,16 +117,41 @@ Explicit subcommands:
 
 List your Telegram chats. Returns JSONL by default.
 
+Each JSON object includes `id`, the Telethon dialog entity's numeric ID. Pass it to `read`, `context`, or `media` to skip name matching entirely:
+
+```bash
+tg chats --filter "Alice"
+tg read 123456789 --limit 20
+```
+
 | Flag       | Description                  |
 |------------|------------------------------|
-| `--filter` | Fuzzy filter by chat name    |
-| `--limit`  | Max chats to list (default 100) |
+| `--filter` | Case-insensitive substring filter by chat name |
+| `--limit`  | Max dialogs to scan before filtering (default 100) |
 | `--pretty` | Rich table output instead of JSONL |
 
+Increase `--limit` if a chat is outside the scanned set.
+
 ### `tg read <chat>`
 
 Read recent messages from a chat. Returns JSONL by default, newest first.
 
+`<chat>` accepts a display name, `@username`, phone number, `me`, or numeric ID. Display names use case-insensitive exact matching first, then substring matching. A single substring match resolves automatically, so `tg read "Alice Morgan"` can open a DM named `Alice Morgan | Example Team`. It prints `Resolved "Alice Morgan" -> "Alice Morgan | Example Team"` on stderr, keeping stdout clean for pipes. Exact matches produce no resolution notice. Multiple substring matches fail with candidate names listed one per line. If no candidates exist, the error suggests `tg chats --filter`.
+
+These lookup rules also apply to `context` and `media`. Numeric IDs, including negative group/channel IDs, skip name matching entirely. Put `--` before a negative positional ID so the CLI does not parse it as an option:
+
+```bash
+tg read --limit 20 -- -1001234567890
+```
+
+Lookup failures exit with code 1 and print both a human-readable message and a single JSON line to stderr. For an ambiguous name, the JSON looks like:
+
+```json
+{"error": "chat_not_found", "query": "Alice", "candidates": ["Alice Morgan | Example Team", "Alice Chen"]}
+```
+
+When no substring matches, similar spellings are offered as suggestions without opening a chat. `candidates` is an empty list when there are no suggestions.
+
 | Flag           | Description                            |
 |----------------|----------------------------------------|
 | `--query`/`-q` | Filter messages by text                |

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

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

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

@@ -242,17 +242,43 @@ def _parse_date(value: str) -> datetime:
     return datetime.strptime(value, "%Y-%m-%d").replace(tzinfo=UTC)
 
 
+def _report_chat_resolution_error(error) -> None:
+    typer.echo(str(error), err=True)
+    typer.echo(
+        json.dumps(
+            {
+                "error": "chat_not_found",
+                "query": error.query,
+                "candidates": error.candidates,
+            },
+            ensure_ascii=False,
+        ),
+        err=True,
+    )
+
+
 @app.command()
 def chats(
     filter_: Annotated[
-        str | None, typer.Option("--filter", help="Fuzzy filter by chat name.")
+        str | None,
+        typer.Option(
+            "--filter", help="Case-insensitive substring filter by chat name."
+        ),
     ] = None,
-    limit: Annotated[int, typer.Option(help="Max chats to list.")] = 100,
+    limit: Annotated[
+        int, typer.Option(help="Max dialogs to scan before filtering.")
+    ] = 100,
     pretty: Annotated[
         bool, typer.Option("--pretty", help="Rich table output.")
     ] = False,
 ) -> None:
-    """List your Telegram chats."""
+    """List your Telegram chats.
+
+    JSONL includes id (Telethon dialog entity ID), name, chat_type,
+    unread_count, pinned, and date. Pass id to read, context, or media to
+    skip name matching entirely. Negative group/channel IDs are also accepted;
+    put options before -- and the negative ID after it: tg read -- -1001234567890.
+    """
     from tgcli.client import create_client, list_chats
 
     async def _run():
@@ -292,6 +318,13 @@ def chats(
     help=(
         "Read recent messages from a chat. Newest first by default (--head for "
         "oldest).\n\n"
+        "Chat names match case-insensitively: exact first, then a unique "
+        "substring. Substring matches print the resolved name on stderr. "
+        "Ambiguous or missing names exit 1 with a human-readable "
+        "error and one JSON line on stderr (error, query, candidates).\n\n"
+        "Pass an id from `tg chats` to skip name matching entirely. "
+        "Negative group/channel IDs are accepted: "
+        "`tg read --limit 20 -- -1001234567890`.\n\n"
         "Default JSONL includes id, text, chat_name, sender_name, "
         "sender_username, sender_id, date, reply_to_msg_id, media_type, and "
         "media_filename. sender_username may be null; sender_id is the most "
@@ -306,7 +339,9 @@ def chats(
     )
 )
 def read(
-    chat: Annotated[str, typer.Argument(help="Chat or person to read messages from.")],
+    chat: Annotated[
+        str, typer.Argument(help="Chat name, id, @username, phone, or me.")
+    ],
     query: Annotated[
         str | None, typer.Option("--query", "-q", help="Filter messages by text.")
     ] = None,
@@ -335,7 +370,7 @@ def read(
     ] = False,
 ) -> None:
     """Read recent messages from a chat."""
-    from tgcli.client import create_client, read_messages
+    from tgcli.client import ChatResolutionError, create_client, read_messages
 
     try:
         after_dt = _parse_date(after) if after else None
@@ -368,6 +403,9 @@ def read(
     except UnauthorizedError:
         stderr.print("[red]Not authenticated.[/red] Run `tg auth login` first.")
         raise typer.Exit(2)
+    except ChatResolutionError as e:
+        _report_chat_resolution_error(e)
+        raise typer.Exit(1)
     except Exception as e:
         stderr.print(f"[red]Read failed:[/red] {e}")
         raise typer.Exit(1)
@@ -390,6 +428,9 @@ def read(
 @app.command(
     help=(
         "View a message with surrounding context.\n\n"
+        "Chat names use exact matching first, then a unique case-insensitive "
+        "substring. Pass an id from `tg chats` to skip name matching. "
+        "For negative IDs, put options before -- and the ID after it.\n\n"
         "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."
@@ -406,7 +447,7 @@ def context(
     ] = False,
 ) -> None:
     """View a message with surrounding context."""
-    from tgcli.client import create_client, get_context
+    from tgcli.client import ChatResolutionError, create_client, get_context
 
     async def _run():
         client = create_client()
@@ -422,6 +463,9 @@ def context(
     except UnauthorizedError:
         stderr.print("[red]Not authenticated.[/red] Run `tg auth login` first.")
         raise typer.Exit(2)
+    except ChatResolutionError as e:
+        _report_chat_resolution_error(e)
+        raise typer.Exit(1)
     except Exception as e:
         stderr.print(f"[red]Context fetch failed:[/red] {e}")
         raise typer.Exit(1)
@@ -451,6 +495,9 @@ def context(
 @app.command(
     help=(
         "Download the attachment of one message.\n\n"
+        "Chat names use exact matching first, then a unique case-insensitive "
+        "substring. Pass an id from `tg chats` to skip name matching. "
+        "For negative IDs, put options before -- and the ID after it.\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, "
@@ -477,7 +524,7 @@ def media(
     ] = 100,
 ) -> None:
     """Download the attachment of one message."""
-    from tgcli.client import create_client, download_media
+    from tgcli.client import ChatResolutionError, create_client, download_media
 
     os.makedirs(out, exist_ok=True)
 
@@ -502,6 +549,9 @@ def media(
     except UnauthorizedError:
         stderr.print("[red]Not authenticated.[/red] Run `tg auth login` first.")
         raise typer.Exit(2)
+    except ChatResolutionError as e:
+        _report_chat_resolution_error(e)
+        raise typer.Exit(1)
     except Exception as e:
         stderr.print(f"[red]Download failed:[/red] {e}")
         raise typer.Exit(1)

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

@@ -1,14 +1,19 @@
 from __future__ import annotations
 
+import json
 import os
 import re
 import shutil
+import sys
 import zipfile
 from datetime import datetime
+from difflib import get_close_matches
 
 from telethon import TelegramClient
+from telethon.errors import UsernameInvalidError
 from telethon.sessions import StringSession
 from telethon.tl.types import (
+    ChatEmpty,
     DocumentAttributeAudio,
     DocumentAttributeFilename,
     DocumentAttributeSticker,
@@ -34,6 +39,25 @@ from tgcli.session import load_session
 _USERNAME_RE = re.compile(r"^[A-Za-z][A-Za-z0-9_]{4,31}$")
 
 
+class ChatResolutionError(ValueError):
+    def __init__(self, query: str, candidates: list[str]) -> None:
+        self.query = query
+        self.candidates = candidates
+        message = f"Cannot find chat {json.dumps(query, ensure_ascii=False)}. "
+        if candidates:
+            message += (
+                "Did you mean:\n"
+                + "\n".join(
+                    json.dumps(candidate, ensure_ascii=False)
+                    for candidate in candidates
+                )
+                + "?"
+            )
+        else:
+            message += "Use `tg chats --filter` to find exact names."
+        super().__init__(message)
+
+
 def create_client(config: TelegramConfig | None = None) -> TelegramClient:
     """Create a TelegramClient using stored session and config."""
     config = config or load_config()
@@ -80,25 +104,52 @@ async def _resolve_entity(client: TelegramClient, name: str):
     """Resolve a name to a Telethon entity.
 
     Handles @usernames, phone numbers, and numeric IDs via get_entity().
-    Plain names are matched case-insensitively against dialog names.
+    Plain names prefer exact matches, then unique case-insensitive substrings.
     """
     if name.lower() == "me":
         return await client.get_me()
 
-    if name.startswith("@") or name.startswith("+") or name.lstrip("-").isdigit():
+    if re.fullmatch(r"-?[0-9]+", name):
+        chat_id = int(name)
+        try:
+            entity = await client.get_entity(chat_id)
+            if not isinstance(entity, ChatEmpty):
+                return entity
+        except ValueError:
+            pass
+        # StringSession does not persist the entity cache across invocations.
+        async for dialog in client.iter_dialogs():
+            if (dialog.entity.id if chat_id >= 0 else dialog.id) == chat_id:
+                return dialog.entity
+        raise ChatResolutionError(name, [])
+
+    if name.startswith("@") or name.startswith("+"):
         try:
             return await client.get_entity(name)
-        except Exception:  # noqa: S110
+        except (ValueError, UsernameInvalidError):
             pass
 
     name_lower = name.lower()
+    dialogs = []
     async for dialog in client.iter_dialogs():
         if dialog.name.lower() == name_lower:
             return dialog.entity
+        dialogs.append(dialog)
+
+    matches = [dialog for dialog in dialogs if name_lower in dialog.name.lower()]
+    if len(matches) == 1:
+        print(
+            f"Resolved {json.dumps(name, ensure_ascii=False)} -> "
+            f"{json.dumps(matches[0].name, ensure_ascii=False)}",
+            file=sys.stderr,
+        )
+        return matches[0].entity
+    if matches:
+        raise ChatResolutionError(name, [dialog.name for dialog in matches])
 
-    raise ValueError(
-        f'Cannot find chat "{name}". Use `tg chats --filter` to find exact names.'
-    )
+    close_names = get_close_matches(name_lower, [d.name.lower() for d in dialogs])
+    candidates = [d.name for d in dialogs if d.name.lower() in close_names]
+    raise ChatResolutionError(name, candidates)
 
 
 async def _resolve_sender(client: TelegramClient, chat_entity, value: str):
@@ -207,6 +258,7 @@ async def list_chats(
         if not filter_lower or filter_lower in dialog.name.lower():
             results.append(
                 ChatData(
+                    id=dialog.entity.id,
                     name=dialog.name,
                     chat_type=_chat_type(dialog.entity),
                     unread_count=dialog.unread_count,

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

@@ -11,6 +11,7 @@ from rich.text import Text
 
 @dataclass(frozen=True)
 class ChatData:
+    id: int
     name: str
     chat_type: str
     unread_count: int

{pytgcli-0.10.0 → pytgcli-0.11.0}/tests/test_cli.py

@@ -1,14 +1,17 @@
 from __future__ import annotations
 
 import json
+import re
 from datetime import UTC, datetime
+from types import SimpleNamespace
 from unittest.mock import AsyncMock, MagicMock, patch
 
+import pytest
 from telethon.errors import UnauthorizedError
 from typer.testing import CliRunner
 
 from tgcli.cli import app
-from tgcli.formatting import MessageData
+from tgcli.formatting import ChatData, MessageData
 
 runner = CliRunner()
 
@@ -190,6 +193,49 @@ class TestAuthSmart:
 
 
 class TestChats:
+    @patch("tgcli.client.create_client")
+    @patch("tgcli.client.list_chats", new_callable=AsyncMock)
+    def test_chats_jsonl_includes_id(self, mock_list_chats, mock_create):
+        mock_create.return_value = AsyncMock()
+        mock_list_chats.return_value = [
+            ChatData(
+                id=123,
+                name="Mira Vale | Example",
+                chat_type="user",
+                unread_count=0,
+                pinned=False,
+                date=None,
+            )
+        ]
+
+        result = runner.invoke(app, ["chats"])
+
+        assert result.exit_code == 0
+        assert json.loads(result.stdout)["id"] == 123
+        assert result.stderr == ""
+
+    @patch("tgcli.client.create_client")
+    def test_chats_lists_entity_id_from_dialog(self, mock_create):
+        async def dialogs(**kwargs):
+            yield SimpleNamespace(
+                id=-1000000000123,
+                name="Mira Vale | Example",
+                entity=SimpleNamespace(id=123),
+                unread_count=0,
+                pinned=False,
+                date=None,
+            )
+
+        client = AsyncMock()
+        client.iter_dialogs = MagicMock(side_effect=dialogs)
+        mock_create.return_value = client
+
+        result = runner.invoke(app, ["chats", "--filter", "mira"])
+
+        assert result.exit_code == 0
+        assert json.loads(result.stdout)["id"] == 123
+        assert result.stderr == ""
+
     @patch("tgcli.client.create_client")
     @patch("tgcli.client.list_chats", new_callable=AsyncMock)
     def test_chats_unauthorized_exits_2(self, mock_list_chats, mock_create):
@@ -600,7 +646,150 @@ class TestContext:
         assert "Configuration error" in result.output
 
 
+class TestChatResolutionFailures:
+    @pytest.mark.parametrize("exact", [False, True])
+    @patch("tgcli.client.create_client")
+    def test_read_resolution_notice_keeps_stdout_jsonl(self, mock_create, exact):
+        name = "Mira Vale" if exact else "Mira Vale | Example"
+        entity = SimpleNamespace(id=123, first_name=name, last_name=None)
+        message = SimpleNamespace(
+            id=10,
+            text="hello",
+            date=datetime(2025, 6, 15, tzinfo=UTC),
+            reply_to=None,
+            media=None,
+            sender_id=123,
+            get_sender=AsyncMock(return_value=entity),
+        )
+
+        async def dialogs():
+            yield SimpleNamespace(name=name, entity=entity)
+
+        async def messages(*args, **kwargs):
+            yield message
+
+        client = AsyncMock()
+        client.iter_dialogs = MagicMock(side_effect=dialogs)
+        client.iter_messages = MagicMock(side_effect=messages)
+        mock_create.return_value = client
+
+        result = runner.invoke(app, ["read", "Mira Vale"])
+
+        assert result.exit_code == 0
+        assert json.loads(result.stdout)["chat_name"] == name
+        assert result.stderr == (
+            "" if exact else 'Resolved "Mira Vale" -> "Mira Vale | Example"\n'
+        )
+
+    @pytest.mark.parametrize("command", ["read", "context", "media"])
+    @pytest.mark.parametrize(
+        ("query", "names", "candidates"),
+        [
+            (
+                "Mira Vale",
+                ["Mira Vale | Example", "Mira Vale | Studio"],
+                ["Mira Vale | Example", "Mira Vale | Studio"],
+            ),
+            ("zzzzzz", ["Project Alpha"], []),
+            ("mira vlae", ["Mira Vale"], ["Mira Vale"]),
+        ],
+    )
+    @patch("tgcli.client.create_client")
+    def test_actual_resolver_errors_emit_json_to_stderr(
+        self, mock_create, command, query, names, candidates
+    ):
+        async def dialogs():
+            for index, name in enumerate(names):
+                yield SimpleNamespace(name=name, entity=SimpleNamespace(id=index))
+
+        client = AsyncMock()
+        client.iter_dialogs = MagicMock(side_effect=dialogs)
+        mock_create.return_value = client
+        args = [command, query]
+        if command != "read":
+            args.append("10")
+
+        result = runner.invoke(app, args)
+
+        assert result.exit_code == 1
+        assert result.stdout == ""
+        assert f'Cannot find chat "{query}"' in result.stderr
+        json_lines = [
+            line for line in result.stderr.splitlines() if line.startswith("{")
+        ]
+        assert len(json_lines) == 1
+        assert json.loads(json_lines[0]) == {
+            "error": "chat_not_found",
+            "query": query,
+            "candidates": candidates,
+        }
+        human_lines = result.stderr.splitlines()[:-1]
+        for candidate in candidates:
+            assert json.dumps(candidate) in [line.rstrip("?") for line in human_lines]
+        client.iter_dialogs.assert_called_once_with()
+
+    @pytest.mark.parametrize("command", ["read", "context", "media"])
+    @patch("tgcli.client.create_client")
+    def test_structured_error_preserves_long_and_special_names(
+        self, mock_create, command
+    ):
+        from tgcli.client import ChatResolutionError
+
+        query = 'Mira "[red]" \\ 雪\n' + "long name " * 30
+        candidates = [query + " Example", query + " Studio"]
+        mock_create.return_value = AsyncMock()
+        operation = {
+            "read": "read_messages",
+            "context": "get_context",
+            "media": "download_media",
+        }[command]
+        args = [command, query] + ([] if command == "read" else ["10"])
+        with patch(
+            f"tgcli.client.{operation}",
+            new_callable=AsyncMock,
+            side_effect=ChatResolutionError(query, candidates),
+        ):
+            result = runner.invoke(app, args)
+
+        assert result.exit_code == 1
+        assert result.stdout == ""
+        lines = [line for line in result.stderr.splitlines() if line.startswith("{")]
+        assert len(lines) == 1
+        assert json.loads(lines[0]) == {
+            "error": "chat_not_found",
+            "query": query,
+            "candidates": candidates,
+        }
+
+    @pytest.mark.parametrize("chat_id", ["123", "-123", "-1000000000123"])
+    @patch("tgcli.client.create_client")
+    def test_numeric_chat_id_reaches_resolver(self, mock_create, chat_id):
+        async def messages(*args, **kwargs):
+            if False:
+                yield
+
+        client = AsyncMock()
+        client.iter_messages = MagicMock(side_effect=messages)
+        mock_create.return_value = client
+
+        result = runner.invoke(app, ["read", "--", chat_id])
+
+        assert result.exit_code == 0
+        client.get_entity.assert_awaited_once_with(int(chat_id))
+        client.iter_dialogs.assert_not_called()
+
+
 class TestHelp:
+    @pytest.mark.parametrize("command", ["read", "chats"])
+    def test_help_describes_substring_and_numeric_ids(self, command):
+        result = runner.invoke(app, [command, "--help"])
+
+        assert result.exit_code == 0
+        plain = re.sub(r"\x1b\[[0-9;]*m", "", result.output).lower()
+        assert "substring" in plain
+        assert "id" in plain
+        assert "name matching" in plain
+
     def test_main_help(self):
         result = runner.invoke(app, ["--help"])
 
@@ -641,9 +830,13 @@ class TestHelp:
 
         assert result.exit_code == 0
         assert "media_type" in result.output
-        assert "--out" in result.output
-        assert "--allow-archives" in result.output
-        assert "no downloadable media" in result.output
+        # CI renders help with color, and Rich splits option names into
+        # several style spans, so strip ANSI codes before matching.
+        plain = re.sub(r"\x1b\[[0-9;]*m", "", result.output)
+        assert "--out" in plain
+        assert "--allow-archives" in plain
+        assert "--max-size" in plain
+        assert "no downloadable media" in plain
 
     def test_auth_help(self):
         result = runner.invoke(app, ["auth", "--help"])

{pytgcli-0.10.0 → pytgcli-0.11.0}/tests/test_client.py

@@ -6,7 +6,14 @@ from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
 
-from tgcli.client import create_client, get_context, read_messages
+from tgcli.client import (
+    ChatResolutionError,
+    _resolve_entity,
+    create_client,
+    get_context,
+    list_chats,
+    read_messages,
+)
 
 _next_entity_id = 0
 
@@ -73,6 +80,175 @@ class TestCreateClient:
         mock_tc.assert_called_once_with(mock_ss.return_value, 123, "abc")
 
 
+class TestResolveEntity:
+    @pytest.fixture()
+    def client(self):
+        client = AsyncMock()
+        client.get_entity.side_effect = ValueError("not found")
+        client.iter_dialogs = _mock_iter_dialogs()
+        return client
+
+    async def test_exact_match_precedes_substrings(self, client, capsys):
+        dialogs = [_mock_dialog("Mira Vale | Example"), _mock_dialog("Mira Vale")]
+        client.iter_dialogs = MagicMock(return_value=_async_iter(dialogs))
+
+        assert await _resolve_entity(client, "mIRA vALE") is dialogs[1].entity
+        client.iter_dialogs.assert_called_once_with()
+        client.get_entity.assert_not_awaited()
+        assert capsys.readouterr() == ("", "")
+
+    async def test_unique_substring_is_case_insensitive(self, client, capsys):
+        dialogs = [_mock_dialog("Other"), _mock_dialog("Mira Vale | Example")]
+        client.iter_dialogs = MagicMock(return_value=_async_iter(dialogs))
+
+        assert await _resolve_entity(client, "mIRA vALE") is dialogs[1].entity
+        client.iter_dialogs.assert_called_once_with()
+        captured = capsys.readouterr()
+        assert captured.out == ""
+        assert captured.err == 'Resolved "mIRA vALE" -> "Mira Vale | Example"\n'
+
+    async def test_resolution_notice_escapes_names_on_one_line(self, client, capsys):
+        query = 'Mira "[red]" \\ 雪\n'
+        client.iter_dialogs = _mock_iter_dialogs(query + "Example")
+
+        await _resolve_entity(client, query)
+
+        captured = capsys.readouterr()
+        assert captured.out == ""
+        assert captured.err == (
+            'Resolved "Mira \\"[red]\\" \\\\ 雪\\n" -> '
+            '"Mira \\"[red]\\" \\\\ 雪\\nExample"\n'
+        )
+
+    async def test_ambiguous_substring_lists_candidates(self, client):
+        candidates = ["Mira Vale | Example", "Mira Vale | Studio"]
+        client.iter_dialogs = _mock_iter_dialogs(*candidates)
+
+        with pytest.raises(ChatResolutionError) as caught:
+            await _resolve_entity(client, "Mira Vale")
+
+        assert caught.value.query == "Mira Vale"
+        assert caught.value.candidates == candidates
+        assert 'Cannot find chat "Mira Vale". Did you mean:' in str(caught.value)
+        assert '\n"Mira Vale | Example"' in str(caught.value)
+        assert '\n"Mira Vale | Studio"' in str(caught.value)
+        client.iter_dialogs.assert_called_once_with()
+
+    async def test_no_match_keeps_discovery_hint(self, client):
+        client.iter_dialogs = _mock_iter_dialogs("Project Alpha")
+
+        with pytest.raises(ChatResolutionError) as caught:
+            await _resolve_entity(client, "zzzzzz")
+
+        assert caught.value.query == "zzzzzz"
+        assert caught.value.candidates == []
+        assert 'Cannot find chat "zzzzzz".' in str(caught.value)
+        assert "Use `tg chats --filter`" in str(caught.value)
+        client.iter_dialogs.assert_called_once_with()
+
+    async def test_near_match_suggested_but_never_resolved(self, client):
+        client.iter_dialogs = _mock_iter_dialogs("Mira Vale", "Project Alpha")
+
+        with pytest.raises(ChatResolutionError) as caught:
+            await _resolve_entity(client, "mira vlae")
+
+        assert caught.value.candidates == ["Mira Vale"]
+        assert "Did you mean:" in str(caught.value)
+        client.iter_dialogs.assert_called_once_with()
+
+    @pytest.mark.parametrize("query", ["@mira_example", "+12025550123"])
+    async def test_direct_reference_precedes_names(self, client, query):
+        client.get_entity.side_effect = None
+        entity = client.get_entity.return_value
+
+        assert await _resolve_entity(client, query) is entity
+        client.get_entity.assert_awaited_once_with(query)
+        client.iter_dialogs.assert_not_called()
+
+    async def test_me_uses_current_user(self, client):
+        assert await _resolve_entity(client, "ME") is client.get_me.return_value
+        client.get_me.assert_awaited_once_with()
+        client.iter_dialogs.assert_not_called()
+
+    async def test_invalid_username_becomes_resolution_error(self, client):
+        from telethon.errors import UsernameInvalidError
+
+        client.get_entity.side_effect = UsernameInvalidError(None)
+
+        with pytest.raises(ChatResolutionError) as caught:
+            await _resolve_entity(client, "@invalid_username")
+
+        assert caught.value.query == "@invalid_username"
+        assert caught.value.candidates == []
+
+    @pytest.mark.parametrize("query", ["123", "-123", "-1000000000123"])
+    async def test_numeric_reference_is_passed_as_integer(self, client, query):
+        client.get_entity.side_effect = None
+
+        assert await _resolve_entity(client, query) is client.get_entity.return_value
+        client.get_entity.assert_awaited_once_with(int(query))
+        client.iter_dialogs.assert_not_called()
+
+    @pytest.mark.parametrize("query", ["123", "-123", "-1000000000123"])
+    async def test_uncached_id_resolves_from_dialog(self, client, query):
+        dialog = _mock_dialog("Mira Vale")
+        dialog.entity.id = 123
+        dialog.id = int(query) if query.startswith("-") else -123
+        client.iter_dialogs = MagicMock(return_value=_async_iter([dialog]))
+
+        assert await _resolve_entity(client, query) is dialog.entity
+        client.get_entity.assert_awaited_once_with(int(query))
+        client.iter_dialogs.assert_called_once_with()
+
+    async def test_missing_numeric_id_never_matches_name(self, client):
+        dialog = _mock_dialog("999999999")
+        dialog.entity.id = 123
+        dialog.id = -123
+        client.iter_dialogs = MagicMock(return_value=_async_iter([dialog]))
+
+        with pytest.raises(ChatResolutionError) as caught:
+            await _resolve_entity(client, "999999999")
+
+        assert caught.value.candidates == []
+
+    async def test_empty_chat_is_a_resolution_failure(self, client):
+        from telethon.tl.types import ChatEmpty
+
+        client.get_entity.side_effect = None
+        client.get_entity.return_value = ChatEmpty(id=123)
+
+        with pytest.raises(ChatResolutionError) as caught:
+            await _resolve_entity(client, "-123")
+
+        assert caught.value.query == "-123"
+        assert caught.value.candidates == []
+
+    async def test_authorization_errors_are_not_resolution_errors(self, client):
+        from telethon.errors import UnauthorizedError
+
+        client.get_entity.side_effect = UnauthorizedError(None, None)
+        with pytest.raises(UnauthorizedError):
+            await _resolve_entity(client, "123")
+        client.iter_dialogs.assert_not_called()
+
+
+class TestListChats:
+    async def test_json_id_uses_entity_id_and_filter_matches_substring(self):
+        dialog = _mock_dialog("Mira Vale | Example")
+        dialog.entity.id = 123
+        dialog.id = -1000000000123
+        dialog.unread_count = 2
+        dialog.date = None
+        client = AsyncMock()
+        client.iter_dialogs = MagicMock(return_value=_async_iter([dialog]))
+
+        chats = await list_chats(client, filter_name="mIRA vALE")
+
+        assert len(chats) == 1
+        assert chats[0].id == 123
+        assert chats[0].name == dialog.name
+
+
 class TestReadMessages:
     @pytest.fixture()
     def client(self):

{pytgcli-0.10.0 → pytgcli-0.11.0}/tests/test_formatting.py

@@ -6,7 +6,9 @@ from io import StringIO
 from rich.console import Console
 
 from tgcli.formatting import (
+    ChatData,
     format_auth_status,
+    format_chat_jsonl,
     format_context,
     format_message_jsonl,
     format_search_results,
@@ -19,6 +21,27 @@ def _render(renderable) -> str:
     return buf.getvalue()
 
 
+class TestFormatChatJsonl:
+    def test_includes_numeric_entity_id(self):
+        chat = ChatData(
+            id=123,
+            name="Mira Vale | Example",
+            chat_type="user",
+            unread_count=0,
+            pinned=False,
+            date=None,
+        )
+
+        assert json.loads(format_chat_jsonl(chat)) == {
+            "id": 123,
+            "name": "Mira Vale | Example",
+            "chat_type": "user",
+            "unread_count": 0,
+            "pinned": False,
+            "date": None,
+        }
+
+
 class TestFormatMessageJsonl:
     def test_basic_serialization(self, make_message):
         msg = make_message(

{pytgcli-0.10.0 → pytgcli-0.11.0}/uv.lock

@@ -667,7 +667,7 @@ wheels = [
 
 [[package]]
 name = "pytgcli"
-version = "0.10.0"
+version = "0.11.0"
 source = { editable = "." }
 dependencies = [
     { name = "keyring" },