envsbot 2.2.0__tar.gz → 2.3.0__tar.gz

{envsbot-2.2.0 → envsbot-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: envsbot
-Version: 2.2.0
+Version: 2.3.0
 Summary: A modular plugin-driven XMPP bot framework
 Author-email: ~dan <fab@redterminal.org>, ~creme <creme@envs.net>
 License-Expression: GPL-3.0-only
@@ -22,7 +22,7 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: envs-xmpp<2.0,>=1.3.0
+Requires-Dist: envs-xmpp<2.0,>=1.5.0
 Requires-Dist: aiosqlite<1,>=0.20
 Requires-Dist: aiohttp<4,>=3.14.3
 Requires-Dist: beautifulsoup4<5,>=4.12.3
@@ -33,7 +33,7 @@ Requires-Dist: psutil<8,>=5.9
 Requires-Dist: slixmpp<2,>=1.8
 Provides-Extra: dev
 Requires-Dist: build<2,>=1.2; extra == "dev"
-Requires-Dist: mutmut>=3.0; extra == "dev"
+Requires-Dist: mutmut==3.6.0; extra == "dev"
 Requires-Dist: mypy>=1.8; extra == "dev"
 Requires-Dist: pytest<10,>=8.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=1.3.0; extra == "dev"
@@ -75,7 +75,7 @@ The bot was originally developed for the **envs pubnix/tilde** community and fol
 * vCard and avatar support via XEP-0054, XEP-0084 and XEP-0153
 * RSS/Atom feed watcher for room and direct subscriptions with stable feed numbers, scoped listing/search, pause/retry controls and per-destination templates
 * URL metadata checks for links, files and YouTube videos
-* Shared persistent recent-message cache for reply-aware plugins
+* Shared privacy-aware recent-message cache for reply-aware plugins
 * Weather, translation, vCard lookup, XMPP diagnostics, reminders, polls, pins, tell messages and utility commands
 * Community/fun plugins such as IdleRPG, ducks, dice, karma, sed corrections and XKCD
 * Pytest-based test suite with Drone CI and GitHub Actions support
@@ -150,7 +150,7 @@ Verify the installed application and shared core without starting XMPP:
 
 ```bash
 envsbot --version
-# envsbot 2.2.0 (envs-xmpp 1.3.0)
+# envsbot 2.3.0 (envs-xmpp 1.5.0)
 ```
 
 For a structured 72-hour post-release observation checklist, see
@@ -611,10 +611,11 @@ Run mutation tests with mutmut:
 ```bash
 ./scripts/mutmut.sh run
 ./scripts/mutmut.sh results
+./scripts/mutmut.sh check
 ./scripts/mutmut.sh browse
 ```
 
-The mutmut configuration in `pyproject.toml` explicitly lists the flat-layout source paths and disables coverage during mutant test runs. `scripts/mutmut.sh` deliberately unsets `PYTHONPATH` so the generated `./mutants` checkout cannot be shadowed by the original sources. Use `./scripts/mutmut.sh fresh` for a clean full run.
+The release mutation gate uses a curated deterministic scope in `pyproject.toml` rather than the entire bot. A full-repository audit currently creates more than 70,000 mutants and thousands of timeout-heavy async/background-task mutations, which is useful for occasional deep analysis but too noisy for a reproducible release gate. The curated scope covers routing, persistent message-cache storage, translate/weather behavior, help formatting, and plugin-manager internals and may be expanded only when added paths run without mutation timeouts. `scripts/mutmut.sh` deliberately unsets `PYTHONPATH` so the generated `./mutants` checkout cannot be shadowed by the original sources. Use `./scripts/mutmut.sh fresh` for a clean release-gate run, then `./scripts/mutmut.sh check` to compare it with the accepted survivor baseline. After reviewing an intentional survivor delta, `./scripts/mutmut.sh accept` updates that baseline. New `no tests`, timeout, suspicious, or unchecked results can never be accepted.
 
 Drone CI is configured in `.drone.yml`.
 

{envsbot-2.2.0 → envsbot-2.3.0}/README.md

@@ -31,7 +31,7 @@ The bot was originally developed for the **envs pubnix/tilde** community and fol
 * vCard and avatar support via XEP-0054, XEP-0084 and XEP-0153
 * RSS/Atom feed watcher for room and direct subscriptions with stable feed numbers, scoped listing/search, pause/retry controls and per-destination templates
 * URL metadata checks for links, files and YouTube videos
-* Shared persistent recent-message cache for reply-aware plugins
+* Shared privacy-aware recent-message cache for reply-aware plugins
 * Weather, translation, vCard lookup, XMPP diagnostics, reminders, polls, pins, tell messages and utility commands
 * Community/fun plugins such as IdleRPG, ducks, dice, karma, sed corrections and XKCD
 * Pytest-based test suite with Drone CI and GitHub Actions support
@@ -106,7 +106,7 @@ Verify the installed application and shared core without starting XMPP:
 
 ```bash
 envsbot --version
-# envsbot 2.2.0 (envs-xmpp 1.3.0)
+# envsbot 2.3.0 (envs-xmpp 1.5.0)
 ```
 
 For a structured 72-hour post-release observation checklist, see
@@ -567,10 +567,11 @@ Run mutation tests with mutmut:
 ```bash
 ./scripts/mutmut.sh run
 ./scripts/mutmut.sh results
+./scripts/mutmut.sh check
 ./scripts/mutmut.sh browse
 ```
 
-The mutmut configuration in `pyproject.toml` explicitly lists the flat-layout source paths and disables coverage during mutant test runs. `scripts/mutmut.sh` deliberately unsets `PYTHONPATH` so the generated `./mutants` checkout cannot be shadowed by the original sources. Use `./scripts/mutmut.sh fresh` for a clean full run.
+The release mutation gate uses a curated deterministic scope in `pyproject.toml` rather than the entire bot. A full-repository audit currently creates more than 70,000 mutants and thousands of timeout-heavy async/background-task mutations, which is useful for occasional deep analysis but too noisy for a reproducible release gate. The curated scope covers routing, persistent message-cache storage, translate/weather behavior, help formatting, and plugin-manager internals and may be expanded only when added paths run without mutation timeouts. `scripts/mutmut.sh` deliberately unsets `PYTHONPATH` so the generated `./mutants` checkout cannot be shadowed by the original sources. Use `./scripts/mutmut.sh fresh` for a clean release-gate run, then `./scripts/mutmut.sh check` to compare it with the accepted survivor baseline. After reviewing an intentional survivor delta, `./scripts/mutmut.sh accept` updates that baseline. New `no tests`, timeout, suspicious, or unchecked results can never be accepted.
 
 Drone CI is configured in `.drone.yml`.
 

{envsbot-2.2.0 → envsbot-2.3.0}/config_sample.py

@@ -314,17 +314,28 @@ ADMIN_REPORT_BACKUP_SMOKE_TEST = False
 
 # ================= MESSAGE CACHE =================
 
-# Number of recent messages retained per room or private conversation. The cache is
-# shared by all plugins, stored in SQLite and restored on restart. Message bodies are
-# therefore persisted in the bot database and included in normal database backups.
-# Lower this value if less retained history is wanted.
+# Number of recent messages retained in RAM per room or private conversation. The same
+# bound applies to SQLite when MESSAGE_CACHE_PERSIST is enabled.
 # Startup-only: restart envsbot after changing this value.
 MESSAGE_CACHE_SIZE = 100
 
-# Remove cached messages older than this many days. Set 0 to disable age pruning.
+# Remove cached messages older than this many days from RAM and SQLite. Set 0 to
+# disable age pruning.
 # Startup-only: restart envsbot after changing this value.
 MESSAGE_CACHE_MAX_AGE_DAYS = 30
 
+# Persist recent message bodies in SQLite so history survives restarts. When disabled,
+# existing message-cache rows are purged at startup and new history remains in RAM
+# only.
+# Startup-only: restart envsbot after changing this value.
+MESSAGE_CACHE_PERSIST = True
+
+# Respect XEP-0334 storage hints. no-store messages are excluded from history; no-
+# permanent-store messages remain available only in RAM and are never written to
+# SQLite.
+# Startup-only: restart envsbot after changing this value.
+MESSAGE_CACHE_RESPECT_NO_STORE = True
+
 
 # ================= USER TRACKING =================
 
@@ -668,6 +679,11 @@ TRANSLATE_TO = None
 # LibreTranslate fallback.
 TRANSLATE_LIBRETRANSLATE_URL = 'https://translate.envs.net/'
 
+# Optional explicit LibreTranslate /languages endpoint for capability discovery. Leave
+# None/empty to derive it from TRANSLATE_LIBRETRANSLATE_URL. Useful when translation
+# requests use a custom reverse-proxy path.
+TRANSLATE_LIBRETRANSLATE_LANGUAGES_URL = None
+
 # Optional LibreTranslate API key. Configured API-key providers are tried before the
 # unauthenticated LibreTranslate fallback.
 TRANSLATE_LIBRETRANSLATE_API_KEY = None

{envsbot-2.2.0 → envsbot-2.3.0}/core_plugins/_admin.py

@@ -463,12 +463,23 @@ def _cache_detail_lines(bot, health: HealthSnapshot | None = None) -> list[str]:
             if (cache_check.needs_attention if cache_check is not None else cache.get("degraded"))
             else "healthy"
         )
