fix: voice_recognition uses constants for credentials and paths

The cog did its own netrc read from a hardcoded /home/pi/.netrc at import
time, crashing on any other host. Now:

- constants.py: ASSEMBLYAI_API_KEY resolved like every other token
  (env ASSEMBLYAI_API_KEY -> netrc machine 'assemblyai' at
  CONJURER_NETRC_FILE); new TRANSCRIPTS_PATH (env
  CONJURER_TRANSCRIPTS_PATH, defaults next to the log file, created by the
  runtime layout)
- voice_recognition_commands.py: drop the hardcoded netrc read and
  transcript dir; when the key is missing raise a clear RuntimeError so
  the guarded loader disables ONLY this cog with a readable reason
- bot.env.example: document ASSEMBLYAI_API_KEY

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.dockerignore

@@ -0,0 +1,17 @@
+# Keep build contexts lean. Component dirs (conjurer_librarian, conjurer_musician)
+# are intentionally NOT ignored — their images copy them from this same context.
+.git
+.github
+.trunk
+.vscode
+**/__pycache__/
+*.pyc
+*.pyo
+*.log
+*.mp3
+docs/
+tests/
+conftest.py
+pytest.ini
+docker/env/*.env
+secrets/

.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+permissions:
+  contents: read
+
+jobs:
+  compile:
+    # Byte-compile every first-party .py to catch syntax errors. No deps.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: py_compile first-party sources
+        run: |
+          git ls-files '*.py' | grep -vE '^(yt_dlp|spotify_dl)/' | xargs python -m py_compile
+          echo "All first-party sources compile."
+
+  unit:
+    # Pure-logic tests; tested modules guard heavy deps, so only pytest needed.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install test deps
+        run: |
+          python -m pip install --upgrade pip
+          pip install pytest
+      - name: Run unit tests
+        run: pytest tests/unit -v
+
+  integration:
+    # Boot the Flask services and assert the X-Conjurer-Api-Key auth contract.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install service deps
+        run: |
+          python -m pip install --upgrade pip
+          pip install pytest flask waitress requests
+      - name: Run integration tests
+        run: pytest tests/integration -v

.github/workflows/python-app.yml

@@ -1,39 +0,0 @@
-# This workflow will install Python dependencies, run tests and lint with a single version of Python
-# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
-
-name: Python application
-
-on:
-  push:
-    branches: [ "main" ]
-  pull_request:
-    branches: [ "main" ]
-
-permissions:
-  contents: read
-
-jobs:
-  build:
-
-    runs-on: ubuntu-latest
-
-    steps:
-    - uses: actions/checkout@v3
-    - name: Set up Python 3.10
-      uses: actions/setup-python@v3
-      with:
-        python-version: "3.10"
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install flake8 pytest
-        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
-    - name: Lint with flake8
-      run: |
-        # stop the build if there are Python syntax errors or undefined names
-        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
-        # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
-        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
-    - name: Test with pytest
-      run: |
-        pytest

.github/workflows/python-package.yml

@@ -1,40 +0,0 @@
-# This workflow will install Python dependencies, run tests and lint with a variety of Python versions
-# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
-
-name: Python package
-
-on:
-  push:
-    branches: [ "main" ]
-  pull_request:
-    branches: [ "main" ]
-
-jobs:
-  build:
-
-    runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        python-version: ["3.8", "3.9", "3.10"]
-
-    steps:
-    - uses: actions/checkout@v3
-    - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v3
-      with:
-        python-version: ${{ matrix.python-version }}
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        python -m pip install flake8 pytest
-        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
-    - name: Lint with flake8
-      run: |
-        # stop the build if there are Python syntax errors or undefined names
-        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
-        # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
-        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
-    - name: Test with pytest
-      run: |
-        pytest

bot.py

@@ -4,8 +4,21 @@
 # pylint: disable=too-many-lines
 """
 Module of a python bot named Conjurer - used to work on BDSM discord servers.
+
+Startup is defensive by design:
+
+* every cog is loaded independently - one broken/missing dependency disables
+  that cog only, never the whole bot,
+* cogs that need a sibling service (musician / librarian) are only enabled
+  after a positive health check; a watchdog keeps re-checking and enables them
+  the moment the service comes alive,
+* fatal misconfiguration (missing Discord token) exits loudly on stderr with a
+  clear message instead of dying silently into a log file.
 """
+import asyncio
 import logging
+import os
+import sys
 
 # *=========================================== Standard Library Imports
 import random
@@ -14,12 +27,26 @@ from logging import handlers
 
 # *==============Imported libraries
 import discord
+import requests
 from discord.ext import commands
 
 from communication_subroutine import comm_subroutine
-from constants import ENCODING, LOGFILE, TOKEN
+from constants import (
+    ENCODING,
+    FILE_SERVICE_ADDRESS,
+    GET_MP3,
+    LIBRARIAN_SERVICE_ADDRESS,
+    LOGFILE,
+    TOKEN,
+)
+
 logger = logging.getLogger("discord")
-logger.setLevel(logging.INFO)
+logger.setLevel(logging.DEBUG)
+formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
+
+# File log (rotated). constants ensures the directory exists; this is belt and
+# braces for exotic overrides.
+os.makedirs(os.path.dirname(LOGFILE) or ".", exist_ok=True)
 handler = handlers.RotatingFileHandler(
     filename=LOGFILE,
     encoding=ENCODING,
@@ -27,10 +54,18 @@ handler = handlers.RotatingFileHandler(
     maxBytes=6 * 1024 * 1024,
     backupCount=6,
     )
-formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
 handler.setFormatter(formatter)
 logger.addHandler(handler)
 
+# Console log so `docker logs` / journalctl actually show what happened.
+console_handler = logging.StreamHandler()
+console_handler.setLevel(logging.INFO)
+console_handler.setFormatter(formatter)
+logger.addHandler(console_handler)
+# Some dependency calls logging.basicConfig(), adding a root handler; without
+# this the 'discord' logger's records get printed twice (our format + root's).
+logger.propagate = False
+
 # *=========================================== Initializations
 intents = discord.Intents.default()
 intents.message_content = True
@@ -47,57 +82,245 @@ intents.moderation = True
 random.seed()
 client = commands.Bot(intents=intents, command_prefix="$")
 
+# *=========================================== Extension groups
+# Core cogs depend on nothing but the bot itself (broken ones are skipped
+# individually). Service groups are gated on a health check of the service
+# they talk to and enabled later by the watchdog when the service appears.
+CORE_EXTENSIONS = [
+    "administration_commands",
+    "ai_commands",
+    "other_commands",
+    "latex_commands",
+    "voice_recognition_commands",
+    "conanjurer_commands",
+]
+
+SERVICE_EXTENSION_GROUPS = {
+    # musician (file service): music download/search, radio control, file shares
+    "musician": {
+        "health_url": f"{FILE_SERVICE_ADDRESS}{GET_MP3}",
+        "extensions": ["music_commands", "radio_commands", "file_search_commands"],
+    },
+    # librarian: DOI / Crossref search
+    "librarian": {
+        "health_url": f"{LIBRARIAN_SERVICE_ADDRESS}/",
+        "extensions": ["librarian_commands"],
+    },
+}
+
+SERVICE_RECHECK_SECONDS = 300
+
+
+def _service_alive(url: str) -> bool:
+    """True when the service answers HTTP at all (any status code counts)."""
+    try:
+        requests.get(url, timeout=3)
+        return True
+    except requests.exceptions.RequestException:
+        return False
+
+
+async def _load_extension_safe(name: str) -> bool:
+    """Load one extension; log and continue instead of killing startup."""
+    if name in client.extensions:
+        return True
+    try:
+        await client.load_extension(name)
+        logger.info("Extension loaded: %s", name)
+        return True
+    except Exception:  # pylint: disable=broad-exception-caught
+        logger.exception("Extension FAILED (disabled, bot continues): %s", name)
+        return False
+
+
+async def _load_service_groups() -> bool:
+    """Health-check each service group and load its cogs when alive.
+
+    Returns True when anything new was loaded (caller may want to re-sync).
+    """
+    loaded_any = False
+    for service, group in SERVICE_EXTENSION_GROUPS.items():
+        missing = [e for e in group["extensions"] if e not in client.extensions]
+        if not missing:
+            continue
+        alive = await asyncio.to_thread(_service_alive, group["health_url"])
+        if not alive:
+            logger.warning(
+                "Service '%s' unreachable (%s) - cogs stay disabled: %s",
+                service,
+                group["health_url"],
+                ", ".join(missing),
+            )
+            continue
+        logger.info("Service '%s' is alive - enabling: %s", service, ", ".join(missing))
+        for extension in missing:
+            if await _load_extension_safe(extension):
+                loaded_any = True
+    return loaded_any
+
+
+async def _sync_tree() -> None:
+    try:
+        await client.tree.sync()
+    except Exception:  # pylint: disable=broad-exception-caught
+        logger.exception("Slash-command tree sync failed (commands may lag)")
+
+
+async def _service_watchdog() -> None:
+    """Periodically retry offline services and enable their cogs when up."""
+    while not client.is_closed():
+        await asyncio.sleep(SERVICE_RECHECK_SECONDS)
+        try:
+            if await _load_service_groups():
+                await _sync_tree()
+        except Exception:  # pylint: disable=broad-exception-caught
+            logger.exception("Service watchdog tick failed")
+
+
+_STARTUP_DONE = False
+
 
 # *=========================================== Define Events
 @client.event
 async def on_ready():
     """Metoda wywoływana przy połączeniu do serwera."""
-    logger = logging.getLogger("discord")
-    logger.debug("SAMPLE DEBUG LOG")
+    global _STARTUP_DONE  # pylint: disable=global-statement
     logger.info("%s has connected to Discord!", client.user)
-    # TODO: load vs reload
+    if _STARTUP_DONE:
+        logger.info("Reconnected - extensions already loaded")
+        return
+    _STARTUP_DONE = True
     logger.info("Reactor: online")
 
-    await client.load_extension("administration_commands")
+    for extension in CORE_EXTENSIONS:
+        await _load_extension_safe(extension)
 
-    await client.load_extension("librarian_commands")
-    await client.load_extension("music_commands")
-    await client.load_extension("radio_commands")
-
-    await client.load_extension("ai_commands")
-
-    await client.load_extension("other_commands")
-    await client.load_extension("voice_recognition_commands")
-    await client.load_extension("file_search_commands")
-    await client.load_extension("latex_commands")
+    await _load_service_groups()
     logger.info("Sensors: online")
 
     logger.info(client.cogs)
-    await client.tree.sync()
+    await _sync_tree()
     for com in client.commands:
         logger.info("Command %s is awejleble", com.qualified_name)
 
+    asyncio.create_task(_service_watchdog())
+
     logger.info("Logged in as ----> %s", client.user)
     logger.info("ID:%s ", client.user.id)
     logger.info("All systems: operational")
 
 
+# *=========================================== Runtime orchestration
+# The legacy bootstrap used two bare threads (client.run + comm_subroutine) and
+# joined them, which made a clean shutdown impossible.  We now drive everything
+# from a single asyncio loop: the Flask comm layer still runs in its own
+# threads (via asyncio.to_thread) but is steered through a shared stop_event so
+# the bot can stop both halves cooperatively.
+
+
+async def _run_comm_subroutine(stop_event: threading.Event) -> None:
+    """Run the blocking comm subroutine in a worker thread.
+
+    A crash here takes down the internal HTTP endpoints only - the Discord
+    side keeps running, so log loudly and swallow.
+    """
+    try:
+        await asyncio.to_thread(comm_subroutine, stop_event)
+    except Exception:  # pylint: disable=broad-exception-caught
+        logger.exception(
+            "Comm layer crashed - internal HTTP endpoints are down "
+            "(musician/librarian callbacks will not arrive); bot continues"
+        )
+
+
+async def _run_bot(token: str, shutdown_event: asyncio.Event) -> None:
+    """Start the Discord client; log WHY it died before flagging shutdown.
+
+    Exceptions were previously swallowed by ``gather(return_exceptions=True)``
+    which made a failed login look like a clean exit (silent crash-loop in
+    docker). Now every death is diagnosed on the console first.
+    """
+    try:
+        # NOTE: log_handler is a Client.run()-only kwarg (run() configures
+        # logging, then calls start()); start() takes just the token. We set
+        # up our own handlers above, so nothing is lost.
+        await client.start(token)
+    except discord.LoginFailure:
+        logger.critical(
+            "FATAL: Discord REJECTED the token (Improper token). Fix the "
+            "'discord' entry in the netrc mounted at CONJURER_NETRC_FILE or "
+            "the DISCORD_TOKEN env var. If the token leaked/reset, generate a "
+            "new one in the Discord Developer Portal -> Bot -> Reset Token."
+        )
+        raise
+    except discord.PrivilegedIntentsRequired:
+        logger.critical(
+            "FATAL: this bot application does not have the Privileged Gateway "
+            "Intents enabled. Open Discord Developer Portal -> your app -> "
+            "Bot -> enable 'Presence', 'Server Members' and 'Message Content' "
+            "Intents, then restart."
+        )
+        raise
+    except Exception:  # pylint: disable=broad-exception-caught
+        logger.exception("FATAL: Discord client crashed at startup/runtime")
+        raise
+    finally:
+        shutdown_event.set()
+
+
+async def main() -> int:
+    """Run both halves; return a process exit code (0 = clean shutdown)."""
+    if TOKEN:
+        token_source = (
+            "env DISCORD_TOKEN" if os.getenv("DISCORD_TOKEN") else "netrc file"
+        )
+        logger.info(
+            "Discord token: loaded from %s (length %d)", token_source, len(TOKEN)
+        )
+
+    logger.info("Starting discord bot")
+    shutdown_event = asyncio.Event()
+    comm_stop_event = threading.Event()
+
+    comm_task = asyncio.create_task(_run_comm_subroutine(comm_stop_event))
+    bot_task = asyncio.create_task(_run_bot(TOKEN, shutdown_event))
+
+    exit_code = 0
+    try:
+        await shutdown_event.wait()
+    except (KeyboardInterrupt, asyncio.CancelledError):
+        logger.info("Shutdown signal received")
+        comm_stop_event.set()
+        await client.close()
+    finally:
+        comm_stop_event.set()
+        if not client.is_closed():
+            await client.close()
+        results = await asyncio.gather(bot_task, comm_task, return_exceptions=True)
+        for result in results:
+            if isinstance(result, BaseException) and not isinstance(
+                result, asyncio.CancelledError
+            ):
+                # Already logged with full traceback inside the task; repeat
+                # the one-liner so it is the LAST thing in `docker logs`.
+                logger.critical("Task died: %r", result)
+                exit_code = 1
+    return exit_code
+
+
 # *================================== Run
 if __name__ == "__main__":
-    logger.info("Starting discord bot")
-    threads = []
-    logger.info("Starting discord bot: Creating threads")
-    threads.append(threading.Thread(target=client.run, args=(TOKEN,),kwargs={"log_handler":None}))
-    threads.append(threading.Thread(target=comm_subroutine))
-    logger.info("Starting discord bot: Starting threads")
-    WRK_CNT = 0
-    for worker in threads:
-        WRK_CNT += 1
-        logger.info("Starting discord bot: Starting thread %s", WRK_CNT)
-        worker.start()
-    logger.info("Starting discord bot: Joining threads")
-    WRK_CNT = 0
-    for worker in threads:
-        WRK_CNT += 1
-        logger.info("Starting discord bot: Joining thread %s", WRK_CNT)
-        worker.join()
+    if not TOKEN:
+        # Loud, unmissable and in `docker logs`: this is THE most common cause
+        # of a silent container crash-loop.
+        MSG = (
+            "FATAL: Discord token missing.\n"
+            "Provide it via the DISCORD_TOKEN environment variable or a netrc "
+            "file (machine 'discord') at the path in CONJURER_NETRC_FILE.\n"
+            "Docker: check that your secrets mount exists, e.g.\n"
+            "  -v /srv/conjurer/secrets/.netrc:/secrets/.netrc:ro\n"
+            "  CONJURER_NETRC_FILE=/secrets/.netrc"
+        )
+        logger.critical(MSG)
+        sys.exit(MSG)
+    sys.exit(asyncio.run(main()))

communication_subroutine.py

@@ -1,17 +1,20 @@
 import json
 import logging
+import os
 import re
 import threading
 import time
 from queue import Empty, Queue
+from typing import Optional
 from urllib import request as urequest
 
-from flask import Flask, jsonify, request
+from flask import Flask, abort, jsonify, request
 from waitress import serve
 
-HOST_ADDRESS = "192.168.1.31"
-PORT_ADDRESS = 5000
-ICECAST_ADDRESS = "http://192.168.1.15:8000"
+HOST_ADDRESS = os.getenv("CONJURER_DISCORD_HOST", "192.168.1.92")
+PORT_ADDRESS = int(os.getenv("CONJURER_DISCORD_PORT", "5000"))
+ICECAST_ADDRESS = os.getenv("CONJURER_ICECAST", "http://192.168.1.12:8000")
+API_KEY = os.getenv("CONJURER_API_KEY")
 OUT_COMM_Q = Queue()
 IN_COMM_Q = Queue()
 SRCHTITLE = re.compile(rb"StreamTitle=\\*(?P<title>[^;]*);").search
@@ -19,6 +22,12 @@ SRCHTITLE = re.compile(rb"StreamTitle=\\*(?P<title>[^;]*);").search
 awaiting_q = []
 incoming_q = Queue()
 app = Flask(__name__)
+
+
+def _authorize_request() -> None:
+    """Reject inbound calls lacking the shared key (no-op if key is unset)."""
+    if API_KEY and request.headers.get("X-Conjurer-Api-Key") != API_KEY:
+        abort(401)
 PREPPED_TRACKS = {
     "requests": "",
     "hit": "",
@@ -53,6 +62,7 @@ class QueryControl:
 
 @app.route("/prepped_tracks", methods=["POST"])
 def log_radio_tracks():
+    _authorize_request()
     app.logger = logging.getLogger("discord")
 
     app.logger.info(request)
@@ -85,6 +95,7 @@ def answer_external_command():
     :return: The function `answer_external_command()` is returning a JSON response with the message
     "SUCCESS".
     """
+    _authorize_request()
     logger = logging.getLogger("discord")
     logger.info(request)
     record = json.loads(request.data)
@@ -129,34 +140,42 @@ def waitress_run():
     serve(app, host=HOST_ADDRESS, port=PORT_ADDRESS)
 
 
-def scan_queue():
+def scan_queue(stop_event: Optional[threading.Event] = None):
     """
     The function `scan_queue` reads data from a queue, logs it, and appends it to another queue.
 
-    :param _logger: The `_logger` parameter is typically an instance of a logging object that is used to
-    record and store log messages. It is commonly used to track the flow of the program, record errors,
-    and provide information for debugging purposes. In this code snippet, the `_logger` object is used
-    to log the
+    A bounded ``get(timeout=1)`` is used instead of a blocking ``get()`` so the
+    worker can observe ``stop_event`` and exit cleanly during shutdown.
+
+    :param stop_event: optional :class:`threading.Event`; when set the loop
+    stops at the next iteration.
     """
     logger = logging.getLogger("discord")
     while True:
-        data = OUT_COMM_Q.get()
+        if stop_event and stop_event.is_set():
+            logger.info("scan_queue: stop requested")
+            break
+        try:
+            data = OUT_COMM_Q.get(timeout=1)
+        except Empty:
+            continue
         logger.info(data)
         awaiting_q.append(data)
 
 
-def scan_incoming():
+def scan_incoming(stop_event: Optional[threading.Event] = None):
     """
     The `scan_incoming` function continuously checks for incoming data, processes it, and logs when data
     is found.
 
-    :param _logger: The `_logger` parameter in the `scan_incoming` function is a logger object that is
-    used to log messages or information during the execution of the function. It is typically used for
-    debugging, monitoring, or tracking the flow of the program. In this case, the `_logger` is being
-    used
+    :param stop_event: optional :class:`threading.Event`; when set the loop
+    stops at the next iteration.
     """
     logger = logging.getLogger("discord")
     while True:
+        if stop_event and stop_event.is_set():
+            logger.info("scan_incoming: stop requested")
+            break
         try:
             answer = incoming_q.get(block=False)
             logger.info("DATA FOUND")
@@ -204,27 +223,48 @@ def id3(url: str) -> dict:
         return tagdata
 
 
-def comm_subroutine():
+def comm_subroutine(stop_event: Optional[threading.Event] = None):
     """
     The `comm_subroutine` function starts multiple threads to run different tasks concurrently.
 
-    :param logger: The `logger` parameter in the `comm_subroutine` function is an instance of a logger
-    object that is used for logging messages at various levels (e.g., debug, info, warning, error). In
-    the provided code snippet, the logger is used to log messages at the "info" level
+    Workers run as daemon threads and honour an optional ``stop_event`` so the
+    bot can shut the communication layer down cleanly instead of blocking
+    forever on ``join()``.
+
+    :param stop_event: optional :class:`threading.Event` shared with the caller
+    to coordinate a cooperative shutdown.
     """
-    # logger.setLevel(logging.DEBUG)
     logger = logging.getLogger("discord")
+    logger.setLevel(logging.DEBUG)
     logger.info("Started comms")
     threads = []
+    # NOTE: flask_debug is the dev server bound to the SAME host:port as
+    # waitress - running both kills the comm layer with 'address in use'.
+    # Enable it only INSTEAD of waitress_run, never alongside.
     # threads.append(threading.Thread(target=flask_debug))
-    threads.append(threading.Thread(target=waitress_run))
-    threads.append(threading.Thread(target=scan_queue))
-    threads.append(threading.Thread(target=scan_incoming))
+    threads.append(threading.Thread(target=waitress_run, daemon=True))
+    threads.append(
+        threading.Thread(
+            target=scan_queue, kwargs={"stop_event": stop_event}, daemon=True
+        )
+    )
+    threads.append(
+        threading.Thread(
+            target=scan_incoming, kwargs={"stop_event": stop_event}, daemon=True
+        )
+    )
 
     for worker in threads:
         worker.start()
-    for worker in threads:
-        worker.join()
+
+    try:
+        while any(thread.is_alive() for thread in threads):
+            if stop_event and stop_event.is_set():
+                break
+            time.sleep(0.5)
+    finally:
+        if stop_event:
+            stop_event.set()
 
 
 if __name__ == "__main__":

conanjurer_commands.py

@@ -1,102 +1,217 @@
-# ai command cogs
-import logging
-import discord
-from discord.ext import commands
-from other_functions import discord_friendly_send, discord_friendly_reply
-from __future__ import annotations
+# This Python file uses the following encoding: utf-8
+"""Conan Exiles <-> Discord bridge (cog).
+
+Follows the project convention (cog here, helpers in
+``conanjurer_functions.py``).  The integration is dormant unless configured in
+:mod:`constants`: with no RCON host / channels the background watchers simply
+do not start and the GM commands report that RCON is unavailable, so loading
+this extension is always safe even on hosts without a Conan server.
+"""
 import asyncio
 import logging
 
-from conanjurer_functions import watch, Event
-log = logging.getLogger("discord")
+import discord
+from discord.ext import commands
+
+from conanjurer_functions import ConanConfig, Event, RconClient, watch, watch_players
+from constants import (
+    CONAN_CHAT_CHANNEL_ID,
+    CONAN_EVENTS_CHANNEL_ID,
+    CONAN_GM_ROLE_ID,
+    CONAN_JOIN_CHANNEL_ID,
+    CONAN_LOG_MODE,
+    CONAN_LOG_PATH,
+    CONAN_PLAYER_POLL_SECONDS,
+    CONAN_RCON_HOST,
+    CONAN_RCON_PASSWORD,
+    CONAN_RCON_PORT,
+    CONAN_SFTP_HOST,
+    CONAN_SFTP_PASSWORD,
+    CONAN_SFTP_PORT,
+    CONAN_SFTP_USER,
+)
+
 
 def is_gm():
+    """Allow only members holding the configured Conan GM role."""
+
     async def predicate(ctx: commands.Context) -> bool:
-        role_id = ctx.bot.cfg.gm_role_id
-        ok = any(r.id == role_id for r in getattr(ctx.author, "roles", []))
+        if not CONAN_GM_ROLE_ID:
+            await ctx.reply(
+                "⛔ Rola GM Conana nie jest skonfigurowana.", mention_author=False
+            )
+            return False
+        ok = any(r.id == CONAN_GM_ROLE_ID for r in getattr(ctx.author, "roles", []))
         if not ok:
             await ctx.reply("⛔ Tylko GM.", mention_author=False)
         return ok
+
     return commands.check(predicate)
 
 
-class FromConan(commands.Cog):
-    def __init__(self, bot: commands.Bot):
+class ConanModule(commands.Cog):
+    """Bridges a Conan Exiles server with Discord over RCON + log following."""
+
+    def __init__(self, bot, logger_name):
         self.bot = bot
-        self._task: asyncio.Task | None = None
+        self.logger = logging.getLogger(logger_name)
+        self.cfg = ConanConfig(
+            rcon_host=CONAN_RCON_HOST,
+            rcon_port=CONAN_RCON_PORT,
+            rcon_password=CONAN_RCON_PASSWORD,
+            log_mode=CONAN_LOG_MODE,
+            log_path=CONAN_LOG_PATH,
+            sftp_host=CONAN_SFTP_HOST,
+            sftp_port=CONAN_SFTP_PORT,
+            sftp_user=CONAN_SFTP_USER,
+            sftp_password=CONAN_SFTP_PASSWORD,
+        )
+        self.rcon = (
+            RconClient(CONAN_RCON_HOST, CONAN_RCON_PORT, CONAN_RCON_PASSWORD)
+            if self.cfg.rcon_enabled
+            else None
+        )
+        self._log_task = None
+        self._player_task = None
 
     async def cog_load(self):
-        self._task = asyncio.create_task(self._run())
+        # Conan -> Discord chat/event mirroring (only with a log source + target)
+        if self.cfg.log_enabled and (CONAN_CHAT_CHANNEL_ID or CONAN_EVENTS_CHANNEL_ID):
+            self._log_task = asyncio.create_task(self._run_log_watch())
+        else:
+            self.logger.info("Conan: log watch disabled (not configured)")
+
+        # Player-join notifications — disabled when the channel is not defined
+        if CONAN_JOIN_CHANNEL_ID and self.rcon is not None:
+            self._player_task = asyncio.create_task(self._run_player_watch())
+        else:
+            self.logger.info(
+                "Conan: player-join notifications disabled (no channel or RCON)"
+            )
 
     async def cog_unload(self):
-        if self._task:
-            self._task.cancel()
+        for task in (self._log_task, self._player_task):
+            if task is not None:
+                task.cancel()
+        if self.rcon is not None:
+            await self.rcon.close()
 
-    async def _run(self):
+    # ---------------------------------------------------------------- watchers
+    async def _run_log_watch(self):
         await self.bot.wait_until_ready()
-        cfg = self.bot.cfg
-        chat_ch = self.bot.get_channel(cfg.chan_chat)
-        evt_ch = self.bot.get_channel(cfg.chan_events)
+        chat_ch = (
+            self.bot.get_channel(CONAN_CHAT_CHANNEL_ID) if CONAN_CHAT_CHANNEL_ID else None
+        )
+        evt_ch = (
+            self.bot.get_channel(CONAN_EVENTS_CHANNEL_ID)
+            if CONAN_EVENTS_CHANNEL_ID
+            else None
+        )
 
-        async def on_event(e: Event):
-            target = chat_ch if e.kind == "chat" else evt_ch
+        async def on_event(event: Event):
+            target = chat_ch if event.kind == "chat" else evt_ch
             if target is not None:
-                # allowed_mentions: nie pinguj nikogo treścią z gry
-                await target.send(e.text, allowed_mentions=discord.AllowedMentions.none())
+                await target.send(
+                    event.text, allowed_mentions=discord.AllowedMentions.none()
+                )
 
-        log.info("Start obserwacji logu (tryb=%s)", cfg.log_mode)
-        await watch(cfg, on_event)
+        self.logger.info("Conan: starting log watch (mode=%s)", self.cfg.log_mode)
+        await watch(self.cfg, on_event)
 
-class ToConan(commands.Cog):
-    def __init__(self, bot: commands.Bot):
-        self.bot = bot
+    async def _run_player_watch(self):
+        """Task 2: announce on a defined channel when a player joins the server."""
+        await self.bot.wait_until_ready()
+        channel = self.bot.get_channel(CONAN_JOIN_CHANNEL_ID)
+        if channel is None:
+            self.logger.warning(
+                "Conan: join channel %s not found — player notifications off",
+                CONAN_JOIN_CHANNEL_ID,
+            )
+            return
+
+        async def on_join(name: str):
+            await channel.send(
+                f"🟢 **{name}** wszedł na serwer Conan",
+                allowed_mentions=discord.AllowedMentions.none(),
+            )
+
+        self.logger.info(
+            "Conan: starting player-join watch (channel=%s, every %ss)",
+            CONAN_JOIN_CHANNEL_ID,
+            CONAN_PLAYER_POLL_SECONDS,
+        )
+        await watch_players(self.rcon, CONAN_PLAYER_POLL_SECONDS, on_join)
+
+    # ----------------------------------------------------- Discord -> Conan
+    async def _require_rcon(self, ctx: commands.Context):
+        if self.rcon is None:
+            await ctx.reply(
+                "⛔ RCON Conana nie jest skonfigurowany/dostępny.",
+                mention_author=False,
+            )
+            return None
+        return self.rcon
 
     @commands.command(name="say")
     @is_gm()
     async def say(self, ctx: commands.Context, *, message: str):
         """Discord -> Conan: ogłoszenie widoczne dla wszystkich graczy w grze."""
-        resp = await self.bot.rcon.command(f"broadcast {message}")
-        await ctx.reply(f"✅ Wysłano do gry. (serwer: `{resp.strip() or 'OK'}`)",
-                        mention_author=False)
+        rcon = await self._require_rcon(ctx)
+        if rcon is None:
+            return
+        resp = await rcon.command(f"broadcast {message}")
+        await ctx.reply(
+            f"✅ Wysłano do gry. (serwer: `{resp.strip() or 'OK'}`)",
+            mention_author=False,
+        )
 
     @commands.command(name="players")
     @is_gm()
     async def players(self, ctx: commands.Context):
         """Lista graczy online (RCON listplayers)."""
-        resp = await self.bot.rcon.command("listplayers")
-        await ctx.reply(f"```\n{resp.strip() or 'brak danych'}\n```",
-                        mention_author=False)
+        rcon = await self._require_rcon(ctx)
+        if rcon is None:
+            return
+        resp = await rcon.command("listplayers")
+        await ctx.reply(
+            f"```\n{resp.strip() or 'brak danych'}\n```", mention_author=False
+        )
 
     @commands.command(name="kick")
     @is_gm()
     async def kick(self, ctx: commands.Context, *, who: str):
         """Wyrzuć gracza (po nazwie/charname — zależnie od wersji serwera)."""
-        resp = await self.bot.rcon.command(f"kick {who}")
+        rcon = await self._require_rcon(ctx)
+        if rcon is None:
+            return
+        resp = await rcon.command(f"kick {who}")
         await ctx.reply(f"👢 `{resp.strip() or 'OK'}`", mention_author=False)
 
     @commands.command(name="rcon")
     @is_gm()
     async def raw_rcon(self, ctx: commands.Context, *, cmd: str):
         """Surowa komenda RCON (dla zaawansowanych GM). Używaj ostrożnie."""
-        resp = await self.bot.rcon.command(cmd)
+        rcon = await self._require_rcon(ctx)
+        if rcon is None:
+            return
+        resp = await rcon.command(cmd)
         await ctx.reply(f"```\n{resp.strip() or 'OK'}\n```", mention_author=False)
 
-    # --- HOOK pod przyszły mod mostu (Chat V2 API) ---
     @commands.command(name="ogłoś", aliases=["oglos", "rp"])
     @is_gm()
     async def rp_announce(self, ctx: commands.Context, nadawca: str, *, message: str):
         """Wiadomość RP 'z nadawcą' (np. ogłoszenie w imieniu Króla Khasara).
 
-        Na samym RCON realizujemy to jako sformatowany broadcast. Gdy dodasz
-        własny mod na Chat V2 API z dedykowaną komendą czatu, podmień tę linię
-        na wywołanie tej komendy (np. 'tot_rp_say <nadawca> <msg>').
+        Na samym RCON realizujemy to jako sformatowany broadcast.
         """
-        resp = await self.bot.rcon.command(f"broadcast [{nadawca}]: {message}")
+        rcon = await self._require_rcon(ctx)
+        if rcon is None:
+            return
+        resp = await rcon.command(f"broadcast [{nadawca}]: {message}")
         await ctx.reply(f"📜 Ogłoszono jako **{nadawca}**.", mention_author=False)
 
 
-async def setup(bot: commands.Bot):
-    await bot.add_cog(ToConan(bot))
-    await bot.add_cog(FromConan(bot))
-
-
+async def setup(bot):
+    logger = logging.getLogger("discord")
+    await bot.add_cog(ConanModule(bot, "discord"))
+    logger.info("Loading conanjurer commands module done")

conanjurer_functions.py

@@ -1,92 +1,103 @@
+# This Python file uses the following encoding: utf-8
+"""Helper logic for the Conan Exiles <-> Discord bridge.
+
+Mirrors the project layout: the cog lives in ``conanjurer_commands.py`` and the
+reusable logic lives here.  Configuration comes from :mod:`constants` (env-var
+overridable); optional third-party dependencies (``aiomcrcon``/``asyncssh``)
+are imported defensively so the main bot can still load the extension when the
+Conan integration is not installed or not in use.
+"""
 from __future__ import annotations
-import os
-from dataclasses import dataclass
-from dotenv import load_dotenv
+
 import asyncio
 import logging
+import os
 import re
-from typing import AsyncIterator, Callable, Awaitable
-from aiomcrcon import Client as _Rcon  # Source RCON over TCP
-import asyncssh
+from dataclasses import dataclass
+from typing import AsyncIterator, Awaitable, Callable, Optional, Set
+
+try:
+    from aiomcrcon import Client as _Rcon  # Source RCON over TCP
+except ImportError:  # pragma: no cover - optional component
+    _Rcon = None
+
+try:
+    import asyncssh
+except ImportError:  # pragma: no cover - optional component
+    asyncssh = None
+
+logger = logging.getLogger("discord")
 
-load_dotenv()
 
-log = logging.getLogger("discord")
 @dataclass
 class Event:
-    kind: str        # "chat" | "login" | "logout" | "death" | "raw"
-    text: str        # gotowy do wyświetlenia tekst
-    raw: str         # oryginalna linia (do debugowania)
+    kind: str  # "chat" | "login" | "logout" | "death" | "raw"
+    text: str  # ready-to-display text
+    raw: str   # original line (for debugging)
 
 
-# --- REGEXY DO DOSTROJENIA NA WŁASNYM LOGU ---
-# Poniżej PRZYKŁADOWE wzorce. Conan/Pippi/Tot logują różnie — sprawdź swój log
-# i dopasuj. Jeśli wzorzec nie pasuje, linia trafia jako "raw" tylko do debug.
-_PATTERNS: list[tuple[str, re.Pattern]] = [
-    ("chat",   re.compile(r"Chat:\s*(?P<who>.+?):\s*(?P<msg>.+)$", re.I)),
-    ("login",  re.compile(r"(?P<who>.+?)\s+(joined|connected|logged in)", re.I)),
-    ("logout", re.compile(r"(?P<who>.+?)\s+(left|disconnected|logged out)", re.I)),
-    ("death",  re.compile(r"(?P<who>.+?)\s+was killed by\s+(?P<by>.+)$", re.I)),
-]
+@dataclass
+class ConanConfig:
+    """Runtime configuration for the bridge, built from :mod:`constants`."""
 
-@dataclass(frozen=True)
-class Config:
-    # Discord
-    guild_id: int
-    chan_chat: int
-    chan_events: int
-    gm_role_id: int
-    # RCON
     rcon_host: str
     rcon_port: int
     rcon_password: str
-    # Log
-    log_mode: str          # "local" | "sftp"
+    log_mode: str  # "local" | "sftp"
     log_path: str
-    sftp_host: str | None
+    sftp_host: str
     sftp_port: int
-    sftp_user: str | None
-    sftp_password: str | None
+    sftp_user: str
+    sftp_password: str
 
-    @staticmethod
-    def load() -> "Config":
-        mode = os.getenv("LOG_MODE", "local").lower()
-        return Config(
-            guild_id=int(_req("DISCORD_GUILD_ID")),
-            chan_chat=int(_req("CHAN_CHAT")),
-            chan_events=int(_req("CHAN_EVENTS")),
-            gm_role_id=int(_req("GM_ROLE_ID")),
-            rcon_host=_req("RCON_HOST"),
-            rcon_port=int(os.getenv("RCON_PORT", "25575")),
-            rcon_password=_req("RCON_PASSWORD"),
-            log_mode=mode,
-            log_path=_req("LOG_PATH"),
-            sftp_host=os.getenv("SFTP_HOST"),
-            sftp_port=int(os.getenv("SFTP_PORT", "22")),
-            sftp_user=os.getenv("SFTP_USER"),
-            sftp_password=os.getenv("SFTP_PASSWORD"),
-        )
+    @property
+    def rcon_enabled(self) -> bool:
+        """RCON usable only when host+password are set and the lib is present."""
+        return bool(self.rcon_host and self.rcon_password and _Rcon is not None)
+
+    @property
+    def log_enabled(self) -> bool:
+        """Log following usable only when its prerequisites are configured."""
+        if not self.log_path:
+            return False
+        if self.log_mode == "sftp":
+            return bool(self.sftp_host and asyncssh is not None)
+        return True
+
+
+# --- REGEXY DO DOSTROJENIA NA WŁASNYM LOGU ---
+# Conan/Pippi/Tot logują różnie — dopasuj do swojego logu. Linie niepasujące są
+# ignorowane (nie zgadujemy).
+_PATTERNS: list[tuple[str, re.Pattern]] = [
+    ("chat", re.compile(r"Chat:\s*(?P<who>.+?):\s*(?P<msg>.+)$", re.I)),
+    ("login", re.compile(r"(?P<who>.+?)\s+(joined|connected|logged in)", re.I)),
+    ("logout", re.compile(r"(?P<who>.+?)\s+(left|disconnected|logged out)", re.I)),
+    ("death", re.compile(r"(?P<who>.+?)\s+was killed by\s+(?P<by>.+)$", re.I)),
+]
 
 
 class RconClient:
+    """Thin async wrapper around a Source-RCON connection to the Conan server."""
+
     def __init__(self, host: str, port: int, password: str):
         self._host, self._port, self._pw = host, port, password
-        self._client: _Rcon | None = None
+        self._client: Optional["_Rcon"] = None
         self._lock = asyncio.Lock()
 
-    async def _ensure(self) -> _Rcon:
+    async def _ensure(self) -> "_Rcon":
+        if _Rcon is None:
+            raise RuntimeError("aiomcrcon not installed — RCON unavailable")
         if self._client is None:
-            c = _Rcon(self._host, self._port, self._pw)
-            await c.connect()
-            self._client = c
-            log.info("RCON połączony %s:%s", self._host, self._port)
+            client = _Rcon(self._host, self._port, self._pw)
+            await client.connect()
+            self._client = client
+            logger.info("RCON connected %s:%s", self._host, self._port)
         return self._client
 
     async def command(self, cmd: str) -> str:
-        """Wyślij komendę do serwera Conana. Zwraca odpowiedź serwera.
+        """Send a command to the Conan server and return its response.
 
-        To jest KANAŁ Discord -> Conan. Np. command("broadcast Witajcie!")
-        wyświetli komunikat wszystkim graczom w grze.
+        Discord -> Conan channel, e.g. ``command("broadcast Hi!")``.
         """
         async with self._lock:
             for attempt in (1, 2):
@@ -94,8 +105,8 @@ class RconClient:
                     client = await self._ensure()
                     resp, _ = await client.send_cmd(cmd)
                     return resp
-                except Exception as e:  # rozłączenie/restart serwera
-                    log.warning("RCON błąd (próba %s): %s", attempt, e)
+                except Exception as exc:  # disconnect / server restart
+                    logger.warning("RCON error (attempt %s): %s", attempt, exc)
                     await self.close()
                     if attempt == 2:
                         raise
@@ -106,20 +117,19 @@ class RconClient:
         if self._client is not None:
             try:
                 await self._client.close()
-            except Exception:
+            except Exception:  # pragma: no cover - best effort
                 pass
             self._client = None
 
 
-
-def parse_line(line: str) -> Event | None:
+def parse_line(line: str) -> Optional[Event]:
     line = line.rstrip("\n")
     if not line.strip():
         return None
     for kind, pat in _PATTERNS:
-        m = pat.search(line)
-        if m:
-            g = m.groupdict()
+        match = pat.search(line)
+        if match:
+            g = match.groupdict()
             if kind == "chat":
                 return Event(kind, f"💬 **{g['who']}**: {g['msg']}", line)
             if kind == "login":
@@ -128,42 +138,98 @@ def parse_line(line: str) -> Event | None:
                 return Event(kind, f"⚪ **{g['who']}** opuścił grę", line)
             if kind == "death":
                 return Event(kind, f"💀 **{g['who']}** zginął z ręki {g['by']}", line)
-    return None  # nierozpoznane -> ignoruj (nie zgadujemy)
+    return None  # nierozpoznane -> ignoruj
+
+
+def parse_players(listplayers_output: str) -> Set[str]:
+    """Extract the set of connected player char-names from RCON ``listplayers``.
+
+    Conan's table is roughly::
+
+        Idx | Char name | Player name | User ID | Platform ID | Platform Name
+        0   | Conan     | SomeUser    | 12345   | 765...      | Steam
+
+    The char-name column (index 1) is used.  The exact format varies between
+    server builds, so this is best-effort and intentionally tunable.
+    """
+    players: Set[str] = set()
+    for raw in listplayers_output.splitlines():
+        line = raw.strip()
+        if not line or "|" not in line:
+            continue
+        cols = [c.strip() for c in line.split("|")]
+        head = cols[0].lower()
+        # skip the header row and any separator rows (e.g. "---|---")
+        if head in ("idx", "") or set(cols[0]) <= set("-"):
+            continue
+        if len(cols) >= 2 and cols[1]:
+            players.add(cols[1])
+    return players
+
+
+async def watch_players(
+    rcon: RconClient,
+    interval: float,
+    on_join: Callable[[str], Awaitable[None]],
+) -> None:
+    """Poll RCON ``listplayers`` and call *on_join* for each new player.
+
+    The first poll seeds the known-player set without announcing, so restarting
+    the bot does not re-announce everyone already online.  RCON failures are
+    logged and retried on the next tick rather than killing the task.
+    """
+    known: Optional[Set[str]] = None
+    while True:
+        try:
+            response = await rcon.command("listplayers")
+            current = parse_players(response)
+            if known is None:
+                known = current
+            else:
+                for name in current - known:
+                    try:
+                        await on_join(name)
+                    except Exception:  # pragma: no cover - handler guard
+                        logger.exception("Conan: on_join handler failed")
+                known = current
+        except Exception as exc:
+            logger.warning("Conan: player poll failed: %s", exc)
+        await asyncio.sleep(interval)
 
 
 async def _follow_local(path: str) -> AsyncIterator[str]:
-    """tail -f w czystym asyncio, podąża też po rotacji pliku."""
-    import os
+    """``tail -f`` in pure asyncio, following log rotation."""
     while True:
         try:
-            with open(path, "r", encoding="utf-8", errors="replace") as f:
-                f.seek(0, os.SEEK_END)
-                inode = os.fstat(f.fileno()).st_ino
+            with open(path, "r", encoding="utf-8", errors="replace") as handle:
+                handle.seek(0, os.SEEK_END)
+                inode = os.fstat(handle.fileno()).st_ino
                 while True:
-                    line = f.readline()
+                    line = handle.readline()
                     if line:
                         yield line
                         continue
                     await asyncio.sleep(0.5)
-                    # wykryj rotację logu
                     try:
-                        if os.stat(path).st_ino != inode:
+                        if os.stat(path).st_ino != inode:  # rotation
                             break
                     except FileNotFoundError:
                         break
         except FileNotFoundError:
-            log.warning("Log nie istnieje jeszcze: %s", path)
+            logger.warning("Conan log not present yet: %s", path)
             await asyncio.sleep(3.0)
 
 
-async def _follow_sftp(cfg) -> AsyncIterator[str]:
-    """Polling przyrostowy po SFTP (Host Havoc). Czyta tylko nowe bajty."""
+async def _follow_sftp(cfg: ConanConfig) -> AsyncIterator[str]:
+    """Incremental SFTP polling (e.g. Host Havoc): reads only new bytes."""
     offset = 0
     while True:
         try:
             async with asyncssh.connect(
-                cfg.sftp_host, port=cfg.sftp_port,
-                username=cfg.sftp_user, password=cfg.sftp_password,
+                cfg.sftp_host,
+                port=cfg.sftp_port,
+                username=cfg.sftp_user,
+                password=cfg.sftp_password,
                 known_hosts=None,
             ) as conn:
                 async with conn.start_sftp_client() as sftp:
@@ -171,36 +237,30 @@ async def _follow_sftp(cfg) -> AsyncIterator[str]:
                         try:
                             attrs = await sftp.stat(cfg.log_path)
                             size = attrs.size or 0
-                            if size < offset:      # rotacja
+                            if size < offset:  # rotation
                                 offset = 0
                             if size > offset:
-                                async with sftp.open(cfg.log_path, "r") as rf:
-                                    await rf.seek(offset)
-                                    chunk = await rf.read()
+                                async with sftp.open(cfg.log_path, "r") as remote:
+                                    await remote.seek(offset)
+                                    chunk = await remote.read()
                                     offset = size
-                                    for ln in chunk.splitlines():
-                                        yield ln
+                                    for line in chunk.splitlines():
+                                        yield line
                         except FileNotFoundError:
-                            log.warning("SFTP: brak logu %s", cfg.log_path)
+                            logger.warning("SFTP: missing log %s", cfg.log_path)
                         await asyncio.sleep(2.0)
-        except Exception as e:
-            log.warning("SFTP rozłączony: %s — ponawiam", e)
+        except Exception as exc:
+            logger.warning("SFTP disconnected: %s — retrying", exc)
             await asyncio.sleep(5.0)
 
 
-async def watch(cfg, on_event: Callable[[Event], Awaitable[None]]) -> None:
-    source = _follow_local(cfg.log_path) if cfg.log_mode == "local" else _follow_sftp(cfg)
+async def watch(cfg: ConanConfig, on_event: Callable[[Event], Awaitable[None]]) -> None:
+    """Follow the Conan log and dispatch recognised lines to *on_event*."""
+    source = _follow_local(cfg.log_path) if cfg.log_mode != "sftp" else _follow_sftp(cfg)
     async for line in source:
-        evt = parse_line(line)
-        if evt is not None:
+        event = parse_line(line)
+        if event is not None:
             try:
-                await on_event(evt)
-            except Exception:
-                log.exception("Błąd obsługi zdarzenia")
-
-def _req(key: str) -> str:
-    val = os.getenv(key)
-    if not val or val.startswith("wklej") or val.startswith("000000"):
-        raise RuntimeError(f"Brak/placeholder w .env: {key}")
-    return val
-
+                await on_event(event)
+            except Exception:  # pragma: no cover - handler guard
+                logger.exception("Conan: event handler failed")

conftest.py

@@ -0,0 +1,14 @@
+"""Pytest bootstrap: make first-party modules importable from the tests.
+
+The bot modules live at the repository root and the musician service lives in
+``conjurer_musician/``; neither is an installable package, so we put both on
+``sys.path`` here.
+"""
+import os
+import sys
+
+_ROOT = os.path.dirname(os.path.abspath(__file__))
+
+for _path in (_ROOT, os.path.join(_ROOT, "conjurer_musician")):
+    if _path not in sys.path:
+        sys.path.insert(0, _path)

conjurer_librarian/scrape_bot.py

@@ -4,6 +4,7 @@ This module contains the code for the scrape bot.
 
 import json
 import logging
+import os
 import random
 import re
 import time
@@ -15,9 +16,9 @@ from urllib.request import urlopen
 from requests import ConnectionError as RequestsConnectionError
 from requests import ConnectTimeout, Timeout
 
-SCR_DATABASE_PATH = r"C:\\Database\\chunks\\"
-SCR_FILENAME = "40_chunk.txt"
-SCR_ENCODING = "utf-8"
+SCR_DATABASE_PATH = os.getenv("CONJURER_LIBRARIAN_DB_PATH", r"C:\\Database\\chunks\\")
+SCR_FILENAME = os.getenv("CONJURER_LIBRARIAN_SCRAPE_CHUNK", "40_chunk.txt")
+SCR_ENCODING = os.getenv("CONJURER_ENCODING", "utf-8")
 
 WORK_Q = Queue()
 random.seed()

conjurer_librarian/search_bot.py

@@ -19,22 +19,20 @@ Global Variables:
 """
 
 # TODO: Wpiemdolić to wszystko w klasę z loggerem przysłanym z góry
+import os
 from queue import Empty, Queue
 from threading import Thread
 import time
 q = Queue()
 #TODO: Count number of lines in files and print to approximate on which part of the file search is
 
-# DATA FOR TEST ONLY
-# MAXTHREADS = 5
-# DATABASE_PATH = r'C:\\Database\\chunks_1\\'
+# Deployment data is environment-overridable so the local DOI database can live
+# on a mounted volume (Docker/Linux) instead of the hardcoded Windows path.
+MAXTHREADS = int(os.getenv("CONJURER_LIBRARIAN_MAXTHREADS", "41"))
+DATABASE_PATH = os.getenv("CONJURER_LIBRARIAN_DB_PATH", r"C:\\Database\\chunks\\")
 
-# DEPLOYMENT DATA
-MAXTHREADS = 41
-DATABASE_PATH = r"C:\\Database\\chunks\\"
-
-ENCODING = "utf-8"
-CHUNK = "_chunk.txt"
+ENCODING = os.getenv("CONJURER_ENCODING", "utf-8")
+CHUNK = os.getenv("CONJURER_LIBRARIAN_CHUNK", "_chunk.txt")
 _sentinel = object()
 WORK_Q_SIZE = 35500000
 
@@ -107,7 +105,7 @@ def consumer(in_q, control_q, doi, live_results, result_list, control_dict, no,
 
                 for item in result_list:
                     if item["DOI"] in data and not item["exists"]:
-                        print(f"HIT in {no} content {data[0]} line {data[1]} file {data[2]} {item["exists"]}")
+                        print(f"HIT in {no} content {data[0]} line {data[1]} file {data[2]} {item['exists']}")
                         _logger.info(data)
                         _logger.info("HIT")
                         item["exists"] = True

conjurer_librarian/search_bot2.py

@@ -108,7 +108,7 @@ def consumer(in_q, control_q, doi, live_results, result_list, control_dict, no,
                 print(f"C{no}{alive_no}\r", end="")
                 for item in result_list:
                     if item["DOI"] in data[0] and not item["exists"]:
-                        print(f"HIT in {no} content {data[0]} line {data[1]} file {data[2]} {item["exists"]}")
+                        print(f"HIT in {no} content {data[0]} line {data[1]} file {data[2]} {item['exists']}")
                         item["exists"] = True
                         live_results.append(item)
                     done_check = done_check and item["exists"]

conjurer_musician/.gitignore

@@ -0,0 +1,7 @@
+# Runtime-generated radio data — keep out of the repo
+all_playlist.playlist
+hit.playlist
+request.playlist
+priority_queue.playlist
+prio_playlist.json
+*.mp3

conjurer_musician/media_search_functions.py

@@ -1,24 +1,44 @@
 #!/usr/bin/env python3
-import argparse
+"""Share-list search/publish helpers for the musician service.
+
+Paths are environment-overridable and the share database / directory are
+accessed lazily, so importing this module has no side effects (the previous
+version ran ``SHARE_DIR.mkdir()`` and read the JSON DB at import time, which
+crashed on any host without the Pi's ``/var/www`` / ``/var/log`` layout — and
+made the service untestable).
+"""
 import json
 import os
-import sys
 import uuid
 from pathlib import Path
 
-# CONFIGURATION
-JSON_DB        = '/var/log/share_scan.json'
-SHARE_DIR      = Path('/var/www/html/share')
-BASE_URL       = 'https://czernobog.pl/share'
+# CONFIGURATION (env-overridable)
+JSON_DB = os.getenv("CONJURER_SHARE_DB", "/var/log/share_scan.json")
+SHARE_DIR = Path(os.getenv("CONJURER_SHARE_DIR", "/var/www/html/share"))
+BASE_URL = os.getenv("CONJURER_SHARE_BASE_URL", "https://czernobog.pl/share")
+
+_entries_cache = None
+
+
+def _ensure_share_dir():
+    SHARE_DIR.mkdir(parents=True, exist_ok=True)
 
-# Ensure share directory exists
-SHARE_DIR.mkdir(parents=True, exist_ok=True)
 
 def load_db():
-    with open(JSON_DB) as f:
-        return json.load(f)['entries']
+    """Load share entries, returning [] when the DB is missing/corrupt."""
+    try:
+        with open(JSON_DB) as handle:
+            return json.load(handle).get("entries", [])
+    except (FileNotFoundError, json.JSONDecodeError):
+        return []
+
+
+def _entries():
+    global _entries_cache
+    if _entries_cache is None:
+        _entries_cache = load_db()
+    return _entries_cache
 
-ENTRIES = load_db()
 
 def relevancy(path, keywords):
     score = 0
@@ -28,17 +48,20 @@ def relevancy(path, keywords):
             score += low.count(kw.lower())
     return score
 
+
 def find_matches(count, keywords):
     scored = []
-    for e in ENTRIES:
-        score = relevancy(e['path'], keywords)
+    for entry in _entries():
+        score = relevancy(entry["path"], keywords)
         if score > 0:
-            scored.append((score, e['path']))
+            scored.append((score, entry["path"]))
     scored.sort(reverse=True, key=lambda x: x[0])
     result = [p for _, p in scored]
     return result[:count]
 
+
 def publish(paths):
+    _ensure_share_dir()
     urls = []
     for path in paths:
         token = uuid.uuid4().hex
@@ -49,4 +72,3 @@ def publish(paths):
             pass
         urls.append(f"{BASE_URL}/{token}")
     return urls
-

constants.py

@@ -1,13 +1,51 @@
+"""Centralised configuration and runtime constants for Conjurer.
+
+Historically this module performed heavy filesystem and credential reads at
+import time which made the bot brittle on hosts that did not mirror the
+original paths.  This version keeps the original platform defaults (so the
+behaviour on the Raspberry Pi / WSL / Windows deployments is unchanged when no
+environment variables are set) but adds three robustness improvements ported
+from the dockerised experiment:
+
+* every path/endpoint can be overridden via an environment variable,
+* JSON state files are loaded defensively (a missing or corrupt file no longer
+  crashes the whole bot at import time),
+* optional dependencies (openai, spotipy, netrc) and credentials are guarded so
+  the bot can still start when a secondary integration is offline, and
+* a shared ``CONJURER_API_KEY`` plus ``service_headers()`` helper enables
+  authenticated internal HTTP calls.
+
+All path constants intentionally remain plain ``str`` (with their original
+trailing separators) to stay byte-for-byte compatible with the existing string
+concatenation in the command modules.
+"""
+
 import json
-import netrc
+import logging
+import os
 from datetime import datetime
 from platform import uname
 from sys import platform
 from typing import List, Optional, TypedDict
 
-import openai
-import spotipy
-from spotipy.oauth2 import SpotifyClientCredentials
+try:
+    import netrc
+except ImportError:  # pragma: no cover - standard on CPython
+    netrc = None
+
+try:
+    import openai
+except ImportError:  # pragma: no cover - optional at runtime
+    openai = None
+
+try:
+    import spotipy
+    from spotipy.oauth2 import SpotifyClientCredentials
+except ImportError:  # pragma: no cover - optional component
+    spotipy = None
+    SpotifyClientCredentials = None
+
+logger = logging.getLogger("discord")
 
 Music_Config = TypedDict(
     "Music_Config",
@@ -30,16 +68,12 @@ MUSIC_FOLDER = ""
 MEMORY_FIVE_SIARA = ""
 MEMORY_FIVE_MUZYKA = ""
 SETTINGS_FILE = ""
-ENCODING = ""
+ENCODING = "utf-8"
 GRAPHICS_PATH = ""
 MUZYKA_MOJEGO_LUDU_HISTORIA = 1500
 MUZYKA_MOJEGO_LUDU_SLOWA_KLUCZOWE = 15
 MUZYKA_MOJEGO_LUDU_PLAJLISTA = 30
 
-FILE_SERVICE_ADDRESS = "http://192.168.1.15:5000"
-RADIO_HARBOR_ADDRESS = "http://192.168.1.15:54321"
-SKIP_TRACK = "/skip"
-
 GET_MP3 = "/mp3"
 SEND_MP3 = "/update_mp3"
 GET_PLAYLIST = "/get_music"
@@ -48,14 +82,13 @@ CREATE_PRIO_PLAYLIST = "/create_priority_playlist"
 
 REQUEST_MUSIC = "/request_radio_file"
 CLEAR_PRIO = "/clear_pr_pls"
-LIBRARIAN_SERVICE_ADDRESS = "http://192.168.1.192:5001"
 SEND_QUERY = "/query"
 TIME_BETWEEN_CALLS = 100000
 LAST_SPONTANEOUS_CALL = datetime.now()
-HOST_ADDRESS = "192.168.1.191"
-PORT_ADDRESS = 5000
 
-# *=========================================== Platform Specific Predefines
+# *=========================================== Platform Specific Defaults
+# These blocks only establish *default* values.  Every constant is overridable
+# through the matching environment variable further below.
 
 if platform in ("linux", "linux2"):
     SEPARATOR_FILE_PATH = "/"
@@ -74,18 +107,18 @@ if platform in ("linux", "linux2"):
         DIR_PATH_SADOX = "/mnt/c/Users/mtusz/OneDrive/Dokumenty/Fansadox"
 
     else:
-        LOGFILE = "/home/pi/Conjurer/discord.log"
-        MEMORY_FIVE_SIARA = "/home/pi/Conjurer/pamiec.json"
-        SYSTEM_GPT_SETTINGS = "/home/pi/Conjurer/system_gpt_settings.json"
-        MEMORY_FIVE_MUZYKA = "/home/pi/Conjurer/pamiec_muzyki.json"
-        MUSIC_FOLDER = "/home/pi/MediaShare/mp3/"
-        SETTINGS_FILE = "/home/pi/Conjurer/settings.json"
-        NETRC_FILE = "/home/pi/.netrc"
-        LOGSTORE = "/home/pi/MediaShara/logs/"
-        ACCIDENT_LOG = "/home/pi/Conjurer/accident_log.json"
+        LOGFILE = "./discord.log"
+        MEMORY_FIVE_SIARA = "./pamiec.json"
+        SYSTEM_GPT_SETTINGS = "./system_gpt_settings.json"
+        MEMORY_FIVE_MUZYKA = "./pamiec_muzyki.json"
+        MUSIC_FOLDER = "./"
+        SETTINGS_FILE = "./settings.json"
+        NETRC_FILE = "/srv/conjurer/secrets/.netrc"
+        LOGSTORE = "./logs/"
+        ACCIDENT_LOG = "./accident_log.json"
         ENCODING = "utf-8"
-        GRAPHICS_PATH = "/home/pi/MediaShare/Conjurer_graphics/"
-        DIR_PATH_SADOX = "/home/pi/MediaShare/Fansadox/"
+        GRAPHICS_PATH = "./Conjurer_graphics/"
+        DIR_PATH_SADOX = "./Fansadox/"
 
 
 elif platform == "win32":
@@ -101,47 +134,245 @@ elif platform == "win32":
     ENCODING = "utf-8"
     DIR_PATH_SADOX = "C:\\Users\\mtusz\\OneDrive\\Dokumenty\\Fansadox\\"
     SEPARATOR_FILE_PATH = "\\"
-with open(SETTINGS_FILE, "r", encoding=ENCODING) as f_settings_file:
-    DATA = json.load(f_settings_file)
-REMOTE_HOST_NAME = "openai"
-netrc_mod = netrc.netrc(NETRC_FILE)
-authTokens = netrc_mod.authenticators(REMOTE_HOST_NAME)
-openai.api_key = authTokens[2]
-OPENAICLIENT = openai.AsyncOpenAI(api_key=openai.api_key)
-REMOTE_HOST_NAME = "discord"
-authTokens = netrc_mod.authenticators(REMOTE_HOST_NAME)
-TOKEN = authTokens[2]
 
-REMOTE_HOST_NAME = "spotipy"
-authTokens = netrc_mod.authenticators(REMOTE_HOST_NAME)
-SPOTIFY_CTRL = spotipy.Spotify(
-    client_credentials_manager=SpotifyClientCredentials(
-        client_id=authTokens[0],
-        client_secret=authTokens[2],
-    )
+else:
+    # Fallback for development hosts (macOS, BSD, …) that match none of the
+    # production platforms.  Everything is rooted next to this file so the
+    # module can at least be imported and unit-tested off-deployment.
+    _BASE_DIR = os.path.dirname(os.path.abspath(__file__))
+    SEPARATOR_FILE_PATH = os.sep
+    LOGFILE = os.path.join(_BASE_DIR, "discord.log")
+    MEMORY_FIVE_SIARA = os.path.join(_BASE_DIR, "pamiec.json")
+    SYSTEM_GPT_SETTINGS = os.path.join(_BASE_DIR, "system_gpt_settings.json")
+    MEMORY_FIVE_MUZYKA = os.path.join(_BASE_DIR, "pamiec_muzyki.json")
+    MUSIC_FOLDER = os.path.join(_BASE_DIR, "music") + os.sep
+    SETTINGS_FILE = os.path.join(_BASE_DIR, "settings.json")
+    NETRC_FILE = os.path.join(os.path.expanduser("~"), ".netrc")
+    LOGSTORE = os.path.join(_BASE_DIR, "logs") + os.sep
+    ACCIDENT_LOG = os.path.join(_BASE_DIR, "accident_log.json")
+    GRAPHICS_PATH = os.path.join(_BASE_DIR, "Conjurer_graphics") + os.sep
+    DIR_PATH_SADOX = os.path.join(_BASE_DIR, "Fansadox") + os.sep
+
+
+# *=========================================== Environment overrides
+# Values stay as plain strings so existing ``PATH + filename`` concatenation in
+# the command modules keeps working unchanged.
+
+# Container-friendly shortcut: point CONJURER_DATA_DIR at a single mounted
+# volume and every writable data file/dir is rooted under it. The per-variable
+# CONJURER_* overrides below still take precedence, so granular control remains
+# possible and the native (Pi) deployment is unaffected when it is unset.
+_DATA_DIR = os.getenv("CONJURER_DATA_DIR")
+if _DATA_DIR:
+    LOGFILE = os.path.join(_DATA_DIR, "discord.log")
+    SETTINGS_FILE = os.path.join(_DATA_DIR, "settings.json")
+    MEMORY_FIVE_SIARA = os.path.join(_DATA_DIR, "pamiec.json")
+    MEMORY_FIVE_MUZYKA = os.path.join(_DATA_DIR, "pamiec_muzyki.json")
+    SYSTEM_GPT_SETTINGS = os.path.join(_DATA_DIR, "system_gpt_settings.json")
+    ACCIDENT_LOG = os.path.join(_DATA_DIR, "accident_log.json")
+    LOGSTORE = os.path.join(_DATA_DIR, "logs") + os.sep
+    GRAPHICS_PATH = os.path.join(_DATA_DIR, "Conjurer_graphics") + os.sep
+    MUSIC_FOLDER = os.path.join(_DATA_DIR, "music") + os.sep
+    DIR_PATH_SADOX = os.path.join(_DATA_DIR, "Fansadox") + os.sep
+
+LOGFILE = os.getenv("CONJURER_LOG_FILE", LOGFILE)
+NETRC_FILE = os.getenv("CONJURER_NETRC_FILE", NETRC_FILE)
+SETTINGS_FILE = os.getenv("CONJURER_SETTINGS_FILE", SETTINGS_FILE)
+MEMORY_FIVE_SIARA = os.getenv("CONJURER_MEMORY_FILE", MEMORY_FIVE_SIARA)
+MEMORY_FIVE_MUZYKA = os.getenv("CONJURER_MUSIC_MEMORY_FILE", MEMORY_FIVE_MUZYKA)
+SYSTEM_GPT_SETTINGS = os.getenv("CONJURER_SYSTEM_GPT_SETTINGS", SYSTEM_GPT_SETTINGS)
+GRAPHICS_PATH = os.getenv("CONJURER_GRAPHICS_PATH", GRAPHICS_PATH)
+MUSIC_FOLDER = os.getenv("CONJURER_MUSIC_FOLDER", MUSIC_FOLDER)
+LOGSTORE = os.getenv("CONJURER_LOGSTORE", LOGSTORE)
+ACCIDENT_LOG = os.getenv("CONJURER_ACCIDENT_LOG", ACCIDENT_LOG)
+DIR_PATH_SADOX = os.getenv("CONJURER_SADOX_DIR", DIR_PATH_SADOX)
+ENCODING = os.getenv("CONJURER_ENCODING", ENCODING)
+SEPARATOR_FILE_PATH = os.getenv("CONJURER_PATH_SEPARATOR", SEPARATOR_FILE_PATH)
+
+# Voice-recognition transcript dumps. Defaults next to the log file (so on the
+# Pi it lands in /home/pi/Conjurer/transcripts/, in docker under /data).
+TRANSCRIPTS_PATH = os.getenv(
+    "CONJURER_TRANSCRIPTS_PATH",
+    os.path.join(os.path.dirname(LOGFILE) or ".", "transcripts") + os.sep,
 )
-REMOTE_HOST_NAME = "youtube"
-authTokens = netrc_mod.authenticators(REMOTE_HOST_NAME)
-YOUTUBE_AUTH = [authTokens[0],authTokens[2]]
 
-WORD_REACTIONS = DATA["word_reactions"]
-CYCLIC_WORDS = DATA["cyclic_words"]
+FILE_SERVICE_ADDRESS = os.getenv("CONJURER_FILE_SERVICE", "http://192.168.1.15:5000")
+RADIO_HARBOR_ADDRESS = os.getenv("CONJURER_RADIO_HARBOR", "http://192.168.1.15:54321")
+SKIP_TRACK = os.getenv("CONJURER_SKIP_ENDPOINT", "/skip")
+LIBRARIAN_SERVICE_ADDRESS = os.getenv(
+    "CONJURER_LIBRARIAN_SERVICE", "http://192.168.1.192:5001"
+)
+HOST_ADDRESS = os.getenv("CONJURER_DISCORD_HOST", "192.168.1.191")
+PORT_ADDRESS = int(os.getenv("CONJURER_DISCORD_PORT", "5000"))
+
+# Shared secret for authenticating internal service-to-service HTTP calls.
+API_SHARED_KEY = os.getenv("CONJURER_API_KEY", "")
+
+
+# *=========================================== Self-healing runtime layout
+# A fresh host/volume must never kill the bot at import time. Missing
+# directories are created and missing state files are seeded - first from the
+# templates shipped alongside this file (repo checkout / docker image), then
+# from a safe empty structure. Existing files are never touched, so preserved
+# history always wins.
+
+_TEMPLATE_DIR = os.path.dirname(os.path.abspath(__file__))
+
+
+def _ensure_dir(path: str) -> None:
+    if not path:
+        return
+    try:
+        os.makedirs(path, exist_ok=True)
+    except OSError as exc:
+        logger.warning("Cannot create directory %s: %s", path, exc)
+
+
+def _seed_file(path: str, template_name: str, empty_content: str) -> None:
+    """Create *path* from the repo template (or *empty_content*) if missing."""
+    if not path or os.path.exists(path):
+        return
+    _ensure_dir(os.path.dirname(path) or ".")
+    template = os.path.join(_TEMPLATE_DIR, template_name)
+    try:
+        if os.path.exists(template) and os.path.abspath(template) != os.path.abspath(path):
+            import shutil
+
+            shutil.copyfile(template, path)
+            logger.warning("Seeded missing %s from repo template", path)
+        else:
+            with open(path, "w", encoding=ENCODING) as handle:
+                handle.write(empty_content)
+            logger.warning("Created missing %s as empty state", path)
+    except OSError as exc:
+        logger.warning("Cannot seed %s: %s", path, exc)
+
+
+def _ensure_runtime_layout() -> None:
+    for directory in (
+        os.path.dirname(LOGFILE) or ".",
+        LOGSTORE,
+        GRAPHICS_PATH,
+        MUSIC_FOLDER,
+        TRANSCRIPTS_PATH,
+    ):
+        _ensure_dir(directory)
+
+    # (target path, template shipped next to this file, empty fallback)
+    _seed_file(SETTINGS_FILE, "settings.json", "{}")
+    _seed_file(SYSTEM_GPT_SETTINGS, "system_gpt_settings.json", "{}")
+    _seed_file(MEMORY_FIVE_SIARA, "pamiec.json", "[]")
+    _seed_file(MEMORY_FIVE_MUZYKA, "pamiec_muzyki.json", "[]")
+    _seed_file(ACCIDENT_LOG, "accident_log.json", "[]")
+
+
+_ensure_runtime_layout()
+
+
+# *=========================================== Defensive state loading
+def _load_json(path: str, fallback):
+    """Load JSON from *path*, falling back gracefully on missing/corrupt files."""
+    try:
+        with open(path, "r", encoding=ENCODING) as handle:
+            return json.load(handle)
+    except FileNotFoundError:
+        logger.warning("Missing JSON file at %s - using fallback", path)
+        return fallback
+    except json.JSONDecodeError:
+        logger.warning("Corrupt JSON at %s - resetting to fallback", path)
+        return fallback
+
+
+DATA = _load_json(SETTINGS_FILE, {})
+WORD_REACTIONS = DATA.get("word_reactions", {})
+CYCLIC_WORDS = DATA.get("cyclic_words", {})
 for key in WORD_REACTIONS:
-    WORD_REACTIONS[key][2] = datetime.now()
-with open(MEMORY_FIVE_SIARA, "r+", encoding=ENCODING) as temp_memory_file:
-    # First we load existing data into a dict.
-    MESSAGE_TABLE = json.load(temp_memory_file)
+    if isinstance(WORD_REACTIONS[key], list) and len(WORD_REACTIONS[key]) >= 3:
+        WORD_REACTIONS[key][2] = datetime.now()
 
-with open(SYSTEM_GPT_SETTINGS, "r+", encoding=ENCODING) as temp_settings_file:
-    # First we load existing data into a dict.
-    GPT_SETTINGS = json.load(temp_settings_file)
-with open(MEMORY_FIVE_MUZYKA, "r+", encoding=ENCODING) as temp_music_memory_file:
-    # First we load existing data into a dict.
-    MESSAGE_TABLE_MUZYKA = json.load(temp_music_memory_file)
-SPECJALNE_ZIEMNIACZKI = GPT_SETTINGS[1]
+MESSAGE_TABLE = _load_json(MEMORY_FIVE_SIARA, [])
+GPT_SETTINGS = _load_json(SYSTEM_GPT_SETTINGS, {})
+MESSAGE_TABLE_MUZYKA = _load_json(MEMORY_FIVE_MUZYKA, [])
+
+SPECJALNE_ZIEMNIACZKI = GPT_SETTINGS[1] if isinstance(GPT_SETTINGS, list) else {}
 ASSISTANTS = {}
 
 
+# *=========================================== Credentials
+def _load_netrc_credentials(host: str):
+    """Return the netrc authenticators tuple for *host* or ``None``."""
+    if netrc is None:
+        return None
+    try:
+        parsed = netrc.netrc(NETRC_FILE)
+    except FileNotFoundError:
+        logger.warning("netrc file %s not found", NETRC_FILE)
+        return None
+    except netrc.NetrcParseError:
+        logger.warning("netrc file %s is invalid", NETRC_FILE)
+        return None
+    return parsed.authenticators(host)
+
+
+def _resolve_token(host: str, env_var: str) -> Optional[str]:
+    """Prefer an environment variable, then fall back to netrc."""
+    env_value = os.getenv(env_var)
+    if env_value:
+        return env_value
+    creds = _load_netrc_credentials(host)
+    if creds:
+        return creds[2]
+    logger.warning("Token for %s not configured", host)
+    return None
+
+
+OPENAI_API_KEY = _resolve_token("openai", "OPENAI_API_KEY")
+if openai and OPENAI_API_KEY:
+    openai.api_key = OPENAI_API_KEY
+    OPENAICLIENT = openai.AsyncOpenAI(api_key=OPENAI_API_KEY)
+else:
+    OPENAICLIENT = None
+
+TOKEN = _resolve_token("discord", "DISCORD_TOKEN")
+
+# Voice recognition (AssemblyAI). None = the voice cog reports and disables.
+ASSEMBLYAI_API_KEY = _resolve_token("assemblyai", "ASSEMBLYAI_API_KEY")
+
+if spotipy:
+    _spotify_creds = _load_netrc_credentials("spotipy")
+    if _spotify_creds and SpotifyClientCredentials:
+        SPOTIFY_CTRL = spotipy.Spotify(
+            client_credentials_manager=SpotifyClientCredentials(
+                client_id=_spotify_creds[0],
+                client_secret=_spotify_creds[2],
+            )
+        )
+    else:
+        SPOTIFY_CTRL = None
+else:
+    SPOTIFY_CTRL = None
+
+_youtube_creds = _load_netrc_credentials("youtube")
+if _youtube_creds:
+    YOUTUBE_AUTH = [_youtube_creds[0], _youtube_creds[2]]
+else:
+    YOUTUBE_AUTH = [
+        os.getenv("YOUTUBE_USERNAME", ""),
+        os.getenv("YOUTUBE_PASSWORD", ""),
+    ]
+
+
+def service_headers():
+    """Shared header dict for internal service-to-service HTTP calls.
+
+    Returns an empty dict when no key is configured, keeping calls backward
+    compatible with deployments that do not (yet) enforce authentication.
+    """
+    if API_SHARED_KEY:
+        return {"X-Conjurer-Api-Key": API_SHARED_KEY}
+    return {}
+
+
 LATEX_TEX_ENGINE = "tectonic"
 LATEX_MAX_COMPILE_SECONDS = 45
 LATEX_MAX_ATTACH_MB = 8
@@ -153,3 +384,26 @@ ALLOWED_ROLES = ["Nocna Zmiana", "Jarl", "Thane", "Bartender"]
 GUILD_ID = 664789470779932693
 LATEST_MODEL = "gpt-4o"          # najnowszy/do rozmów (możesz zmienić w jednym miejscu)
 CHEAP_MODEL  = "gpt-4o-mini"     # najtańszy (fallback do 3.5 niżej)
+
+
+# *=========================================== Conan Exiles bridge
+# Every value is optional; the conanjurer cog stays dormant unless configured.
+# Channel/role ids default to 0 ("not defined"); RCON host/log path default to
+# "" ("disabled"). See conanjurer_commands.py / conanjurer_functions.py.
+CONAN_GM_ROLE_ID = int(os.getenv("CONAN_GM_ROLE_ID", "0"))
+CONAN_CHAT_CHANNEL_ID = int(os.getenv("CONAN_CHAT_CHANNEL_ID", "0"))
+CONAN_EVENTS_CHANNEL_ID = int(os.getenv("CONAN_EVENTS_CHANNEL_ID", "0"))
+# Player-join notifications: leave at 0 to keep the feature disabled.
+CONAN_JOIN_CHANNEL_ID = int(os.getenv("CONAN_JOIN_CHANNEL_ID", "0"))
+CONAN_PLAYER_POLL_SECONDS = int(os.getenv("CONAN_PLAYER_POLL_SECONDS", "60"))
+
+CONAN_RCON_HOST = os.getenv("CONAN_RCON_HOST", "")
+CONAN_RCON_PORT = int(os.getenv("CONAN_RCON_PORT", "25575"))
+CONAN_RCON_PASSWORD = os.getenv("CONAN_RCON_PASSWORD", "")
+
+CONAN_LOG_MODE = os.getenv("CONAN_LOG_MODE", "local")  # "local" | "sftp"
+CONAN_LOG_PATH = os.getenv("CONAN_LOG_PATH", "")
+CONAN_SFTP_HOST = os.getenv("CONAN_SFTP_HOST", "")
+CONAN_SFTP_PORT = int(os.getenv("CONAN_SFTP_PORT", "22"))
+CONAN_SFTP_USER = os.getenv("CONAN_SFTP_USER", "")
+CONAN_SFTP_PASSWORD = os.getenv("CONAN_SFTP_PASSWORD", "")

docker/Dockerfile.bot

@@ -0,0 +1,64 @@
+# Conjurer main Discord bot.
+# Build from the repository root:
+#   docker build -f docker/Dockerfile.bot -t conjurer-bot .
+FROM python:3.13-trixie
+
+# System dependencies:
+#   ffmpeg        - audio download/convert (yt_dlp) and Discord voice
+#   libopus0      - Discord voice (PyNaCl / discord-ext-voice-recv)
+#   poppler-utils - pdf2image (librarian/latex previews)
+#   git           - required by the git+https entry in requirements
+#   build-essential - native wheels (PyNaCl etc.)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        ffmpeg \
+        libopus0 \
+        poppler-utils \
+        git \
+        build-essential \
+        curl \
+        ca-certificates \
+        python3-dev \
+        build-essential \
+        portaudio19-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Optional: Tectonic for the $latex command. Remove this layer if unused.
+RUN curl -fsSL https://drop-sh.fullyjustified.net | sh \
+    && mv tectonic /usr/local/bin/tectonic \
+    || echo "tectonic not installed - the LaTeX feature will be disabled"
+
+COPY requirements_bot.txt requirements_conan.txt ./
+RUN pip install --no-cache-dir --upgrade pip \
+    && pip install --no-cache-dir -r requirements_bot.txt
+# Best-effort Conan bridge extras: aiomcrcon supports Python <= 3.11 only, so
+# on this 3.13 image the install fails harmlessly and the conanjurer cog stays
+# dormant (its imports are guarded).
+RUN pip install --no-cache-dir -r requirements_conan.txt \
+    || echo "conan extras skipped - conanjurer cog will stay dormant"
+
+# Vendored forks take import precedence over the pip packages of the same name,
+# because /app (the script dir) is first on sys.path when running `python bot.py`.
+COPY yt_dlp ./yt_dlp
+COPY spotify_dl ./spotify_dl
+
+# Bot sources + default config/asset templates. Runtime state (conversation
+# history etc.) is read from the mounted /data volume via CONJURER_DATA_DIR,
+# so these committed copies only act as first-run fallbacks.
+COPY *.py ./
+COPY settings.json system_gpt_settings.json accident_log.json pamiec.json pamiec_muzyki.json ./
+COPY fuckery.jpg willowisp.png wod_beacon.jpg ./
+COPY docker/entrypoint.bot.sh /usr/local/bin/entrypoint.sh
+RUN chmod +x /usr/local/bin/entrypoint.sh
+
+ENV PYTHONUNBUFFERED=1 \
+    CONJURER_DATA_DIR=/data \
+    CONJURER_DISCORD_HOST=0.0.0.0 \
+    CONJURER_DISCORD_PORT=5000
+
+VOLUME ["/data"]
+EXPOSE 5000
+
+ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]
+CMD ["python", "bot.py"]

docker/Dockerfile.librarian

@@ -0,0 +1,27 @@
+# Conjurer librarian (Crossref search + local DOI database lookup).
+# Build from the repository root:
+#   docker build -f docker/Dockerfile.librarian -t conjurer-librarian .
+FROM python:3.11-slim
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+COPY conjurer_librarian/requirements_librarian.txt ./
+RUN pip install --no-cache-dir --upgrade pip \
+    && pip install --no-cache-dir -r requirements_librarian.txt requests
+
+COPY conjurer_librarian/ ./
+
+ENV PYTHONUNBUFFERED=1 \
+    CONJURER_LIBRARIAN_HOST=0.0.0.0 \
+    CONJURER_LIBRARIAN_PORT=5001 \
+    CONJURER_LIBRARIAN_DB_PATH=/doi/
+
+# The local DOI chunk database (large) is mounted here.
+VOLUME ["/doi"]
+EXPOSE 5001
+
+CMD ["python", "conjurer_librarian.py"]

docker/Dockerfile.musician

@@ -0,0 +1,35 @@
+# Conjurer musician (Flask file/playlist service backing the radio).
+# Build from the repository root:
+#   docker build -f docker/Dockerfile.musician -t conjurer-musician .
+#
+# NOTE: this containerises the musician *web service* only. The Liquidsoap
+# radio (radio_conjurer.liq) and any Samba/NFS share tooling run separately.
+FROM python:3.11-slim
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+COPY conjurer_musician/requirements_musician.txt ./
+RUN pip install --no-cache-dir --upgrade pip \
+    && pip install --no-cache-dir -r requirements_musician.txt
+
+COPY conjurer_musician/ ./
+COPY docker/entrypoint.musician.sh /usr/local/bin/entrypoint.sh
+RUN chmod +x /usr/local/bin/entrypoint.sh
+
+ENV PYTHONUNBUFFERED=1 \
+    CONJURER_MUSICIAN_HOST=0.0.0.0 \
+    CONJURER_MUSICIAN_PORT=5000 \
+    CONJURER_MUSIC_FOLDER=/music \
+    CONJURER_MUSICIAN_BASE=/data \
+    CONJURER_STREAM_TEMPLATE=/app/stream.html
+
+# /music = the mp3 library (read-only ok); /data = writable playlists + logs.
+VOLUME ["/music", "/data"]
+EXPOSE 5000
+
+ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]
+CMD ["python", "conjurer_musician.py"]

docker/compose.bot.yaml

@@ -0,0 +1,22 @@
+# Main bot VM. Run from the repository root:
+#   cp docker/env/bot.env.example docker/env/bot.env   # then edit
+#   docker compose -f docker/compose.bot.yaml up -d --build
+services:
+  conjurer-bot:
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile.bot
+    image: conjurer-bot:latest
+    container_name: conjurer-bot
+    restart: unless-stopped
+    env_file:
+      - env/bot.env
+    ports:
+      # Flask comm layer — musician/librarian POST results here (/prepped_tracks, /conjurer).
+      - "5000:5000"
+    volumes:
+      # Persistent state (conversation history, settings, logs). Populate this
+      # host dir with your existing pamiec.json etc. to preserve command history.
+      - /srv/conjurer/data:/data
+      # Tokens: a read-only netrc covers discord/openai/spotipy/youtube in one file.
+      - /srv/conjurer/secrets/.netrc:/secrets/.netrc:ro

docker/compose.librarian.yaml

@@ -0,0 +1,20 @@
+# Librarian VM. Run from the repository root:
+#   cp docker/env/librarian.env.example docker/env/librarian.env   # then edit
+#   docker compose -f docker/compose.librarian.yaml up -d --build
+services:
+  conjurer-librarian:
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile.librarian
+    image: conjurer-librarian:latest
+    container_name: conjurer-librarian
+    restart: unless-stopped
+    env_file:
+      - env/librarian.env
+    ports:
+      - "5001:5001"
+    volumes:
+      # Local DOI chunk database (0_chunk.txt ... N_chunk.txt).
+      - /srv/librarian/doi:/doi:ro
+      # Optional: netrc holding Crossref credentials (or use CONJURER_CROSSREF_MAILTO).
+      - /srv/librarian/secrets/.netrc:/secrets/.netrc:ro

docker/compose.musician.yaml

@@ -0,0 +1,21 @@
+# Musician VM (optional — you plan to adapt/implement this yourself).
+# Run from the repository root:
+#   cp docker/env/musician.env.example docker/env/musician.env   # then edit
+#   docker compose -f docker/compose.musician.yaml up -d --build
+services:
+  conjurer-musician:
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile.musician
+    image: conjurer-musician:latest
+    container_name: conjurer-musician
+    restart: unless-stopped
+    env_file:
+      - env/musician.env
+    ports:
+      - "5000:5000"
+    volumes:
+      # The mp3 library the service indexes and serves.
+      - /srv/musician/music:/music
+      # Runtime playlists/logs the service writes.
+      - /srv/musician/data:/data

docker/entrypoint.bot.sh

@@ -0,0 +1,16 @@
+#!/bin/sh
+# Seed the data volume with the baked-in default JSON state on first run only.
+# Existing files (e.g. your preserved pamiec.json history) are never overwritten.
+set -e
+
+DATA="${CONJURER_DATA_DIR:-/data}"
+mkdir -p "$DATA"
+
+for f in settings.json system_gpt_settings.json pamiec.json pamiec_muzyki.json accident_log.json; do
+    if [ ! -e "$DATA/$f" ] && [ -e "/app/$f" ]; then
+        cp "/app/$f" "$DATA/$f"
+        echo "entrypoint: seeded $f into $DATA"
+    fi
+done
+
+exec "$@"

docker/entrypoint.musician.sh

@@ -0,0 +1,23 @@
+#!/bin/sh
+# Prepare the musician's writable volume so the web service starts cleanly on a
+# fresh container. Existing files are never overwritten (preserves your data).
+set -e
+
+DATA="${CONJURER_MUSICIAN_BASE:-/data}"
+MUSIC="${CONJURER_MUSIC_FOLDER:-/music}"
+mkdir -p "$DATA" "$DATA/logs" "$MUSIC"
+
+# The track-forwarding thread tails the Liquidsoap radio logs. When the radio
+# runs separately (or hasn't started yet) these files may not exist; create
+# them empty so the tailer waits instead of crashing.
+for f in radio_log.log persistence.log; do
+    [ -e "$DATA/$f" ] || : > "$DATA/$f"
+done
+
+# Ensure the managed playlists exist (routes/rescan also create them; this just
+# avoids a first-tick race before the initial scan).
+for f in all_playlist.playlist hit.playlist request.playlist priority_queue.playlist; do
+    [ -e "$DATA/$f" ] || : > "$DATA/$f"
+done
+
+exec "$@"

docker/env/bot.env.example

@@ -0,0 +1,39 @@
+# Copy to docker/env/bot.env and fill in. Do NOT commit the real file.
+
+# --- Secrets ------------------------------------------------------------
+# Option A: mount a netrc (recommended — covers discord/openai/spotipy/youtube).
+CONJURER_NETRC_FILE=/secrets/.netrc
+# Option B: pass tokens directly (these take precedence over netrc).
+# DISCORD_TOKEN=
+# OPENAI_API_KEY=
+# ASSEMBLYAI_API_KEY=      # voice recognition; netrc machine 'assemblyai' works too
+# YOUTUBE_USERNAME=
+# YOUTUBE_PASSWORD=
+
+# --- Data ---------------------------------------------------------------
+# Single mounted volume; all writable state is rooted here.
+CONJURER_DATA_DIR=/data
+
+# --- Flask comm layer (inbound from musician/librarian) -----------------
+CONJURER_DISCORD_HOST=0.0.0.0
+CONJURER_DISCORD_PORT=5000
+
+# --- Internal service auth ----------------------------------------------
+# Set the SAME value on bot + musician + librarian. Empty = auth disabled.
+CONJURER_API_KEY=
+
+# --- Where the bot reaches the other services (other Proxmox VMs) --------
+CONJURER_FILE_SERVICE=http://MUSICIAN_VM_IP:5000
+CONJURER_RADIO_HARBOR=http://MUSICIAN_VM_IP:54321
+CONJURER_LIBRARIAN_SERVICE=http://LIBRARIAN_VM_IP:5001
+
+# --- Conan Exiles bridge (optional; empty/0 = disabled) -----------------
+# CONAN_GM_ROLE_ID=0
+# CONAN_RCON_HOST=
+# CONAN_RCON_PORT=25575
+# CONAN_RCON_PASSWORD=
+# CONAN_CHAT_CHANNEL_ID=0
+# CONAN_EVENTS_CHANNEL_ID=0
+# CONAN_JOIN_CHANNEL_ID=0
+# CONAN_LOG_MODE=local
+# CONAN_LOG_PATH=

docker/env/librarian.env.example

@@ -0,0 +1,21 @@
+# Copy to docker/env/librarian.env and fill in.
+
+CONJURER_LIBRARIAN_HOST=0.0.0.0
+CONJURER_LIBRARIAN_PORT=5001
+
+# Same shared secret as the bot (empty = auth disabled).
+CONJURER_API_KEY=
+
+# Where to POST search results back to (the bot's comm layer).
+CONJURER_MAIN_BOT=http://BOT_VM_IP:5000
+
+# Crossref polite-pool contact (or put credentials in netrc under "crossref").
+CONJURER_CROSSREF_MAILTO=you@example.com
+
+# Local DOI chunk database (mounted volume): expects 0_chunk.txt .. N_chunk.txt
+CONJURER_LIBRARIAN_DB_PATH=/doi/
+CONJURER_LIBRARIAN_MAXTHREADS=41
+CONJURER_LIBRARIAN_CHUNK=_chunk.txt
+
+# Optional netrc (for Crossref credentials)
+CONJURER_NETRC_FILE=/secrets/.netrc

docker/env/musician.env.example

@@ -0,0 +1,17 @@
+# Copy to docker/env/musician.env and fill in.
+
+CONJURER_MUSICIAN_HOST=0.0.0.0
+CONJURER_MUSICIAN_PORT=5000
+
+# Same shared secret as the bot (empty = auth disabled).
+CONJURER_API_KEY=
+
+# Where to POST "now playing" / prepped-track updates (the bot's comm layer).
+CONJURER_MAIN_BOT=http://BOT_VM_IP:5000
+
+# The mp3 library (mounted volume).
+CONJURER_MUSIC_FOLDER=/music
+
+# Runtime paths (mounted volume) — playlists/logs the service writes.
+CONJURER_MUSICIAN_BASE=/data
+CONJURER_LOGSTORE=/data/logs

docs/deployment/DOCKER_PROXMOX.md

@@ -0,0 +1,292 @@
+# Conjurer on Docker / Proxmox
+
+Runbook for running Conjurer as Docker containers across Proxmox VMs:
+
+| Component | VM | Container | Port | Image |
+|-----------|----|-----------|------|-------|
+| **Main bot** | VM-bot | `conjurer-bot` | 5000 (Flask comm) | `docker/Dockerfile.bot` |
+| **Librarian** | VM-librarian | `conjurer-librarian` | 5001 | `docker/Dockerfile.librarian` |
+| **Musician** | VM-musician | `conjurer-musician` | 5000 (+ radio) | `docker/Dockerfile.musician` |
+
+The three talk to each other over HTTP on the Proxmox LAN. Direction of calls:
+
+```
+   bot  --(/mp3,/get_music,/add_to_priority,...)-->  musician
+   bot  --(/query)-------------------------------->  librarian
+musician --(/prepped_tracks)-------------------->    bot
+librarian --(/conjurer results)----------------->    bot
+```
+
+Everything is configured through `CONJURER_*` environment variables (see the
+`docker/env/*.env.example` files). Nothing is hardcoded to a host path anymore.
+
+---
+
+## 0. Prerequisites (per VM)
+
+Create a small Linux VM in Proxmox (Debian 12 / Ubuntu 22.04+ is fine), then
+install Docker:
+
+```bash
+sudo apt-get update && sudo apt-get install -y ca-certificates curl git
+curl -fsSL https://get.docker.com | sh
+sudo usermod -aG docker "$USER"   # log out/in afterwards
+```
+
+Clone the repo on each VM (they build from it):
+
+```bash
+sudo mkdir -p /opt && cd /opt
+git clone https://github.com/migatu/conjurer.git
+cd conjurer
+```
+
+> All `docker compose` commands below are run **from the repo root** (`/opt/conjurer`),
+> because the compose files use `context: ..` relative to `docker/`.
+
+---
+
+## 1. Main bot (VM-bot)
+
+### 1a. Prepare host directories
+
+```bash
+sudo mkdir -p /srv/conjurer/data /srv/conjurer/secrets
+```
+
+### 1b. Preserve existing command history  ⭐
+
+The bot's conversation memory and settings live in JSON files. Copy them from
+your current deployment (e.g. the Pi's `/home/pi/Conjurer/`) into the data
+volume so the history carries over:
+
+```bash
+# run on the Pi, or scp the files across, then place them here:
+sudo cp pamiec.json            /srv/conjurer/data/   # AI conversation history
+sudo cp pamiec_muzyki.json     /srv/conjurer/data/   # music-DJ memory
+sudo cp settings.json          /srv/conjurer/data/   # word/cyclic reactions
+sudo cp system_gpt_settings.json /srv/conjurer/data/
+sudo cp accident_log.json      /srv/conjurer/data/   # if present
+```
+
+If you skip this, the container starts with the (empty) template files baked
+into the image and history begins fresh.
+
+### 1c. Tokens
+
+Drop your existing netrc (the one with `discord`, `openai`, `spotipy`,
+`youtube` entries) into the secrets dir:
+
+```bash
+sudo cp ~/.netrc /srv/conjurer/secrets/.netrc
+sudo chmod 600 /srv/conjurer/secrets/.netrc
+```
+
+(Alternatively skip netrc and set `DISCORD_TOKEN` / `OPENAI_API_KEY` in the env
+file — those take precedence.)
+
+### 1d. Configure and launch
+
+```bash
+cp docker/env/bot.env.example docker/env/bot.env
+# edit docker/env/bot.env: set CONJURER_FILE_SERVICE / _LIBRARIAN_SERVICE to the
+# other VMs' IPs, and CONJURER_API_KEY (same value on all three) if you want auth.
+
+docker compose -f docker/compose.bot.yaml up -d --build
+docker logs -f conjurer-bot
+```
+
+Look for `Extension loaded: …` for each cog and `All systems: operational`.
+
+### 1e. Startup model: core cogs vs service-gated cogs
+
+The bot **always** starts with the cogs that depend on nothing but itself
+(administration, AI, other, latex, voice, conanjurer). Cogs that need a
+sibling service are **health-gated**:
+
+| Group | Cogs | Enabled when |
+|-------|------|--------------|
+| musician | `music_commands`, `radio_commands`, `file_search_commands` | `GET {FILE_SERVICE}/mp3` answers |
+| librarian | `librarian_commands` | librarian answers HTTP at all |
+
+When a service is down its cogs stay disabled (commands simply don't exist)
+and the log says so. A watchdog re-checks every 5 minutes and enables the
+cogs the moment the service starts answering — no bot restart needed.
+A single broken cog (missing pip package, bad import) is skipped with a full
+traceback in the log; it never takes the whole bot down.
+
+### 1f. Troubleshooting a crash-looping container
+
+`docker logs conjurer-bot` now shows the real reason (the bot logs to stdout
+as well as the rotating file). The most common cases:
+
+- **`FATAL: Discord token missing`** — the secrets mount is missing/empty or
+  `CONJURER_NETRC_FILE` points elsewhere. Check:
+  `docker inspect -f '{{json .Mounts}}' conjurer-bot | jq` and
+  `docker exec conjurer-bot ls -la /secrets/` (after a manual
+  `docker run … sleep infinity` if it crash-loops too fast).
+- **Missing state files** — not fatal anymore: missing dirs are created and
+  missing JSON state is seeded from the repo templates baked into the image
+  (existing files are never overwritten). Fix the mount at your leisure.
+
+**About files "disappearing" from `/srv/conjurer/...`:** nothing in this stack
+deletes host files — the entrypoint and the bot only ever *create* missing
+files. With a bind mount, `/srv/conjurer/data` **is** the live state (not an
+installation staging area): don't delete it after a successful install.
+If files vanished, the usual suspects are `docker compose down -v` (only
+affects *named* volumes, not binds), a re-provisioned VM, or copying the files
+to a different path than the one in the compose `volumes:` line — verify with
+`docker inspect -f '{{json .Mounts}}' conjurer-bot`.
+
+---
+
+## 2. Librarian (VM-librarian)
+
+### 2a. Mount the DOI database
+
+The librarian checks keyword hits from Crossref against a local database of
+DOI chunk files (`0_chunk.txt … N_chunk.txt`). Put that database on the VM and
+point the volume at it:
+
+```bash
+sudo mkdir -p /srv/librarian/doi /srv/librarian/secrets
+# copy/replicate your chunk files into /srv/librarian/doi/
+```
+
+> The old Windows path `C:\Database\chunks\` is now `CONJURER_LIBRARIAN_DB_PATH`
+> (defaults to `/doi/` in the container). `CONJURER_LIBRARIAN_MAXTHREADS` (41)
+> and `CONJURER_LIBRARIAN_CHUNK` (`_chunk.txt`) are configurable too.
+
+### 2b. Configure and launch
+
+```bash
+cp docker/env/librarian.env.example docker/env/librarian.env
+# edit: CONJURER_MAIN_BOT=http://BOT_VM_IP:5000, CONJURER_CROSSREF_MAILTO, CONJURER_API_KEY
+
+docker compose -f docker/compose.librarian.yaml up -d --build
+docker logs -f conjurer-librarian
+```
+
+---
+
+## 3. Musician (VM-musician)
+
+The web service is container-ready (`docker/Dockerfile.musician` +
+`compose.musician.yaml`). It containerises the **Flask file/playlist service
+only** — the Liquidsoap radio (`radio_conjurer.liq`), `script.params` and any
+Samba/NFS share tooling are separate and typically stay on the host or a
+dedicated setup (you'll adapt those yourself).
+
+### 3a. Two volumes: the library and the writable state
+
+| Mount | Container path | Holds |
+|-------|---------------|-------|
+| `/srv/musician/music` | `/music` (`CONJURER_MUSIC_FOLDER`) | your mp3 library (indexed/served) |
+| `/srv/musician/data` | `/data` (`CONJURER_MUSICIAN_BASE`) | playlists, logs, `radio_log.log`/`persistence.log` |
+
+```bash
+sudo mkdir -p /srv/musician/music /srv/musician/data
+# point /srv/musician/music at (or copy in) your mp3s
+```
+
+### 3b. Preserve existing playlists/state (optional)
+
+If you already run the musician, copy its working playlists into the data
+volume so nothing is regenerated from scratch:
+
+```bash
+sudo cp all_playlist.playlist hit.playlist request.playlist \
+        priority_queue.playlist playlist.json  /srv/musician/data/ 2>/dev/null || true
+```
+
+The container's entrypoint (`docker/entrypoint.musician.sh`) creates any
+missing playlists and touches `radio_log.log` / `persistence.log` empty so the
+track-forwarding thread waits instead of crashing when the radio runs
+elsewhere. It never overwrites files you copied in.
+
+### 3c. Configure and launch
+
+```bash
+cp docker/env/musician.env.example docker/env/musician.env
+# edit: CONJURER_MAIN_BOT=http://BOT_VM_IP:5000 and CONJURER_API_KEY (match the bot)
+
+docker compose -f docker/compose.musician.yaml up -d --build
+docker logs -f conjurer-musician
+```
+
+### 3d. Radio coupling (if you keep Liquidsoap separate)
+
+The musician only forwards "now playing" to the bot by tailing the radio's
+`radio_log.log` / `persistence.log`. To wire them up, have Liquidsoap write
+those two files into the same `/srv/musician/data` directory (or set
+`CONJURER_RADIO_LOG` / `CONJURER_PERSISTENCE_LOG` to wherever it writes). The
+`/stream` page template is served from the baked-in `/app/stream.html`
+(override with `CONJURER_STREAM_TEMPLATE` if you customise it).
+
+---
+
+## 4. Networking & auth
+
+- Open the ports between VMs on the Proxmox LAN: **bot 5000**, **librarian 5001**,
+  **musician 5000** (+ radio harbor 54321 if used). A simple `ufw allow from
+  <lan-subnet>` per port is enough; do not expose them to the internet.
+- **Auth:** set the same `CONJURER_API_KEY` in all three `*.env` files. Then
+  every internal call carries `X-Conjurer-Api-Key` and each service rejects
+  requests without it (HTTP 401). Leave it empty everywhere to disable auth
+  (fully backward compatible). ⚠️ Setting it on only one side breaks the link.
+- The addresses point at each other by VM IP (or a DNS name). Set:
+  - bot: `CONJURER_FILE_SERVICE`, `CONJURER_RADIO_HARBOR`, `CONJURER_LIBRARIAN_SERVICE`
+  - librarian & musician: `CONJURER_MAIN_BOT`
+
+---
+
+## 5. Verify
+
+```bash
+# bot is up and reachable from another VM:
+curl http://BOT_VM_IP:5000/conjurer            # -> "ALIVE"
+# librarian answers:
+curl http://LIBRARIAN_VM_IP:5001/ -I           # service reachable
+docker ps            # all containers "Up"
+docker logs conjurer-bot --tail 50
+```
+
+In Discord, exercise a command that round-trips through a service (e.g. a music
+search that hits the musician, or a librarian query) to confirm the wiring and
+the API key.
+
+---
+
+## 6. Updates
+
+```bash
+cd /opt/conjurer && git pull
+docker compose -f docker/compose.bot.yaml up -d --build   # rebuild + restart
+```
+
+Data in `/srv/.../data` and `/doi` / `/music` volumes survives rebuilds, so
+history and databases persist across updates.
+
+---
+
+## 7. Rollback / coexistence
+
+- The native (Raspberry Pi / systemd) deployment is unaffected — none of the
+  defaults changed; the container behaviour is opt-in via `CONJURER_DATA_DIR`
+  and the other env vars. You can run both during migration.
+- To roll back a VM: `docker compose -f docker/compose.<svc>.yaml down` and
+  restart the previous deployment. The JSON state in `/srv/.../data` is plain
+  files you can copy back to the Pi if needed.
+
+---
+
+## Notes on the images
+
+- **Bot** uses the vendored `yt_dlp/` and `spotify_dl/` forks (they win over the
+  pip packages because `/app` is first on `sys.path`), so your patches stay
+  active without the old `sed` hacks from `install_main_bot.sh`.
+- **Tectonic** (LaTeX `$latex` command) is installed best-effort; if the build
+  step fails the bot still runs, just without LaTeX. Remove that layer from
+  `Dockerfile.bot` if you don't need it.
+- Voice needs `ffmpeg` + `libopus0` (both in the image). No microphone/pyaudio
+  is required — voice is received over Discord and transcribed via AssemblyAI.

librarian_commands.py

@@ -15,7 +15,9 @@ from discord.ext import commands, tasks
 
 from ai_functions import handle_response
 from communication_subroutine import IN_COMM_Q, OUT_COMM_Q, QueryControl
-from constants import DIR_PATH_SADOX, LIBRARIAN_SERVICE_ADDRESS, SEND_QUERY
+from constants import DIR_PATH_SADOX, LIBRARIAN_SERVICE_ADDRESS, SEND_QUERY, service_headers
+
+SERVICE_HEADERS = service_headers()
 
 
 class DataModule(commands.Cog):
@@ -165,6 +167,7 @@ class DataModule(commands.Cog):
             requests.post,
             f"{LIBRARIAN_SERVICE_ADDRESS}{SEND_QUERY}",
             json=json_query,
+            headers=SERVICE_HEADERS,
             timeout=360,
         )
         await ctx.send(
@@ -260,6 +263,7 @@ class DataModule(commands.Cog):
             requests.post,
             f"{LIBRARIAN_SERVICE_ADDRESS}{SEND_QUERY}",
             json=json_query,
+            headers=SERVICE_HEADERS,
             timeout=360,
         )
         await ctx.send(

music_functions.py

@@ -17,10 +17,13 @@ from constants import (
     SEND_MP3,
     SPOTIFY_CTRL,
     YOUTUBE_AUTH,
+    service_headers,
 )
 from spotify_dl import spotify
 from spotify_dl import youtube as youtube_download
 
+SERVICE_HEADERS = service_headers()
+
 
 
 class MusicFileList(object):
@@ -43,7 +46,11 @@ class MusicFileList(object):
         """
         try:
             self.logger.info("Attempt to connect to file service")
-            response = requests.get(f"{FILE_SERVICE_ADDRESS}{GET_MP3}", timeout=360)
+            response = requests.get(
+                f"{FILE_SERVICE_ADDRESS}{GET_MP3}",
+                headers=SERVICE_HEADERS,
+                timeout=360,
+            )
             self.music_file_list = response.json()["music_file_list"]
             self.file_service_active = True
         except requests.exceptions.RequestException as e:
@@ -98,7 +105,12 @@ class MusicFileList(object):
         """
         self.music_file_list.append(item)
         post_data = {"item": str(item)}
-        requests.post(f"{FILE_SERVICE_ADDRESS}{SEND_MP3}", json=post_data, timeout=360)
+        requests.post(
+            f"{FILE_SERVICE_ADDRESS}{SEND_MP3}",
+            json=post_data,
+            headers=SERVICE_HEADERS,
+            timeout=360,
+        )
 
 
 MUSIC_FILE_LIST = MusicFileList("discord")
@@ -308,6 +320,7 @@ async def search_music(ctx, how_many=0, slowa_kluczowe=None):
         requests.post,
         f"{FILE_SERVICE_ADDRESS}{GET_PLAYLIST}",
         json=jrequest,
+        headers=SERVICE_HEADERS,
         timeout=360,
     )
     return_data = await coroutine

pytest.ini

@@ -0,0 +1,5 @@
+[pytest]
+testpaths = tests
+python_files = test_*.py
+python_functions = test_*
+addopts = -ra

radio_commands.py

@@ -8,7 +8,9 @@ import uuid
 
 import asyncio
 from datetime import datetime
-from constants import RADIO_HARBOR_ADDRESS, SKIP_TRACK, FILE_SERVICE_ADDRESS, ADD_TO_PRIO_PLAYLIST, REQUEST_MUSIC, CREATE_PRIO_PLAYLIST, CLEAR_PRIO
+from constants import RADIO_HARBOR_ADDRESS, SKIP_TRACK, FILE_SERVICE_ADDRESS, ADD_TO_PRIO_PLAYLIST, REQUEST_MUSIC, CREATE_PRIO_PLAYLIST, CLEAR_PRIO, service_headers
+
+SERVICE_HEADERS = service_headers()
 
 class RadioModule(commands.Cog):
     def __init__(self, bot, logger_name):
@@ -34,6 +36,7 @@ class RadioModule(commands.Cog):
                 coroutine = asyncio.to_thread(
                     requests.get,
                     f"{RADIO_HARBOR_ADDRESS}{SKIP_TRACK}",
+                    headers=SERVICE_HEADERS,
                     timeout=360,
                 )
                 result = await coroutine
@@ -95,6 +98,7 @@ class RadioModule(commands.Cog):
                 requests.post,
                 f"{FILE_SERVICE_ADDRESS}{ADD_TO_PRIO_PLAYLIST}",
                 json=jrequest,
+                headers=SERVICE_HEADERS,
                 timeout=360,
             )
             result = await coroutine
@@ -130,6 +134,7 @@ class RadioModule(commands.Cog):
                 requests.post,
                 f"{FILE_SERVICE_ADDRESS}{REQUEST_MUSIC}",
                 json=jrequest,
+                headers=SERVICE_HEADERS,
                 timeout=360,
             )
             result = await coroutine
@@ -167,6 +172,7 @@ class RadioModule(commands.Cog):
                 requests.post,
                 f"{FILE_SERVICE_ADDRESS}{CREATE_PRIO_PLAYLIST}",
                 json=jrequest,
+                headers=SERVICE_HEADERS,
                 timeout=360,
             )
             result = await coroutine
@@ -194,6 +200,7 @@ class RadioModule(commands.Cog):
             coroutine = asyncio.to_thread(
                 requests.get,
                 f"{FILE_SERVICE_ADDRESS}{CLEAR_PRIO}",
+                headers=SERVICE_HEADERS,
                 timeout=360,
             )
             result = await coroutine

requirements_bot.txt

@@ -17,4 +17,5 @@ PyMuPDF
 waitress
 assemblyai[extras]
 SpeechRecognition
+asyncssh
 git+https://github.com/imayhaveborkedit/discord-ext-voice-recv

requirements_conan.txt

@@ -0,0 +1,6 @@
+# Optional extras for the Conan Exiles bridge (conanjurer cog).
+#
+# aiomcrcon currently installs only on Python <= 3.11, while the main image
+# runs 3.13. Install is therefore best-effort: when it fails the conanjurer
+# cog simply stays dormant (its imports are guarded) and the bot runs fine.
+aiomcrcon

test.py

@@ -1,20 +0,0 @@
-import logging
-from logging import handlers
-
-logger = logging.getLogger("discord")
-logger.setLevel(logging.DEBUG)
-handler = handlers.RotatingFileHandler(
-    filename="test.log",
-    encoding="utf-8",
-    mode="a",
-    maxBytes=6 * 1024 * 1024,
-    backupCount=6,
-)
-formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
-handler.setFormatter(formatter)
-logger.addHandler(handler)
-
-
-logger2 = logging.getLogger("discord")
-for item in logger2.handlers:
-    print(item)

test_ai.py

@@ -1,13 +0,0 @@
-AsyncCursorPage[Message](
-    data=[Message(id='msg_3eWSdgbcU8sbCmJK2momOgQQ', 
-                  assistant_id='asst_06eZiwvYNK3MR34suFP60gvg', 
-                  attachments=[], 
-                  completed_at=None, 
-                  content=[TextContentBlock(text=Text(annotations=[], value='Cześć! Oto coś do przemyślenia: \n\n„Sukces to suma niewielkich wysiłków powtarzanych dzień po dniu.” — Robert Collier\n\nTo przypomina nam, że często to nie wielkie działania, ale konsekwentne, małe kroki prowadzą do osiągnięcia celu. Jak mogę Ci dzisiaj pomóc?'), type='text')], created_at=1731620112, incomplete_at=None, incomplete_details=None, metadata={}, object='thread.message', role='assistant', run_id='run_JGjWQTCEkDcEYpyCJnrkZU8Q', status=None, thread_id='thread_dDEjGbGm6ICfG75u0KKpoVxD'), Message(id='msg_GFcnfCFgAthGm2D3oE5d0ZkQ', assistant_id=None, attachments=[], completed_at=None, content=[TextContentBlock(text=Text(annotations=[], value='Cześć! Powiedz coś mądrego'), type='text')], created_at=1731620110, incomplete_at=None, incomplete_details=None, metadata={}, object='thread.message', role='user', run_id=None, status=None, thread_id='thread_dDEjGbGm6ICfG75u0KKpoVxD')], object='list', first_id='msg_3eWSdgbcU8sbCmJK2momOgQQ', last_id='msg_GFcnfCFgAthGm2D3oE5d0ZkQ', has_more=False)
-
-
-[TextContentBlock(
-    text=Text(annotations=[], 
-              value='Cześć! Oto coś do rozważenia: "Największą przeszkodą w naszym życiu jest brak odwagi do wprowadzenia zmian." Niezależnie od tego, jakie masz cele czy marzenia, odwaga do działania i przystosowania się do nowych sytuacji jest kluczem do osiągnięcia sukcesu. Jakie masz przemyślenia na ten temat?'), 
-              type='text')
-]

test_time.py

@@ -1,8 +0,0 @@
-import time
-
-first_time = time.time_ns()
-
-time.sleep(1)
-time_diff = time.time_ns() - first_time
-print(time_diff)
-# 2000149433

tests/integration/test_comm_auth.py

@@ -0,0 +1,56 @@
+"""Integration: the bot's communication Flask layer enforces the shared key,
+and the key the bot would *send* (constants.service_headers) is accepted.
+"""
+import constants
+import communication_subroutine as cs
+
+
+def _client(key="test-secret"):
+    cs.API_KEY = key
+    return cs.app.test_client()
+
+
+def test_prepped_tracks_rejected_without_key():
+    client = _client()
+    resp = client.post(
+        "/prepped_tracks", data='["all", "x"]', content_type="application/json"
+    )
+    assert resp.status_code == 401
+
+
+def test_prepped_tracks_accepted_with_key():
+    client = _client()
+    resp = client.post(
+        "/prepped_tracks",
+        data='["all", "x"]',
+        headers={"X-Conjurer-Api-Key": "test-secret"},
+        content_type="application/json",
+    )
+    assert resp.status_code == 200
+
+
+def test_conjurer_get_is_open():
+    client = _client()
+    assert client.get("/conjurer").status_code == 200
+
+
+def test_open_when_key_unset():
+    client = _client(key=None)
+    resp = client.post(
+        "/prepped_tracks", data='["all", "x"]', content_type="application/json"
+    )
+    assert resp.status_code == 200
+
+
+def test_bot_service_headers_accepted_by_service(monkeypatch):
+    # End-to-end auth contract: the header constants.service_headers() produces
+    # is exactly what communication_subroutine._authorize_request() expects.
+    monkeypatch.setattr(constants, "API_SHARED_KEY", "shared-xyz")
+    cs.API_KEY = "shared-xyz"
+    resp = cs.app.test_client().post(
+        "/prepped_tracks",
+        data='["all", "x"]',
+        headers=constants.service_headers(),
+        content_type="application/json",
+    )
+    assert resp.status_code == 200

tests/integration/test_musician_auth.py

@@ -0,0 +1,34 @@
+"""Integration: the musician Flask service enforces the shared key on its
+authenticated endpoints while leaving the open ones reachable.
+"""
+import conjurer_musician as m
+
+
+def _client(key="test-secret"):
+    m.API_KEY = key
+    return m.app.test_client()
+
+
+def test_clear_pr_pls_rejected_without_key():
+    client = _client()
+    assert client.get("/clear_pr_pls").status_code == 401
+
+
+def test_clear_pr_pls_accepted_with_key():
+    client = _client()
+    resp = client.get(
+        "/clear_pr_pls", headers={"X-Conjurer-Api-Key": "test-secret"}
+    )
+    assert resp.status_code == 200
+
+
+def test_mp3_list_is_open():
+    client = _client()
+    resp = client.get("/mp3")
+    assert resp.status_code == 200
+    assert "music_file_list" in resp.get_json()
+
+
+def test_open_when_key_unset():
+    client = _client(key=None)
+    assert client.get("/clear_pr_pls").status_code == 200

tests/unit/test_conanjurer_functions.py

@@ -0,0 +1,63 @@
+"""Unit tests for the Conan Exiles bridge helpers (no Discord/RCON needed)."""
+import conanjurer_functions as cf
+
+
+def test_parse_players_basic():
+    out = (
+        "Idx | Char name | Player name | User ID\n"
+        "0 | Conan | SteamGuy | 1\n"
+        "1 | Khasar | OtherGuy | 2\n"
+        "--- | --- | --- | ---"
+    )
+    assert cf.parse_players(out) == {"Conan", "Khasar"}
+
+
+def test_parse_players_empty_inputs():
+    assert cf.parse_players("No players connected.") == set()
+    assert cf.parse_players("") == set()
+
+
+def test_parse_line_login():
+    event = cf.parse_line("SomeGuy joined the server")
+    assert event is not None
+    assert event.kind == "login"
+    assert "SomeGuy" in event.text
+
+
+def test_parse_line_chat():
+    event = cf.parse_line("Chat: Bob: hello there")
+    assert event is not None
+    assert event.kind == "chat"
+    assert "Bob" in event.text and "hello" in event.text
+
+
+def test_parse_line_unrecognised_is_ignored():
+    assert cf.parse_line("random server noise") is None
+
+
+def test_conanconfig_disabled_when_unconfigured():
+    cfg = cf.ConanConfig("", 25575, "", "local", "", "", 22, "", "")
+    assert cfg.rcon_enabled is False
+    assert cfg.log_enabled is False
+
+
+def test_conanconfig_local_log_enabled():
+    cfg = cf.ConanConfig("", 0, "", "local", "/tmp/conan.log", "", 22, "", "")
+    assert cfg.log_enabled is True
+
+
+def test_conanconfig_rcon_enabled_requires_lib(monkeypatch):
+    # Without aiomcrcon installed, rcon stays disabled even when host+pw are set.
+    monkeypatch.setattr(cf, "_Rcon", None)
+    cfg = cf.ConanConfig("1.2.3.4", 25575, "pw", "local", "", "", 22, "", "")
+    assert cfg.rcon_enabled is False
+    # With the lib present, it enables.
+    monkeypatch.setattr(cf, "_Rcon", object)
+    cfg2 = cf.ConanConfig("1.2.3.4", 25575, "pw", "local", "", "", 22, "", "")
+    assert cfg2.rcon_enabled is True
+
+
+def test_conanconfig_sftp_log_requires_asyncssh(monkeypatch):
+    monkeypatch.setattr(cf, "asyncssh", None)
+    cfg = cf.ConanConfig("", 0, "", "sftp", "/log", "sftp.host", 22, "u", "p")
+    assert cfg.log_enabled is False

tests/unit/test_constants.py

@@ -0,0 +1,35 @@
+"""Unit tests for constants helpers (defensive config / auth headers)."""
+import constants
+
+
+def test_service_headers_empty_when_no_key(monkeypatch):
+    monkeypatch.setattr(constants, "API_SHARED_KEY", "")
+    assert constants.service_headers() == {}
+
+
+def test_service_headers_with_key(monkeypatch):
+    monkeypatch.setattr(constants, "API_SHARED_KEY", "s3cr3t")
+    assert constants.service_headers() == {"X-Conjurer-Api-Key": "s3cr3t"}
+
+
+def test_load_json_missing_returns_fallback(tmp_path):
+    missing = tmp_path / "nope.json"
+    assert constants._load_json(str(missing), {"fallback": 1}) == {"fallback": 1}
+
+
+def test_load_json_valid(tmp_path):
+    good = tmp_path / "ok.json"
+    good.write_text('{"a": 2}', encoding="utf-8")
+    assert constants._load_json(str(good), {}) == {"a": 2}
+
+
+def test_load_json_corrupt_returns_fallback(tmp_path):
+    bad = tmp_path / "bad.json"
+    bad.write_text("{ not valid json", encoding="utf-8")
+    assert constants._load_json(str(bad), []) == []
+
+
+def test_conan_defaults_present():
+    # Feature toggles default to "off" so the bridge stays dormant.
+    assert constants.CONAN_JOIN_CHANNEL_ID == 0
+    assert constants.CONAN_RCON_HOST == ""

voice_recognition_commands.py

@@ -1,6 +1,5 @@
 import asyncio
 import logging
-import netrc
 import time
 import wave
 
@@ -9,11 +8,17 @@ import discord
 from discord.ext import commands, tasks, voice_recv
 from discord.opus import Decoder as OpusDecoder
 
-# Replace with your API key
-NETRC_FILE = "/home/pi/.netrc"
-netrc_mod = netrc.netrc(NETRC_FILE)
-authTokens = netrc_mod.authenticators("assemblyai")
-aai.settings.api_key = authTokens[2]
+from constants import ASSEMBLYAI_API_KEY, TRANSCRIPTS_PATH
+
+# Credentials come from constants (env ASSEMBLYAI_API_KEY, or the 'assemblyai'
+# machine in the netrc at CONJURER_NETRC_FILE). Raising here means the guarded
+# extension loader logs the reason and disables ONLY this cog.
+if not ASSEMBLYAI_API_KEY:
+    raise RuntimeError(
+        "AssemblyAI API key not configured (netrc machine 'assemblyai' or "
+        "ASSEMBLYAI_API_KEY env) - voice recognition stays disabled"
+    )
+aai.settings.api_key = ASSEMBLYAI_API_KEY
 
 discord.opus._load_default()
 CHANNELS = OpusDecoder.CHANNELS
@@ -23,7 +28,7 @@ SAMPLING_RATE = OpusDecoder.SAMPLING_RATE
 # rotate file after there is 0.5s between last received pcm for user.
 # delete messsages after user disconnect
 
-LOCATION = "/home/pi/Conjurer/transcripts/"
+LOCATION = TRANSCRIPTS_PATH
 
 
 class CommunicationObject: