tlgr-cli 2.0.1__py3-none-any.whl

tlgr/__init__.py

@@ -0,0 +1,3 @@
+"""tlgr — Full Telegram account control CLI."""
+
+__version__ = "2.0.1"

tlgr/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running as python -m tlgr."""
+
+from tlgr.cli import cli
+
+if __name__ == "__main__":
+    cli()

tlgr/actions/__init__.py

@@ -0,0 +1,45 @@
+"""Registry-based actions for the Gateway pipeline.
+
+Every action is an async function registered via ``@register_action``.
+Actions receive an :class:`~tlgr.gateway.event.Event`, the action's config
+from YAML, a :class:`~tlgr.jobs.client.JobClient`, and an optional
+:class:`~tlgr.processors.ProcessorChain`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from tlgr.gateway.event import Event
+from tlgr.jobs.client import JobClient
+from tlgr.processors import ProcessorChain
+
+ActionFunc = Callable[
+    [Event, Any, JobClient, ProcessorChain | None],
+    Awaitable[None],
+]
+
+_REGISTRY: dict[str, ActionFunc] = {}
+
+
+def register_action(name: str):
+    """Decorator that registers an action function under *name*."""
+
+    def decorator(func: ActionFunc) -> ActionFunc:
+        _REGISTRY[name] = func
+        return func
+
+    return decorator
+
+
+def get_action(name: str) -> ActionFunc | None:
+    return _REGISTRY.get(name)
+
+
+def list_actions() -> list[str]:
+    return list(_REGISTRY.keys())
+
+
+# Import built-in action modules so they self-register.
+from tlgr.actions import forward, reply  # noqa: E402, F401

tlgr/actions/forward.py

@@ -0,0 +1,74 @@
+"""Forward action — relay messages to one or more destinations."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any
+
+from telethon import errors
+
+from tlgr.actions import register_action
+from tlgr.filters.message import is_forwardable
+from tlgr.gateway.event import Event
+from tlgr.jobs.client import JobClient
+from tlgr.processors import ProcessorChain
+
+log = logging.getLogger("tlgr.actions.forward")
+
+
+@register_action("forward")
+async def action_forward(
+    event: Event,
+    config: Any,
+    client: JobClient,
+    chain: ProcessorChain | None = None,
+) -> None:
+    if event.source != "telegram":
+        log.warning("forward action only supports telegram events")
+        return
+
+    message = event.raw.message
+
+    ok, reason = is_forwardable(message)
+    if not ok:
+        log.debug("message not forwardable: %s", reason)
+        return
+
+    if isinstance(config, str):
+        destinations = [config]
+        drop_author = False
+    elif isinstance(config, dict):
+        to = config.get("to", [])
+        destinations = to if isinstance(to, list) else [to]
+        drop_author = config.get("drop_author", False)
+    else:
+        log.warning("invalid forward config: %r", config)
+        return
+
+    for i, dest_ref in enumerate(destinations):
+        try:
+            dest_id = await client.resolve_chat(dest_ref)
+
+            if chain:
+                original = message.text or getattr(message, "message", "") or ""
+                transformed = chain.apply(original) if original else ""
+                if message.media:
+                    await client.client.send_file(dest_id, message.media, caption=transformed)
+                else:
+                    await client.client.send_message(dest_id, transformed)
+            else:
+                await client.client.forward_messages(
+                    dest_id,
+                    message,
+                    drop_author=drop_author,
+                )
+        except errors.ChatWriteForbiddenError:
+            log.warning("cannot write to %s", dest_ref)
+        except errors.ChannelPrivateError:
+            log.warning("channel %s is private", dest_ref)
+        except Exception as e:
+            log.error("forward to %s failed: %s", dest_ref, e)
+
+        if i < len(destinations) - 1:
+            await asyncio.sleep(0.3)

tlgr/actions/reply.py

@@ -0,0 +1,32 @@
+"""Reply action — send a static text reply to the triggering message."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from tlgr.actions import register_action
+from tlgr.gateway.event import Event
+from tlgr.jobs.client import JobClient
+from tlgr.processors import ProcessorChain
+
+log = logging.getLogger("tlgr.actions.reply")
+
+
+@register_action("reply")
+async def action_reply(
+    event: Event,
+    config: Any,
+    client: JobClient,
+    chain: ProcessorChain | None = None,
+) -> None:
+    if event.source != "telegram":
+        log.warning("reply action only supports telegram events")
+        return
+
+    reply_text = str(config) if isinstance(config, str) else config.get("text", str(config))
+
+    if chain:
+        reply_text = chain.apply(reply_text)
+
+    await event.raw.reply(reply_text)