+        privacy = ""
+        if "respect_no_store" in cache:
+            if cache.get("respect_no_store"):
+                privacy = (
+                    " · hints=on "
+                    f"(skipped={int(cache.get('no_store_skips', 0) or 0)}, "
+                    "memory-only="
+                    f"{int(cache.get('no_permanent_store_messages', 0) or 0)})"
+                )
+            else:
+                privacy = " · hints=off"
         lines.append(
             f"Message cache: {int(cache.get('messages', 0) or 0)} messages · "
             f"pending={int(cache.get('pending_writes', 0) or 0)} · "
             f"retry={int(cache.get('retry_backlog', 0) or 0)} · "
             f"dropped={int(cache.get('dropped_persistence_entries', 0) or 0)} · "
-            f"{persistence} · {cache_health}"
+            f"{persistence}{privacy} · {cache_health}"
         )
     else:
         lines.append("Message cache: unavailable")

envsbot-2.2.0/core_plugins/help.py → envsbot-2.3.0/core_plugins/help/__init__.py

@@ -31,22 +31,50 @@ Examples
 
 from __future__ import annotations
 
-import inspect
 import logging
-import re
 
 import slixmpp
 
 from core_plugins._core import _get_enabled_rooms, handle_room_toggle_command
+from core_plugins.help.formatting import (
+    _access_label,
+    _access_summary,
+    _clean_doc,
+    _command_access_profiles,
+    _command_context_plugin,
+    _command_example_entries,
+    _command_examples,
+    _command_query_tokens,
+    _command_short,
+    _command_subcommand_entries,
+    _command_usage,
+    _common_plugin_access,
+    _context_label,
+    _effective_subcommand_context,
+    _effective_subcommand_role,
+    _example_description_for_command,
+    _examples_for_plugin_command,
+    _first_line,
+    _format_command_detail,
+    _format_command_line,
+    _format_example_lines,
+    _format_one_subcommand_lines,
+    _format_plugin_command_lines,
+    _plugin_description,
+    _plugin_meta,
+    _role_label,
+    _section_lines,
+    _sectioned_subcommands,
+    _subcommand_aliases,
+    _visible_subcommands,
+)
 from utils.command import (
     COMMANDS,
     Command,
-    CommandExample,
     CommandSubcommand,
     Role,
     check_permission,
     command,
-    command_examples,
     command_subcommands,
     resolve_command,
 )
