discord-tools-cli 0.1.0__py3-none-any.whl

discord_tools/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

discord_tools/bot.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+from discord_tools.models import BotIdentity
+from discord_tools.portal import invite_url
+
+RULE = "--------------------------------------------"
+
+INTENT_SHOWN = {
+    "enabled": "enabled",
+    "limited": "limited (may break at scale)",
+    "off": "OFF - search/export text will be empty",
+}
+
+
+@dataclass(frozen=True)
+class BotChange:
+    field: str
+    old: str
+    new: str
+
+
+def format_bot_profile(identity: BotIdentity, *, profile: str) -> str:
+    return "\n".join(
+        [
+            f"Bot profile {profile!r}",
+            RULE,
+            f"Username        {identity.username}",
+            f"Bot ID          {identity.id}",
+            f"Application     {identity.application_id}",
+            f"Description     {identity.description or '(not set)'}",
+            f"Avatar          {'set' if identity.has_avatar else 'not set'}",
+            f"Content intent  {INTENT_SHOWN[identity.message_content_intent]}",
+            RULE,
+            "Invite URL (adds it to a server you manage):",
+            f"  {invite_url(identity.application_id)}",
+        ]
+    )
+
+
+def build_edit_plan(
+    identity: BotIdentity,
+    *,
+    name: str | None = None,
+    description: str | None = None,
+    avatar: str | None = None,
+) -> list[BotChange]:
+    """What would actually change, current -> requested. No-ops drop out so
+    the confirm diff never claims an edit that is not one."""
+    plan: list[BotChange] = []
+    # identity.username is "name#0"-style; compare on the bare name.
+    current_name = identity.username.split("#")[0]
+    if name is not None and name != current_name:
+        plan.append(BotChange("username", current_name, name))
+    if description is not None and description != (identity.description or ""):
+        plan.append(BotChange("description", identity.description or "(not set)", description))
+    if avatar is not None:
+        if not Path(avatar).is_file():
+            # Checked here so a missing file fails before the confirm, not mid-apply.
+            raise FileNotFoundError(f"No avatar file at {avatar}.")
+        plan.append(BotChange("avatar", "set" if identity.has_avatar else "not set", avatar))
+    return plan
+
+
+def format_edit_diff(identity: BotIdentity, plan: list[BotChange]) -> str:
+    lines = [f"Editing {identity.username} (bot ID {identity.id})", RULE]
+    lines.extend(f"{change.field:<12} {change.old} -> {change.new}" for change in plan)
+    lines.append(RULE)
+    return "\n".join(lines)
+
+
+def confirm_bot_edits(diff: str, *, read: Callable[[str], str] = input, write: Callable[[str], None] = print) -> bool:
+    write(diff)
+    answer = read("Apply these changes? [y/N]: ").strip().lower()
+    if not answer:
+        write("No answer read - cancelled.")
+        return False
+    return answer == "y"
+
+
+async def apply_bot_edits(client, plan: list[BotChange]) -> list[str]:
+    applied: list[str] = []
+    username = next((change.new for change in plan if change.field == "username"), None)
+    avatar = next((change.new for change in plan if change.field == "avatar"), None)
+    description = next((change.new for change in plan if change.field == "description"), None)
+
+    if username is not None or avatar is not None:
+        await client.edit_bot_user(username=username, avatar_path=avatar)
+        applied.extend(change.field for change in plan if change.field in ("username", "avatar"))
+    if description is not None:
+        await client.edit_application(description=description)
+        applied.append("description")
+    return applied

discord_tools/cli.py