tlgr/cli/__init__.py

@@ -0,0 +1,259 @@
+"""CLI entry point using Click with nested command groups."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+import click
+
+from tlgr import __version__
+from tlgr.core.errors import TlgrError, emit_error, exit_code_for
+
+
+def _env_bool(key: str) -> bool:
+    return os.environ.get(key, "").lower() in ("1", "true", "yes", "y", "on")
+
+
+def _env_or(key: str, fallback: str) -> str:
+    return os.environ.get(key, "") or fallback
+
+
+def _registry_op(cmd_name: str, rest: list[str]) -> str | None:
+    """The canonical op id an invocation resolves to, if the registry owns it."""
+    from tlgr.registry import ALIASES
+
+    candidates = [cmd_name]
+    if rest and not rest[0].startswith("-"):
+        candidates.append(f"{cmd_name}.{rest[0]}")
+    for candidate in reversed(candidates):
+        found = ALIASES.get(candidate)
+        if found is not None:
+            return found
+    return None
+
+
+class TlgrGroup(click.Group):
+    """Custom group that handles errors, sandboxing, and output formatting."""
+
+    def invoke(self, ctx: click.Context) -> None:
+        try:
+            super().invoke(ctx)
+        except TlgrError as e:
+            use_json = ctx.params.get("json") or (ctx.obj and ctx.obj.get("json"))
+            emit_error(e, use_json=bool(use_json))
+            sys.exit(exit_code_for(e))
+        except (click.ClickException, click.exceptions.Exit, SystemExit):
+            raise
+        except KeyboardInterrupt:
+            sys.exit(130)
+        except Exception as e:
+            use_json = ctx.params.get("json") or (ctx.obj and ctx.obj.get("json"))
+            emit_error(e, use_json=bool(use_json))
+            sys.exit(1)
+
+    def resolve_command(self, ctx: click.Context, args: list[str]) -> tuple:
+        """Override to enforce --enable-commands before dispatching."""
+        cmd_name, cmd, rest = super().resolve_command(ctx, args)
+
+        enabled = ctx.params.get("enable_commands") or ""
+        enabled = enabled.strip()
+
+        # A registry-generated command enforces the allowlist itself, by
+        # canonical op id, so `--enable-commands agent.exit-codes` also allows
+        # the `exit-codes` alias (SEC-04). The path matching below is v1's and
+        # stays only for the groups that are still hand-written.
+        if enabled and cmd_name and _registry_op(cmd_name, rest) is not None:
+            return cmd_name, cmd, rest
+
+        if enabled and cmd_name:
+            allow = {p.strip().lower() for p in enabled.split(",") if p.strip()}
+            if allow and "*" not in allow and "all" not in allow:
+                name_l = cmd_name.lower()
+                group_allowed = name_l in allow
+                has_sub_rules = any(a.startswith(f"{name_l}.") for a in allow)
+                if not group_allowed and not has_sub_rules:
+                    click.echo(
+                        f"Error: command {cmd_name!r} is not enabled "
+                        f"(set --enable-commands to allow it)",
+                        err=True,
+                    )
+                    sys.exit(2)
+                if has_sub_rules and isinstance(cmd, click.Group) and rest:
+                    sub_name = rest[0] if rest else None
+                    if sub_name and not group_allowed:
+                        full_path = f"{name_l}.{sub_name.lower()}"
+                        if full_path not in allow:
+                            click.echo(
+                                f"Error: command {full_path!r} is not enabled "
+                                f"(set --enable-commands to allow it)",
+                                err=True,
+                            )
+                            sys.exit(2)
+
+        return cmd_name, cmd, rest
+
+
+@click.group(cls=TlgrGroup)
+@click.version_option(__version__, prog_name="tlgr")
+@click.option(
+    "--json",
+    "use_json",
+    is_flag=True,
+    default=_env_bool("TLGR_JSON"),
+    help="Output JSON to stdout.",
+)
+@click.option(
+    "--plain",
+    "use_plain",
+    is_flag=True,
+    default=_env_bool("TLGR_PLAIN"),
+    help="Output stable TSV for piping.",
+)
+@click.option(
+    "--account",
+    "-a",
+    default=_env_or("TLGR_ACCOUNT", ""),
+    help="Account alias to use.",
+)
+@click.option(
+    "--enable-commands",
+    default=_env_or("TLGR_ENABLE_COMMANDS", ""),
+    help="Comma-separated allowlist of commands (e.g. 'message.send,chat.list').",
+)
+@click.option(
+    "--results-only",
+    is_flag=True,
+    default=False,
+    help="In JSON mode, emit only the primary result (strip envelope).",
+)
+@click.option(
+    "--select",
+    "select_fields",
+    default=None,
+    help="In JSON mode, select comma-separated fields (supports dot paths).",
+)
+@click.option(
+    "--dry-run",
+    "-n",
+    is_flag=True,
+    default=False,
+    help="Preview destructive operations without executing.",
+)
+@click.option(
+    "--force",
+    "-y",
+    is_flag=True,
+    default=False,
+    help="Skip confirmations for destructive commands.",
+)
+@click.option(
+    "--flood-wait-max",
+    type=int,
+    default=None,
+    help="Max seconds to auto-sleep on rate limit (default from config).",
+)
+@click.option(
+    "--no-input",
+    is_flag=True,
+    default=False,
+    help="Never prompt; fail instead (CI/agent mode).",
+)
+@click.option(
+    "--verbose",
+    "-v",
+    is_flag=True,
+    default=False,
+    help="Enable verbose logging to stderr.",
+)
+@click.pass_context
+def cli(
+    ctx: click.Context,
+    use_json: bool,
+    use_plain: bool,
+    account: str | None,
+    enable_commands: str,
+    results_only: bool,
+    select_fields: str | None,
+    dry_run: bool,
+    flood_wait_max: int | None,
+    force: bool,
+    no_input: bool,
+    verbose: bool,
+) -> None:
+    """tlgr — Full Telegram account control CLI."""
+    ctx.ensure_object(dict)
+
+    # TLGR_AUTO_JSON: default to JSON when stdout is piped and env var is set
+    if _env_bool("TLGR_AUTO_JSON") and not use_json and not use_plain:
+        if not sys.stdout.isatty():
+            use_json = True
+
+    if use_json and use_plain:
+        click.echo("Error: cannot combine --json and --plain", err=True)
+        sys.exit(2)
+
+    if use_json:
+        ctx.obj["fmt"] = "json"
+    elif use_plain:
+        ctx.obj["fmt"] = "plain"
+    else:
+        ctx.obj["fmt"] = "human"
+
+    ctx.obj["json"] = use_json
+    ctx.obj["account"] = account or ""
+    ctx.obj["enable_commands"] = enable_commands
+    ctx.obj["results_only"] = results_only
+    ctx.obj["select"] = select_fields
+    ctx.obj["dry_run"] = dry_run
+    # Every command threads this through its own request body now: the
+    # generated dispatcher passes `flood_wait_max` on every `/v1/op` call, so
+    # the transport-level default the hand-written v1 commands needed (COR-15)
+    # went with them.
+    ctx.obj["flood_wait_max"] = flood_wait_max
+    ctx.obj["force"] = force
+    ctx.obj["no_input"] = no_input
+    ctx.obj["verbose"] = verbose
+
+    if verbose:
+        import logging
+
+        logging.basicConfig(
+            level=logging.DEBUG, stream=sys.stderr, format="%(levelname)s: %(message)s"
+        )
+
+
+# ---------------------------------------------------------------------------
+# Import and register sub-groups
+# ---------------------------------------------------------------------------
+
+from tlgr.cli.gen import build_click_tree  # noqa: E402
+
+# ---------------------------------------------------------------------------
+# The generated tree
+# ---------------------------------------------------------------------------
+
+
+def build_cli() -> click.Group:
+    """Install the transport and attach the generated command tree.
+
+    Every command comes from the registry now. PR-12 deleted the last
+    hand-written group, and with it the merge that let a v1 command and a
+    generated one share a name: there is one source for what `tlgr` can do,
+    so there is nothing left to reconcile.
+    """
+    import tlgr.ops  # noqa: F401  — importing it is what populates the registry
+    from tlgr.cli.gen import set_dispatcher
+    from tlgr.transport import make_dispatcher, make_stream_dispatcher
+
+    # Installing the transport here, rather than importing it in `gen.py`, is
+    # what keeps `cli/gen.py` testable with a fake dispatcher and keeps the
+    # daemon out of the CLI's import graph.
+    set_dispatcher(make_dispatcher(), make_stream_dispatcher())
+
+    for name, command in build_click_tree().items():
+        cli.add_command(command, name)
+    return cli
+
+
+build_cli()

tlgr/cli/confirm.py

@@ -0,0 +1,55 @@
+"""One confirmation path for every destructive operation.
+
+v1 asked in some commands, ignored `--no-input` in others, and would block
+forever on a prompt in a pipeline (COR-16). The rules here are absolute:
+
+* on a TTY, a destructive op prompts unless `--yes`;
+* off a TTY it *requires* `--yes` and otherwise fails with USAGE (exit 2);
+* `--no-input` never prompts and never blocks, whatever the TTY says.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Any
+
+import click
+
+from tlgr.core.errors import UsageError
+
+__all__ = ["confirm"]
+
+
+def _is_tty(stream: Any = None) -> bool:
+    stream = stream or sys.stdin
+    try:
+        return bool(stream.isatty())
+    except (AttributeError, ValueError):
+        return False
+
+
+def confirm(
+    prompt: str,
+    *,
+    force: bool = False,
+    no_input: bool = False,
+    tty: bool | None = None,
+    hint: str = "",
+) -> bool:
+    """Ask, or decide without asking. Raises UsageError when it cannot ask."""
+    if force:
+        return True
+
+    interactive = _is_tty() if tty is None else tty
+    if no_input or not interactive:
+        raise UsageError(
+            f"{prompt} — refusing to continue without --yes"
+            + (f" ({hint})" if hint else "")
+            + (
+                ". stdin is not a terminal, so there is nobody to ask."
+                if not interactive
+                else ". --no-input was given."
+            ),
+            field="yes",
+        )
+    return bool(click.confirm(prompt, default=False))