@@ -133,146 +161,6 @@ async def get_help_store(bot):
 # DOCSTRING / METADATA HELPERS
 # --------------------------------------------------
 
-def _clean_doc(doc: str | None, prefix: str) -> str:
-    """Return a readable docstring with prefix placeholders resolved."""
-    if not doc:
-        return ""
-    return inspect.cleandoc(doc).replace("{prefix}", prefix).strip()
-
-
-def _first_line(doc: str | None) -> str:
-    """Return the first non-empty line from a docstring."""
-    doc = _clean_doc(doc, "")
-    if not doc:
-        return ""
-    for line in doc.splitlines():
-        line = line.strip()
-        if line:
-            return line
-    return ""
-
-
-def _section_lines(doc: str, title: str) -> list[str]:
-    """
-    Extract simple NumPy-style docstring sections such as Usage or Examples.
-    """
-    if not doc:
-        return []
-
-    lines = doc.splitlines()
-    start = None
-    for i, line in enumerate(lines):
-        if line.strip().lower() == title.lower():
-            start = i + 1
-            # Skip underline made of dashes if present.
-            if start < len(lines) and set(lines[start].strip()) <= {"-"}:
-                start += 1
-            break
-    if start is None:
-        return []
-
-    out = []
-    for line in lines[start:]:
-        stripped = line.strip()
-        if (
-            stripped
-            and re.fullmatch(r"[A-Za-z][A-Za-z /_-]+", stripped)
-            and len(stripped.split()) <= 4
-        ):
-            break
-        out.append(line.rstrip())
-
-    return [line for line in out if line.strip()]
-
-
-def _command_short(cmd_obj, prefix: str) -> str:
-    """Return the command summary from decorator metadata only."""
-    short = str(getattr(cmd_obj, "short", "") or "")
-    return short.format(prefix=prefix) if short else "No description available."
-
-
-def _command_usage(cmd_obj, prefix: str) -> list[str]:
-    """Return usage lines from decorator metadata only."""
-    usage = str(getattr(cmd_obj, "usage", "") or "")
-    return [usage.format(prefix=prefix)] if usage else []
-
-
-def _command_example_entries(cmd_obj, prefix: str) -> list[CommandExample]:
-    """Return normalized, prefix-resolved command examples."""
-    return [
-        CommandExample(
-            example.command.format(prefix=prefix),
-            example.description.format(prefix=prefix),
-        )
-        for example in command_examples(cmd_obj)
-    ]
-
-
-def _command_examples(cmd_obj, prefix: str) -> list[str]:
-    """Return example commands for compatibility with older callers."""
-    return [example.command for example in _command_example_entries(cmd_obj, prefix)]
-
-
-def _command_subcommand_entries(
-    cmd_obj,
-    prefix: str,
-) -> list[CommandSubcommand]:
-    """Return normalized, prefix-resolved structured subcommands."""
-    result = []
-    for subcommand in command_subcommands(cmd_obj):
-        result.append(
-            CommandSubcommand(
-                name=subcommand.name,
-                usage=subcommand.usage.format(prefix=prefix),
-                short=subcommand.short.format(prefix=prefix),
-                aliases=tuple(subcommand.aliases),
-                examples=tuple(
-                    CommandExample(
-                        example.command.format(prefix=prefix),
-                        example.description.format(prefix=prefix),
-                    )
-                    for example in subcommand.examples
-                ),
-                role=subcommand.role,
-                context=subcommand.context,
-                section=subcommand.section,
-            )
-        )
-    return result
-
-
-def _role_label(role: Role) -> str:
-    return str(role)
-
-
-def _context_label(cmd_obj) -> str:
-    context = getattr(cmd_obj, "context", "any") or "any"
-    if context != "any":
-        return context
-
-    # envsbot blocks privileged commands in normal room messages.
-    if getattr(cmd_obj, "role", Role.NONE) <= Role.MODERATOR:
-        return "private chat / MUC PM"
-    return "room, MUC PM or private chat"
-
-
-def _plugin_meta(bot, name: str) -> dict:
-    meta = getattr(bot.bot_plugins, "meta", {}).get(name, {}) or {}
-    if meta:
-        return meta
-
-    module = bot.bot_plugins.plugins.get(name)
-    if module is None:
-        return {}
-    return getattr(module, "PLUGIN_META", {}) or {}
-
-
-def _plugin_description(bot, name: str, module) -> str:
-    meta = _plugin_meta(bot, name)
-    desc = meta.get("description") or _first_line(module.__doc__)
-    return desc or "No description available."
-
-
 def _room_feature_entry(plugin: str) -> dict | None:
     """Return room-toggle metadata for a plugin, if it has room settings."""
     return ROOM_FEATURE_HELP.get(str(plugin).strip().lower())
