Initial commit: Stoat Role Bot

Co-authored-by: Cursor <cursoragent@cursor.com>

LOCAL-TEST.md

@@ -0,0 +1,94 @@
+# Local testing (verify bot works before/without NAS)
+
+Run the bot on your PC with the same token and config. If it works locally but not on the NAS, the issue is NAS/container. If it fails locally too, the issue is token, config, or Stoat server.
+
+---
+
+## 1. Run with Node.js (fastest)
+
+On your PC, in the project folder:
+
+```bash
+cd "/home/jorg/Documents/Cursor Projects/Role Bot"
+
+# Use the same .env as NAS (token must be set)
+export $(grep -v '^#' .env | xargs)
+export CONFIG_PATH=./config
+
+# Optional: see every message the bot receives (for debugging)
+export DEBUG=1
+
+# Install and run
+npm install
+npm start
+```
+
+You should see:
+- `Connecting to Stoat/Revolt API...`
+- `Logged in as ExodusMigrator — bot is online`
+- With `DEBUG=1`, lines like `Message: !roles [command]` when you type in Stoat
+
+**Test in Stoat:** In a channel the bot can see, send:
+- `!roles` → bot should reply (list of roles or “No self-assignable roles…”).
+- If you have assignable roles set in `config/roles.json`, try `!role add <RoleName>`.
+
+Stop with **Ctrl+C**.
+
+---
+
+## 2. Run with Docker/Podman (same as NAS)
+
+Same setup as the NAS, but on your machine:
+
+```bash
+cd "/home/jorg/Documents/Cursor Projects/Role Bot"
+
+# Ensure .env has STOAT_BOT_TOKEN and config/roles.json exists
+docker compose up
+# or: podman compose up
+```
+
+Leave it running and test `!roles` in Stoat. Stop with **Ctrl+C** (or `docker compose down` in another terminal).
+
+---
+
+## 3. What to check
+
+| Result | Meaning |
+|--------|--------|
+| Local Node: bot replies to `!roles` | Bot and token are fine; problem is likely NAS/container (network or env). |
+| Local Node: no reply to `!roles` | Check: (1) `config/roles.json` has correct **server ID** for your Stoat server, (2) bot is in that server and has a role above the roles it assigns, (3) channel is in that server. |
+| Local Node: "Login failed" or crash | Token invalid/revoked or network block; fix token or firewall. |
+| Local works, NAS doesn’t | On NAS: confirm `STOAT_BOT_TOKEN` is set in the container, and that the NAS can reach the internet (no block on outbound HTTPS). |
+
+---
+
+## 4. Get your server ID for config
+
+If `!roles` says "No self-assignable roles" or "Configured role names don't match", your `config/roles.json` may have the wrong server ID.
+
+In Stoat (web): open your server, check the URL. It often looks like:
+`https://app.revolt.chat/server/01ABC123...`  
+The long ID after `/server/` is your **server ID**. Use it in `config/roles.json`:
+
+```json
+{
+  "servers": {
+    "01ABC123_YOUR_REAL_SERVER_ID": {
+      "reaction_roles": {},
+      "assignable_roles": ["Notifications", "Gamer"]
+    }
+  }
+}
+```
+
+Role names under `assignable_roles` must match the **exact** role names in your Stoat server (case-sensitive).
+
+---
+
+## 5. Optional: DEBUG when running on NAS
+
+To see incoming messages in the NAS container logs, add this env var when creating the container:
+- `DEBUG=1`
+
+Then in the logs you’ll see when the bot receives a message (and whether it’s treated as a command). Helps confirm if the bot gets events at all on the NAS.