tlgr/cli/errors.py

@@ -0,0 +1,84 @@
+"""Turning an exception into output and an exit status, once.
+
+Two rules from §9:
+
+* in JSON mode the error object goes to **stdout**, so an agent parsing
+  stdout always gets JSON, and a one-line summary goes to stderr;
+* a Click usage error is formatted the same way as any other error in JSON
+  mode — v1 let Click print its own English to stderr and exited 2 with no
+  JSON at all, which is UX-02.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Any
+
+import click
+
+from tlgr.core.errors import (
+    EXIT_CANCELLED,
+    EXIT_USAGE,
+    classify,
+    error_body_dict,
+    exit_code_for,
+)
+
+__all__ = ["emit", "exit_status", "handle"]
+
+
+def _usage_body(exc: click.UsageError) -> dict[str, Any]:
+    body: dict[str, Any] = {
+        "code": "USAGE",
+        "message": exc.format_message(),
+        "error": exc.format_message(),
+        "exit_code": EXIT_USAGE,
+    }
+    if exc.ctx is not None:
+        body["usage"] = exc.ctx.get_usage()
+        body["command"] = exc.ctx.command_path
+    parameter = getattr(exc, "param", None)
+    if parameter is not None and getattr(parameter, "name", None):
+        body["field"] = parameter.name
+    return body
+
+
+def body_for(exc: BaseException) -> dict[str, Any]:
+    """The error object printed in JSON mode."""
+    if isinstance(exc, click.UsageError):
+        return _usage_body(exc)
+    return error_body_dict(classify(exc))
+
+
+def exit_status(exc: BaseException) -> int:
+    if isinstance(exc, KeyboardInterrupt):
+        return EXIT_CANCELLED
+    if isinstance(exc, click.UsageError):
+        return exc.exit_code or EXIT_USAGE
+    return exit_code_for(exc) if hasattr(exc, "exit_code") else classify(exc).exit_code
+
+
+def emit(exc: BaseException, *, use_json: bool = False, op: str = "") -> None:
+    """Write the error out: JSON to stdout when asked, a line to stderr always."""
+    body = body_for(exc)
+    if use_json:
+        import json
+
+        envelope: dict[str, Any] = {"ok": False, "error": body}
+        if op:
+            envelope["op"] = op
+        json.dump(envelope, sys.stdout, default=str, ensure_ascii=False)
+        sys.stdout.write("\n")
+        sys.stdout.flush()
+
+    message = body.get("message") or str(exc)
+    hint = body.get("hint") or getattr(exc, "hint", "")
+    print(f"Error: {message}", file=sys.stderr)
+    if hint:
+        print(f"  {hint}", file=sys.stderr)
+
+
+def handle(exc: BaseException, *, use_json: bool = False, op: str = "") -> int:
+    """Emit *exc* and return the status the process should exit with."""
+    emit(exc, use_json=use_json, op=op)
+    return exit_status(exc)