tlgr-cli 2.0.1__py3-none-any.whl

tlgr/cli/globals.py

@@ -0,0 +1,273 @@
+"""The global flags, attached to every generated command *and* to the root.
+
+`tlgr chat list --json` and `tlgr --json chat list` must both work. In v1 only
+the second did, and the first exited 2 with "No such option" (UX-01), which is
+the single most common thing an agent gets wrong on its first call. The flags
+are therefore declared once here and attached in both places; a command-level
+value wins over a root-level one.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Any
+
+import click
+
+__all__ = [
+    "GLOBAL_FLAG_NAMES",
+    "CliState",
+    "add_global_options",
+    "env_bool",
+    "resolve_account",
+    "state_from",
+]
+
+
+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
+
+
+#: Parameter names the generator must never collide with when deriving flags
+#: from request fields.
+GLOBAL_FLAG_NAMES = frozenset(
+    {
+        "use_json",
+        "use_plain",
+        "account",
+        "results_only",
+        "select_fields",
+        "dry_run",
+        "force",
+        "no_input",
+        "flood_wait_max",
+        "timeout",
+        "verbose",
+        "no_daemon_restart",
+        "enable_commands",
+        "columns",
+        "wide",
+        "no_header",
+        # Pagination is transport-level, not part of any request struct
+        # (registry lint L5 forbids those field names), so the generated
+        # flags land here and travel to the daemon beside the request.
+        "limit",
+        "cursor",
+        "fetch_all",
+    }
+)
+
+
+@dataclass
+class CliState:
+    """The merged view of the global flags for one invocation."""
+
+    fmt: str = "human"
+    account: str = ""
+    results_only: bool = False
+    select: str | None = None
+    dry_run: bool = False
+    force: bool = False
+    no_input: bool = False
+    flood_wait_max: int | None = None
+    timeout: float | None = None
+    verbose: bool = False
+    no_daemon_restart: bool = False
+    enable_commands: str = ""
+    columns: str | None = None
+    wide: bool = False
+    no_header: bool = False
+    limit: int | None = None
+    cursor: str | None = None
+    fetch_all: bool = False
+    warnings: list[str] = field(default_factory=list)
+
+    @property
+    def json(self) -> bool:
+        return self.fmt == "json"
+
+
+def _flag_options() -> list[Any]:
+    """The option decorators, built fresh so Click never shares a Parameter."""
+    return [
+        click.option(
+            "--json", "use_json", is_flag=True, default=None, help="Output JSON to stdout."
+        ),
+        click.option(
+            "--plain", "use_plain", is_flag=True, default=None, help="Output stable TSV for piping."
+        ),
+        click.option(
+            "--account",
+            "-a",
+            default=None,
+            metavar="ALIAS",
+            help="Account alias to use.  [env: TLGR_ACCOUNT]",
+        ),
+        click.option(
+            "--results-only",
+            is_flag=True,
+            default=None,
+            help="In JSON mode, print only the result (no envelope).",
+        ),
+        click.option(
+            "--select",
+            "select_fields",
+            default=None,
+            metavar="FIELDS",
+            help="Project comma-separated fields out of the result (dot paths allowed).",
+        ),
+        click.option(
+            "--columns", default=None, metavar="COLS", help="Override the human/plain columns."
+        ),
+        click.option("--wide", is_flag=True, default=None, help="Do not truncate any column."),
+        click.option("--no-header", is_flag=True, default=None, help="Omit the header row."),
+        click.option(
+            "--yes", "-y", "force", is_flag=True, default=None, help="Skip confirmations."
+        ),
+        click.option(
+            "--no-input", is_flag=True, default=None, help="Never prompt; fail instead (CI/agent)."
+        ),
+        click.option(
+            "--flood-wait-max",
+            type=int,
+            default=None,
+            help="Max seconds to auto-sleep on a rate limit.",
+        ),
+        click.option("--timeout", type=float, default=None, help="Client-side timeout in seconds."),
+        click.option(
+            "--no-daemon-restart",
+            is_flag=True,
+            default=None,
+            help="Never restart the daemon automatically.",
+        ),
+        click.option(
+            "--enable-commands",
+            default=None,
+            metavar="IDS",
+            help="Comma-separated allowlist of operation ids.",
+        ),
+        click.option("--verbose", "-v", is_flag=True, default=None, help="Verbose logging."),
+    ]
+
+
+def add_global_options(command: Any) -> Any:
+    """Attach every global flag to *command*.
+
+    Defaults are `None` rather than `False` so that "not given here" stays
+    distinguishable from "given as false", which is what lets a command-level
+    flag override a root-level one without clobbering it.
+    """
+    for decorator in reversed(_flag_options()):
+        command = decorator(command)
+    return command
+
+
+def _merge(target: dict[str, Any], params: dict[str, Any]) -> None:
+    """Fold command-level flag values over the root-level ones."""
+    for key, value in params.items():
+        if value is not None and key in GLOBAL_FLAG_NAMES:
+            target[key] = value
+
+
+def state_from(ctx: click.Context, params: dict[str, Any] | None = None) -> CliState:
+    """Build the merged `CliState` for this invocation."""
+    merged: dict[str, Any] = dict(ctx.obj or {})
+    if params:
+        _merge(merged, params)
+
+    use_json = merged.get("use_json")
+    use_plain = merged.get("use_plain")
+    if use_json is None:
+        use_json = merged.get("json") or env_bool("TLGR_JSON")
+    if use_plain is None:
+        use_plain = env_bool("TLGR_PLAIN")
+    if use_json and use_plain:
+        raise click.UsageError("cannot combine --json and --plain")
+
+    fmt = merged.get("fmt", "human")
+    if use_json:
+        fmt = "json"
+    elif use_plain:
+        fmt = "plain"
+
+    return CliState(
+        fmt=fmt,
+        account=merged.get("account") or "",
+        results_only=bool(merged.get("results_only")),
+        select=merged.get("select_fields") or merged.get("select"),
+        dry_run=bool(merged.get("dry_run")),
+        force=bool(merged.get("force")),
+        no_input=bool(merged.get("no_input")),
+        flood_wait_max=merged.get("flood_wait_max"),
+        timeout=merged.get("timeout"),
+        verbose=bool(merged.get("verbose")),
+        no_daemon_restart=bool(merged.get("no_daemon_restart")),
+        enable_commands=merged.get("enable_commands") or "",
+        columns=merged.get("columns"),
+        wide=bool(merged.get("wide")),
+        no_header=bool(merged.get("no_header")),
+        limit=merged.get("limit"),
+        cursor=merged.get("cursor"),
+        fetch_all=bool(merged.get("fetch_all")),
+    )
+
+
+def _require_account_enabled() -> bool:
+    """`TLGR_REQUIRE_ACCOUNT`, else `[defaults] require_account`."""
+    env = os.environ.get("TLGR_REQUIRE_ACCOUNT", "").strip().lower()
+    if env in ("1", "true", "yes", "on"):
+        return True
+    if env in ("0", "false", "no", "off"):
+        return False
+    try:
+        from tlgr.core.config import load_app_config
+
+        return bool(load_app_config().defaults.require_account)
+    except Exception:
+        return False
+
+
+def resolve_account(
+    state: CliState,
+    *,
+    positional: str | None = None,
+    require: bool | None = None,
+) -> str:
+    """Resolve the account, in one place, in one order.
+
+    positional → `-a/--account` → `TLGR_ACCOUNT` → `[accounts] default` →
+    the active alias. The daemon never picks for you (COR-02); when nothing
+    resolves and the operation needs one, that is a USAGE error naming the
+    ways to supply it.
+    """
+    alias = (positional or state.account or _env_or("TLGR_ACCOUNT")).strip()
+
+    if not alias:
+        try:
+            from tlgr.core.config import load_app_config
+            from tlgr.core.paths import default_base
+
+            alias = (load_app_config().default_account or "").strip()
+            if not alias:
+                from tlgr.core.accounts import AccountManager
+
+                # `default_base()` rather than the `CONFIG_DIR` constant:
+                # that one is captured at import, so a `TLGR_HOME` set after
+                # the first import was ignored here and the CLI read the
+                # *real* home — which is how a development run reaches a
+                # production tree at all.
+                alias = (AccountManager(default_base()).get_active() or "").strip()
+        except Exception:
+            alias = ""
+
+    if not alias and (require or (require is None and _require_account_enabled())):
+        raise click.UsageError(
+            "No account specified. Pass -a <alias>, set TLGR_ACCOUNT, or set "
+            "[accounts] default in config.toml (see: tlgr account list)."
+        )
+    return alias

tlgr/cli/introspect.py

@@ -0,0 +1,170 @@
+"""Describing the Click tree for `tlgr schema`.
+
+The walker itself is v1's, kept because the schema document still has to
+describe every not-yet-migrated command; what changed is where the examples
+come from. v1 hand-maintained `EXAMPLE_RESPONSES` and covered 26 of 93
+commands (COR-33); now an example is the spec's, validated by a test.
+
+This lives in `cli/` because only the CLI knows what the CLI looks like;
+`tlgr/schema.py` sits below it and is handed the result.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+
+__all__ = ["describe"]
+
+
+def _param_type_name(param: click.Parameter) -> str:
+    """Return a stable type name for a Click parameter."""
+    t = param.type
+    if isinstance(t, click.Choice):
+        return "choice"
+    if isinstance(t, click.IntRange):
+        return "int"
+    if isinstance(t, click.FloatRange):
+        return "float"
+    name = getattr(t, "name", type(t).__name__)
+    return str(name).lower()
+
+
+def _build_param(param: click.Parameter) -> dict[str, Any]:
+    """Serialize a Click parameter to a schema dict."""
+    entry: dict[str, Any] = {"name": param.name or ""}
+
+    if isinstance(param, click.Option):
+        entry["type"] = "option"
+        opts = list(param.opts) + list(param.secondary_opts)
+        entry["flags"] = sorted(opts)
+        entry["is_flag"] = getattr(param, "is_flag", False)
+    elif isinstance(param, click.Argument):
+        entry["type"] = "argument"
+        entry["required"] = param.required
+        if param.nargs != 1:
+            entry["nargs"] = param.nargs
+    else:
+        entry["type"] = "parameter"
+
+    entry["param_type"] = _param_type_name(param)
+
+    if isinstance(param.type, click.Choice):
+        entry["choices"] = list(param.type.choices)
+
+    is_flag = getattr(param, "is_flag", False)
+    default = param.default
+    if (
+        default is not None
+        and default != ()
+        and not is_flag
+        and not (hasattr(default, "__class__") and "Sentinel" in type(default).__name__)
+    ):
+        entry["default"] = default
+
+    help_text = getattr(param, "help", None)
+    if help_text:
+        entry["help"] = help_text
+
+    if getattr(param, "hidden", False):
+        entry["hidden"] = True
+
+    if getattr(param, "envvar", None):
+        envvar = param.envvar
+        if isinstance(envvar, str):
+            entry["envvar"] = [envvar]
+        elif envvar:
+            entry["envvar"] = list(envvar)
+
+    return entry
+
+
+def _registry_example(full_path: str) -> Any:
+    """The example for a command path, from the spec that owns it.
+
+    Not every command has one yet: an unmigrated v1 group has no spec, and
+    saying nothing is better than shipping the stale literal v1 kept here.
+    """
+    from tlgr.registry import ALIASES, REGISTRY
+
+    op_id = ALIASES.get(full_path.removeprefix("tlgr ").replace(" ", "."))
+    spec = REGISTRY.get(op_id) if op_id else None
+    if spec is None or spec.example is None:
+        return None
+    import msgspec
+
+    return msgspec.to_builtins(spec.example)
+
+
+def _build_node(cmd: click.BaseCommand, name: str = "", path: str = "") -> dict[str, Any]:
+    """Recursively build a schema node for a command."""
+    full_path = f"{path} {name}".strip() if path else name
+
+    node: dict[str, Any] = {
+        "name": name or cmd.name or "",
+        "path": full_path,
+    }
+
+    if isinstance(cmd, click.Group):
+        node["type"] = "group"
+    else:
+        node["type"] = "command"
+
+    if cmd.help:
+        node["help"] = cmd.help.split("\n")[0].strip()
+
+    if getattr(cmd, "hidden", False):
+        node["hidden"] = True
+
+    params = getattr(cmd, "params", [])
+    if params:
+        node["params"] = [_build_param(p) for p in params if p.name != "help"]
+
+    example = _registry_example(full_path)
+    if example is not None:
+        node["example_response"] = example
+
+    if isinstance(cmd, click.Group):
+        sub_names = cmd.list_commands(click.Context(cmd, info_name=name))
+        subcommands = []
+        for sub_name in sorted(sub_names):
+            sub_cmd = cmd.get_command(click.Context(cmd, info_name=name), sub_name)
+            if sub_cmd is not None:
+                subcommands.append(_build_node(sub_cmd, sub_name, full_path))
+        if subcommands:
+            node["subcommands"] = subcommands
+
+    return node
+
+
+def describe(path: tuple[str, ...] = (), *, include_hidden: bool = False) -> dict[str, Any] | None:
+    """The command tree under *path*, or None when the path does not exist."""
+    from tlgr.cli import cli as root_cli
+
+    node: Any = root_cli
+    walked = "tlgr"
+    for token in path:
+        if not isinstance(node, click.Group):
+            return None
+        sub = node.get_command(click.Context(node, info_name=walked.split()[-1]), token)
+        if sub is None:
+            return None
+        walked = f"{walked} {token}"
+        node = sub
+
+    tree = _build_node(node, name=walked.split()[-1], path="")
+    tree["path"] = walked
+    if not include_hidden:
+        _strip_hidden(tree)
+    return tree
+
+
+def _strip_hidden(node: dict[str, Any]) -> None:
+    """Recursively remove hidden commands and params."""
+    if "params" in node:
+        node["params"] = [p for p in node["params"] if not p.get("hidden")]
+    if "subcommands" in node:
+        node["subcommands"] = [s for s in node["subcommands"] if not s.get("hidden")]
+        for sub in node["subcommands"]:
+            _strip_hidden(sub)