@@ -358,252 +246,6 @@ def _all_visible_commands(bot, role: Role) -> list[tuple[str, Command]]:
     return commands
 
 
-def _format_command_line(cmd_obj, prefix: str) -> str:
-    aliases = sorted(set(a for a in (cmd_obj.aliases or []) if a != cmd_obj.name))
-    alias_text = ""
-    if aliases:
-        alias_text = f" / aliases: {', '.join(prefix + a for a in aliases)}"
-    return (
-        f"• {prefix}{cmd_obj.name} [{_role_label(cmd_obj.role)}] — "
-        f"{_command_short(cmd_obj, prefix)}{alias_text}"
-    )
-
-
-def _effective_subcommand_role(cmd_obj, subcommand: CommandSubcommand) -> Role:
-    return subcommand.role if subcommand.role is not None else cmd_obj.role
-
-
-def _effective_subcommand_context(cmd_obj, subcommand: CommandSubcommand) -> str:
-    return subcommand.context or _context_label(cmd_obj)
-
-
-def _visible_subcommands(cmd_obj, role: Role, prefix: str) -> list[CommandSubcommand]:
-    """Return structured subcommands visible to one user role."""
-    return [
-        subcommand
-        for subcommand in _command_subcommand_entries(cmd_obj, prefix)
-        if role <= _effective_subcommand_role(cmd_obj, subcommand)
-    ]
-
-
-def _subcommand_aliases(cmd_obj, subcommand: CommandSubcommand, prefix: str) -> list[str]:
-    """Return full command aliases for one structured subcommand."""
-    root = str(cmd_obj.name)
-    return [f"{prefix}{root} {alias}" for alias in subcommand.aliases]
-
-
-def _access_summary(role: Role, context: str) -> str:
-    """Return one compact role/context line for focused help output."""
-    return f"Role: {_role_label(role)} · Context: {context}"
-
-
-def _access_label(role: Role, context: str) -> str:
-    """Return a short access label suitable for one command line."""
-    return f"{_role_label(role)} · {context}"
-
-
-def _command_access_profiles(
-    cmd_obj,
-    prefix: str,
-    role: Role,
-) -> list[tuple[Role, str]]:
-    """Return visible role/context pairs represented by one command family."""
-    subcommands = _visible_subcommands(cmd_obj, role, prefix)
-    if subcommands:
-        return [
-            (
-                _effective_subcommand_role(cmd_obj, subcommand),
-                _effective_subcommand_context(cmd_obj, subcommand),
-            )
-            for subcommand in subcommands
-        ]
-    return [(cmd_obj.role, _context_label(cmd_obj))]
-
-
-def _common_plugin_access(
-    commands: list,
-    prefix: str,
-    role: Role,
-) -> tuple[Role, str] | None:
-    """Return a shared access profile when every visible command uses it."""
-    profiles = {
-        profile
-        for cmd_obj in commands
-        for profile in _command_access_profiles(cmd_obj, prefix, role)
-    }
-    return next(iter(profiles)) if len(profiles) == 1 else None
-
-
-def _format_one_subcommand_lines(
-    cmd_obj,
-    subcommand: CommandSubcommand,
-    prefix: str,
-    *,
-    common_access: tuple[Role, str] | None = None,
-) -> list[str]:
-    """Return compact lines for one structured subcommand."""
-    effective_role = _effective_subcommand_role(cmd_obj, subcommand)
-    context = _effective_subcommand_context(cmd_obj, subcommand)
-    access = (effective_role, context)
-    access_suffix = (
-        ""
-        if common_access == access
-        else f" [{_access_label(effective_role, context)}]"
-    )
-    lines = [f"• {subcommand.usage} — {subcommand.short}{access_suffix}"]
-    aliases = _subcommand_aliases(cmd_obj, subcommand, prefix)
-    if aliases:
-        lines.append("  Aliases: " + ", ".join(aliases))
-    return lines
-
-
-def _sectioned_subcommands(
-    subcommands: list[CommandSubcommand],
-) -> list[tuple[str, list[CommandSubcommand]]]:
-    """Group subcommands by their optional help section, preserving order."""
-    sections: list[tuple[str, list[CommandSubcommand]]] = []
-    indexes: dict[str, int] = {}
-    for subcommand in subcommands:
-        section = subcommand.section.strip()
-        if section not in indexes:
-            indexes[section] = len(sections)
-            sections.append((section, []))
-        sections[indexes[section]][1].append(subcommand)
-    return sections
-
-
-def _format_plugin_command_lines(
-    cmd_obj,
-    prefix: str,
-    role: Role,
-    *,
-    common_access: tuple[Role, str] | None = None,
-) -> list[str]:
-    """Return compact, consistently spaced plugin-help command lines."""
-    subcommands = _visible_subcommands(cmd_obj, role, prefix)
-    if subcommands:
-        sections = _sectioned_subcommands(subcommands)
-        has_named_sections = any(section for section, _entries in sections)
-        lines: list[str] = []
-        for section, entries in sections:
-            if has_named_sections:
-                if lines:
-                    lines.append("")
-                lines.append(f"{section or 'Other commands'}:")
-            for subcommand in entries:
-                lines.extend(
-                    _format_one_subcommand_lines(
-                        cmd_obj,
-                        subcommand,
-                        prefix,
-                        common_access=common_access,
-                    )
-                )
-        return lines
-
-    aliases = sorted(set(a for a in (cmd_obj.aliases or []) if a != cmd_obj.name))
-    access = (cmd_obj.role, _context_label(cmd_obj))
-    access_suffix = (
-        ""
-        if common_access == access
-        else f" [{_access_label(*access)}]"
-    )
-    lines = [
-        f"• {_command_usage(cmd_obj, prefix)[0]} — "
-        f"{_command_short(cmd_obj, prefix)}{access_suffix}",
-    ]
-    if aliases:
-        lines.append("  Aliases: " + ", ".join(prefix + alias for alias in aliases))
-    return lines
-
-
-def _example_description_for_command(
-    cmd_obj,
-    example: CommandExample,
-    prefix: str,
-) -> str:
-    """Return an explicit or subcommand-derived example description."""
-    if example.description:
-        return example.description
-
-    example_tokens = _command_query_tokens(example.command, prefix)
-    for subcommand in _command_subcommand_entries(cmd_obj, prefix):
-        names = [subcommand.name, *subcommand.aliases]
-        for name in names:
-            if not name or name.startswith("<"):
-                continue
-            name_tokens = tuple(name.lower().split())
-            primary_tokens = tuple(str(cmd_obj.name).lower().split())
-            if example_tokens[: len(primary_tokens)] != primary_tokens:
-                continue
-            remaining = example_tokens[len(primary_tokens):]
-            if remaining[: len(name_tokens)] == name_tokens:
-                return subcommand.short
-    return _command_short(cmd_obj, prefix)
-
-
-def _format_example_lines(
-    cmd_obj,
-    examples: list[CommandExample] | tuple[CommandExample, ...],
-    prefix: str,
-) -> list[str]:
-    """Render every example and its description on one compact line."""
-    lines = []
-    for example in examples:
-        description = _example_description_for_command(cmd_obj, example, prefix)
-        suffix = f" — {description}" if description else ""
-        lines.append(f"• {example.command}{suffix}")
-    return lines
-
-
-def _examples_for_plugin_command(
-    cmd_obj,
-    prefix: str,
-    role: Role,
-) -> list[CommandExample]:
-    """Prefer concise structured examples for aggregate commands."""
-    subcommands = _visible_subcommands(cmd_obj, role, prefix)
-    if subcommands:
-        return [example for subcommand in subcommands for example in subcommand.examples]
-    return _command_example_entries(cmd_obj, prefix)
-
-
-def _format_command_detail(cmd_obj, prefix: str, role: Role | None = None) -> list[str]:
-    lines = [
-        f"📖 Command: {prefix}{cmd_obj.name}",
-        _access_summary(cmd_obj.role, _context_label(cmd_obj)),
-    ]
-
-    aliases = sorted(set(a for a in (cmd_obj.aliases or []) if a != cmd_obj.name))
-    if aliases:
-        lines.append("Aliases: " + ", ".join(prefix + a for a in aliases))
-
-    lines += ["", _command_short(cmd_obj, prefix), "", "Usage:"]
-    for usage in _command_usage(cmd_obj, prefix):
-        lines.append(f"  {usage}")
-
-    visible_role = role if role is not None else Role.OWNER
-    subcommands = _visible_subcommands(cmd_obj, visible_role, prefix)
-    if subcommands:
-        lines += ["", "Subcommands:"]
-        lines.extend(_format_plugin_command_lines(cmd_obj, prefix, visible_role))
-
-    examples = _examples_for_plugin_command(cmd_obj, prefix, visible_role)
-    if examples:
-        lines += ["", "Examples:"]
-        lines.extend(_format_example_lines(cmd_obj, examples, prefix))
-
-    return lines
-
-
-def _command_context_plugin(bot, cmd_obj) -> str | None:
-    """Return the plugin name matching a focused command, if any."""
-    first_token = str(cmd_obj.name).split(maxsplit=1)[0].lower()
-    if first_token in getattr(bot.bot_plugins, "plugins", {}):
-        return first_token
-    return None
-
-
 def _format_plugin_context_lines(bot, plugin: str) -> list[str]:
     """Return compact plugin context for focused command help."""
     module = bot.bot_plugins.plugins[plugin]
@@ -624,14 +266,6 @@ def _format_plugin_context_lines(bot, plugin: str) -> list[str]:
     return lines
 
 
-def _command_query_tokens(query: str, prefix: str) -> tuple[str, ...]:
-    """Return normalized command tokens for a help query."""
-    query = query.strip().lower()
-    if prefix and query.startswith(prefix):
-        query = query[len(prefix):].strip()
-    return tuple(part for part in query.split() if part)
-
-
 def _commands_matching_prefix(
     tokens: tuple[str, ...],
     role: Role,