@@ -0,0 +1,362 @@
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import sys
+from functools import partial
+from pathlib import Path
+from typing import Sequence
+
+from discord_tools.portal import invite_url, run_auth
+from discord_tools.config import ConfigError, load_config
+from discord_tools.discovery import discover_servers, format_tree
+from discord_tools.delete import clear_messages, confirm_clear_messages
+from discord_tools.doctor import run_doctor
+from discord_tools.bot import (
+    apply_bot_edits,
+    build_edit_plan,
+    confirm_bot_edits,
+    format_bot_profile,
+    format_edit_diff,
+)
+from discord_tools.create import (
+    confirm_create,
+    create_category,
+    create_channel,
+    create_thread,
+    format_create_preview,
+)
+from discord_tools.exporters import write_records
+from discord_tools.search import all_content_empty, format_message_records, search_messages
+from discord_tools.send import confirm_send, format_send_preview, require_send_allowed, send_to_channel
+
+
+def positive_int(value: str) -> int:
+    parsed = int(value)
+    if parsed < 1:
+        raise argparse.ArgumentTypeError("must be at least 1")
+    return parsed
+
+
+def snowflake(value: str) -> int:
+    if not value.isdecimal():
+        raise argparse.ArgumentTypeError("must be a numeric Discord ID")
+    return int(value)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="discord-tools")
+    parser.add_argument("--profile", help="Named bot profile from ~/.discord-tools/ (default: default)")
+    subparsers = parser.add_subparsers(dest="command")
+
+    subparsers.add_parser("auth", help="Guided bot setup: Developer Portal walkthrough, token check, invite URL")
+
+    doctor = subparsers.add_parser("doctor", help="Check token, message-content intent, servers, and channel permissions")
+    doctor.add_argument("--channel", type=snowflake, help="Also check the bot's permissions and message visibility in this channel/thread ID")
+
+    discover = subparsers.add_parser("discover", help="List the server -> channel -> thread tree with IDs")
+    discover.add_argument("--server", type=snowflake, help="Limit to one server ID")
+    discover.add_argument("--json", dest="json_output", help="Write the tree to this JSON file instead of printing")
+
+    search = subparsers.add_parser("search", help="Search and export messages (history fetch + local filter)")
+    search.add_argument("--channel", required=True, type=snowflake, help="Channel or thread ID")
+    search.add_argument("--keyword", "--contains", dest="keyword", help="Case-insensitive text filter")
+    search.add_argument("--from-user", help="Author username or ID")
+    search.add_argument("--since", help="Inclusive ISO date or datetime lower bound")
+    search.add_argument("--until", help="Inclusive ISO date or datetime upper bound")
+    search.add_argument("--limit", type=positive_int, help="Maximum exported messages")
+    search.add_argument("--format", choices=("json", "csv"), default="json", help="Export format")
+    search.add_argument(
+        "--output",
+        help="Output file; relative names land in ~/.discord-tools/exports/. Prints a readable table when omitted",
+    )
+
+    send_parser = subparsers.add_parser("send", help="Send a message to a channel or thread as the bot")
+    send_parser.add_argument("--channel", required=True, type=snowflake, help="Channel or thread ID")
+    send_parser.add_argument("--text", help="Message text, or - to read it from stdin; optional when --file is given")
+    send_parser.add_argument("--file", dest="files", action="append", metavar="PATH", help="Attach a file; repeatable")
+    send_parser.add_argument(
+        "--yes",
+        action="store_true",
+        help="Skip the preview and send; the channel must be in DISCORD_SEND_ALLOWLIST",
+    )
+
+    create_parser = subparsers.add_parser("create", help="Create a channel, category, or thread")
+    create_kinds = create_parser.add_subparsers(dest="create_kind")
+
+    create_channel_parser = create_kinds.add_parser("channel", help="Create a text channel")
+    create_channel_parser.add_argument("--server", required=True, type=snowflake, help="Server ID")
+    create_channel_parser.add_argument("--name", required=True, help="Channel name")
+    create_channel_parser.add_argument("--category", type=snowflake, help="Category ID to file it under")
+
+    create_category_parser = create_kinds.add_parser("category", help="Create a category")
+    create_category_parser.add_argument("--server", required=True, type=snowflake, help="Server ID")
+    create_category_parser.add_argument("--name", required=True, help="Category name")
+
+    create_thread_parser = create_kinds.add_parser("thread", help="Create a thread in a text channel")
+    create_thread_parser.add_argument("--channel", required=True, type=snowflake, help="Parent channel ID")
+    create_thread_parser.add_argument("--name", required=True, help="Thread name")
+
+    for kind_parser in (create_channel_parser, create_category_parser, create_thread_parser):
+        kind_parser.add_argument("--yes", action="store_true", help="Skip the confirmation prompt")
+
+    clear = subparsers.add_parser("clear-messages", help="Clear a channel or thread's messages (dry-run by default)")
+    clear.add_argument("--channel", required=True, type=snowflake, help="Channel or thread ID")
+    clear.add_argument("--execute", action="store_true", help="Actually clear messages after typing DELETE")
+
+    bot_parser = subparsers.add_parser("bot", help="Show or edit the active profile's bot settings and invite URL")
+    bot_parser.add_argument("--invite", action="store_true", help="Print only the invite URL")
+    bot_parser.add_argument("--json", dest="json_output", help="Write the bot profile to this JSON file")
+    bot_parser.add_argument("--name", help="Set the bot's username")
+    bot_parser.add_argument("--description", help="Set the application description shown on the bot's profile")
+    bot_parser.add_argument("--avatar", help="Path to a new avatar image")
+    bot_parser.add_argument("--yes", action="store_true", help="Skip the confirmation prompt")
+
+    return parser
+
+
+def _write_json(payload, path: str) -> None:
+    output = Path(path)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(json.dumps(payload, indent=2, default=str) + "\n")
+
+
+async def _run_discover(client, args) -> int:
+    tree = await discover_servers(client, server_id=args.server)
+    if args.json_output:
+        _write_json(tree, args.json_output)
+    else:
+        print(format_tree(tree))
+    return 0
+
+
+async def run(args, *, client=None, config=None) -> int:
+    """Run one command.
+
+    The menu passes its own already-logged-in client so a whole menu session
+    is one login; a caller that passes a client owns it, so it is not closed
+    here.
+    """
+    if args.command == "auth":
+        return await run_auth(profile=args.profile)
+    if args.command == "doctor":
+        return await run_doctor(profile=args.profile, channel_id=args.channel)
+
+    if config is None:
+        config = load_config(profile=args.profile)
+
+    if client is not None:
+        return await _dispatch(client, args, config)
+    from discord_tools.client import open_client
+
+    async with open_client(config.token) as owned:
+        return await _dispatch(owned, args, config)
+
+
+async def _run_search(client, args) -> int:
+    if args.format == "csv" and not args.output:
+        # Checked before the fetch: on a big channel the history walk is the
+        # expensive part, and a usage mistake should fail before it, not after.
+        raise ValueError("--output is required for CSV export")
+
+    records = await search_messages(
+        client,
+        args.channel,
+        keyword=args.keyword,
+        from_user=args.from_user,
+        since=args.since,
+        until=args.until,
+        limit=args.limit,
+    )
+
+    if args.output:
+        path = write_records(records, args.output, args.format)
+        print(f"Exported {len(records)} message(s) to {path}")
+    else:
+        print(format_message_records(records))
+
+    if all_content_empty(records):
+        print(
+            "warning: every fetched message came back with empty text - the classic sign the "
+            "message-content intent is off in the Developer Portal. Run `discord-tools doctor`.",
+            file=sys.stderr,
+        )
+    return 0
+
+
+def _message_text(raw: str | None, *, has_files: bool) -> str | None:
+    # `-` is how a multi-line body gets in: quoting newlines through a shell
+    # flag is the kind of thing that silently sends half a message.
+    if raw is None:
+        if not has_files:
+            raise ValueError("Nothing to send: pass --text, or --file to send an attachment.")
+        return None
+    text = (sys.stdin.read() if raw == "-" else raw).strip()
+    if not text and not has_files:
+        raise ValueError("Nothing to send: the message text is empty.")
+    return text or None
+
+
+def _attachments(paths: list[str] | None) -> list[str]:
+    # Checked before the confirm, never mid-send: a typo in the fourth path
+    # should not surface after the first three have already reached Discord.
+    files = list(paths or [])
+    missing = [path for path in files if not Path(path).is_file()]
+    if missing:
+        raise FileNotFoundError("No file at " + ", ".join(missing) + ".")
+    return files
+
+
+async def _run_send(client, args, config) -> int:
+    files = _attachments(getattr(args, "files", None))
+    text = _message_text(args.text, has_files=bool(files))
+    channel = await client.get_channel(args.channel)
+
+    confirm = None
+    if args.yes:
+        require_send_allowed(config.send_allowlist, channel.id)
+    else:
+        identity = await client.get_identity()
+        preview = format_send_preview(channel, text, sender=identity.username, files=files)
+        confirm = partial(confirm_send, preview)
+
+    result = await send_to_channel(client, channel, text, files=files, confirm=confirm)
+    print(json.dumps(result.to_dict(), indent=2))
+    return 1 if result.cancelled else 0
+
+
+async def _run_create(client, args) -> int:
+    if args.create_kind is None:
+        raise ValueError("create needs one of: channel, category, thread.")
+
+    if args.create_kind == "thread":
+        parent = await client.get_channel(args.channel)
+        where = f"in #{parent.name} ({parent.id})"
+    else:
+        server = next((entry for entry in await client.list_servers() if entry.id == args.server), None)
+        if server is None:
+            raise ValueError(f"The bot is not in a server with ID {args.server}.")
+        where = f"in server {server.name} ({server.id})"
+        if args.create_kind == "channel" and args.category:
+            where += f", under category {args.category}"
+
+    confirm = None
+    if not args.yes:
+        preview = format_create_preview(args.create_kind, args.name, where=where)
+        confirm = partial(confirm_create, preview)
+
+    if args.create_kind == "channel":
+        created = await create_channel(client, args.server, args.name, category_id=args.category, confirm=confirm)
+    elif args.create_kind == "category":
+        created = await create_category(client, args.server, args.name, confirm=confirm)
+    else:
+        created = await create_thread(client, args.channel, args.name, confirm=confirm)
+
+    print(json.dumps(created.to_dict(), indent=2))
+    return 1 if created.cancelled else 0
+
+
+async def _run_clear_messages(client, args) -> int:
+    result = await clear_messages(
+        client,
+        args.channel,
+        execute=args.execute,
+        confirm=confirm_clear_messages,
+        progress=print,
+    )
+    print(json.dumps(result.to_dict(), indent=2))
+    return 1 if result.cancelled else 0
+
+
+async def _run_bot(client, args, config) -> int:
+    identity = await client.get_identity()
+
+    if args.invite:
+        print(invite_url(identity.application_id))
+        return 0
+
+    requested = {key: getattr(args, key) for key in ("name", "description", "avatar") if getattr(args, key) is not None}
+    if not requested:
+        if args.json_output:
+            _write_json(identity.to_dict(), args.json_output)
+        else:
+            print(format_bot_profile(identity, profile=config.profile))
+        return 0
+
+    plan = build_edit_plan(identity, **requested)
+    if not plan:
+        print("Nothing to change - every requested value is already set.")
+        return 0
+
+    if not args.yes:
+        if not confirm_bot_edits(format_edit_diff(identity, plan)):
+            print(json.dumps({"applied": [], "cancelled": True}, indent=2))
+            return 1
+
+    applied = await apply_bot_edits(client, plan)
+    print(json.dumps({"applied": applied, "cancelled": False}, indent=2))
+    return 0
+
+
+async def _dispatch(client, args, config) -> int:
+    if args.command == "discover":
+        return await _run_discover(client, args)
+    if args.command == "search":
+        return await _run_search(client, args)
+    if args.command == "send":
+        return await _run_send(client, args, config)
+    if args.command == "create":
+        return await _run_create(client, args)
+    if args.command == "clear-messages":
+        return await _run_clear_messages(client, args)
+    if args.command == "bot":
+        return await _run_bot(client, args, config)
+    raise ValueError(f"Unknown command: {args.command}")
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        if args.command is None:
+            if not sys.stdin.isatty():
+                # A menu needs a human. Scripts and agents get the help they
+                # actually wanted instead of a blocked input() prompt.
+                parser.print_help()
+                return 0
+            try:
+                # `input()` only gets line editing when readline is imported.
+                # Without it every arrow key echoes its raw escape sequence
+                # (^[[A) into the answer. Menu-only, and optional: readline is
+                # absent on some platforms and the menu works fine without it.
+                import readline  # noqa: F401
+            except ImportError:
+                pass
+
+            # Imported here, not at module scope: menu.py imports cli, and a
+            # top-level import either way closes the cycle.
+            from discord_tools.menu import run_menu
+
+            return asyncio.run(run_menu(profile=args.profile))
+        return asyncio.run(run(args))
+    except (KeyboardInterrupt, EOFError):
+        print()
+        return 130
+    except ConfigError as exc:
+        parser.error(str(exc))
+    except ValueError as exc:
+        parser.error(str(exc))
+    except PermissionError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    except RuntimeError as exc:
+        # ClientError and friends: a Discord-side refusal, not a usage mistake.
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    except OSError as exc:
+        parser.error(str(exc))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())