tlgr/cli/params.py

@@ -0,0 +1,189 @@
+"""Custom Click parameter types.
+
+Each one converts to the *model* value the daemon expects and fails as a
+USAGE error naming the offending field, so a bad argument is reported the same
+way whether it was caught in the CLI or over the wire.
+
+Nothing here resolves anything. `@alice` becomes a `PeerRef`, not a user; the
+network is the daemon's business (§4.3, §6.6).
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+import click
+
+from tlgr.core.text import PARSE_MODES
+from tlgr.core.timefmt import TimeFormatError, fmt_dt, parse_dt, parse_duration
+from tlgr.models.peer import PeerRef, parse_message_link, parse_peer_ref, parse_user_ref
+
+__all__ = [
+    "DATETIME",
+    "DURATION",
+    "JSON",
+    "MSGREF",
+    "PARSE_MODE",
+    "PATH",
+    "PEER",
+    "USER",
+    "DateTimeParam",
+    "DurationParam",
+    "JsonParam",
+    "MsgRefParam",
+    "PathParam",
+    "PeerParam",
+    "UserParam",
+    "for_kind",
+]
+
+
+class PeerParam(click.ParamType):
+    """`@username`, an id, `+phone`, `me`/`saved`, or a t.me/tg:// link."""
+
+    name = "peer"
+
+    def convert(self, value: Any, param: Any, ctx: Any) -> Any:
+        if isinstance(value, PeerRef):
+            return value
+        try:
+            return parse_peer_ref(str(value))
+        except ValueError as exc:
+            self.fail(str(exc), param, ctx)
+
+
+class UserParam(PeerParam):
+    """`PEER` minus the forms that can only name a chat."""
+
+    name = "user"
+
+    def convert(self, value: Any, param: Any, ctx: Any) -> Any:
+        if isinstance(value, PeerRef):
+            return value
+        try:
+            return parse_user_ref(str(value))
+        except ValueError as exc:
+            self.fail(str(exc), param, ctx)
+
+
+class MsgRefParam(click.ParamType):
+    """A message id, or a link that carries one.
+
+    A link is accepted anywhere a `<chat> <msg-id>` pair is expected; the
+    generated command fills both and complains if they disagree (STYLE §2).
+    """
+
+    name = "msg_id"
+
+    def convert(self, value: Any, param: Any, ctx: Any) -> Any:
+        if isinstance(value, int):
+            return value
+        text = str(value).strip()
+        try:
+            return int(text)
+        except ValueError:
+            pass
+        link = parse_message_link(text)
+        if link is None:
+            self.fail(f"{text!r} is neither a message id nor a message link", param, ctx)
+        return link[1]
+
+
+class DurationParam(click.ParamType):
+    """`30s 5m 2h 7d 1w forever`. `0` is legal and means "immediately"."""
+
+    name = "duration"
+
+    def convert(self, value: Any, param: Any, ctx: Any) -> Any:
+        if value is None or isinstance(value, int):
+            return value
+        try:
+            return parse_duration(str(value))
+        except TimeFormatError as exc:
+            self.fail(str(exc), param, ctx)
+
+
+class DateTimeParam(click.ParamType):
+    """RFC-3339, `YYYY-MM-DD`, `YYYY-MM-DDTHH:MM`, or a relative `-90m`/`+3d`.
+
+    Converts to a UTC RFC-3339 string, because that is what crosses the wire;
+    a naive value is read in the local zone first (COR-23).
+    """
+
+    name = "datetime"
+
+    def convert(self, value: Any, param: Any, ctx: Any) -> Any:
+        if value is None:
+            return None
+        try:
+            parsed = parse_dt(str(value))
+        except TimeFormatError as exc:
+            self.fail(str(exc), param, ctx)
+        return fmt_dt(parsed)
+
+
+class JsonParam(click.ParamType):
+    """A JSON literal, or `@path` / `-` to read it from a file or stdin."""
+
+    name = "json"
+
+    def convert(self, value: Any, param: Any, ctx: Any) -> Any:
+        if not isinstance(value, str):
+            return value
+        text = value
+        if text == "-":
+            text = sys.stdin.read()
+        elif text.startswith("@"):
+            try:
+                with open(text[1:], encoding="utf-8") as handle:
+                    text = handle.read()
+            except OSError as exc:
+                self.fail(f"{text[1:]}: {exc.strerror or exc}", param, ctx)
+        try:
+            json.loads(text)
+        except ValueError as exc:
+            self.fail(f"not valid JSON: {exc}", param, ctx)
+        return text
+
+
+class PathParam(click.Path):
+    """A filesystem path where `-` keeps its stdin/stdout meaning."""
+
+    name = "path"
+
+    def convert(self, value: Any, param: Any, ctx: Any) -> Any:
+        if value == "-":
+            return "-"
+        return super().convert(value, param, ctx)
+
+
+class ParseModeParam(click.Choice):
+    def __init__(self) -> None:
+        super().__init__(list(PARSE_MODES))
+
+
+PEER = PeerParam()
+USER = UserParam()
+MSGREF = MsgRefParam()
+DURATION = DurationParam()
+DATETIME = DateTimeParam()
+JSON = JsonParam()
+PATH = PathParam()
+PARSE_MODE = ParseModeParam()
+
+#: `kind=` on a request field → the Click type that implements it.
+_BY_KIND: dict[str, click.ParamType] = {
+    "peer": PEER,
+    "user": USER,
+    "msg_id": MSGREF,
+    "duration": DURATION,
+    "datetime": DATETIME,
+    "json": JSON,
+    "path": PATH,
+}
+
+
+def for_kind(kind: str) -> click.ParamType | None:
+    return _BY_KIND.get(kind)