Jay

Customizable XMPP bot

Dependencies

• CMake ≥ 4.1
• Ninja (for the presets below)
• pkg-config
• gloox
• yaml-cpp
• libuuid
• libresolv (glibc; optional on libcs that provide res_query in libc)
• GoogleTest (only when JAY_ENABLE_TEST=ON)
• gcovr (optional; for the coverage preset / report task)

CI

Forgejo Actions (.forgejo/workflows/). The toolchain image is built via the shared blue/ci reusable workflow: tag = md5(Containerfile + ISO week), rebuild only when that tag is missing in the registry. Secrets DOCKER_HUB_USERNAME / DOCKER_HUB_PASSWORD must be set on the repo (or org). The shared blue/ci repo must be public.

Building

Configure/build trees are out-of-source and one directory per preset (e.g. gcc-build-debug/). That keeps compiler, build type, and JAY_ENABLE_TEST from fighting over a single CMake cache. A plain build/ directory still works if you prefer manual cmake -S . -B build ….

List presets:

cmake --list-presets
cmake --build --list-presets
ctest --list-presets

Examples:

cmake --preset gcc-debug              # GCC Debug + tests  → gcc-build-debug/
cmake --build --preset build-gcc-debug
ctest --preset test-gcc-debug

cmake --preset gcc-coverage           # same + --coverage → gcc-build-coverage/
cmake --build --preset build-gcc-coverage
ctest --preset test-gcc-coverage
gcovr --root . --filter src/ --exclude test/ --exclude-unreachable-branches \
  --gcov-ignore-parse-errors=negative_hits.warn_once_per_file \
  --print-summary \
  --txt gcc-build-coverage/coverage.txt \
  --html-details gcc-build-coverage/coverage.html \
  gcc-build-coverage

cmake --preset gcc-debug-notest       # GCC Debug, no tests
cmake --preset gcc-release            # GCC Release
cmake --preset clang-debug            # Clang Debug + tests + clang-tidy

One-off overrides (same binary dir — rewrites that cache):

cmake --preset gcc-debug -DJAY_ENABLE_ASAN=ON

For a lasting combo that isn’t in the file, either add a preset with inherits, or use a dedicated -B dir. Docs: https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html

cmake --preset gcc-debug
cp example.config.yml gcc-build-debug/config.yml
# edit gcc-build-debug/config.yml as you please
cmake --build --preset build-gcc-debug
./gcc-build-debug/src/jay ./gcc-build-debug/config.yml

Commands

All commands start with / followed by the module alias:

/actor list
/publish dialog
/chat join room@conference.example.org

In a MUC, address the bot first with its room nickname:

BotNick: /actor list

The bot replies in the room mentioning you back (YourNick: …). Whispers to the bot are answered as whispers. Messages that are not commands (no leading /) are ignored for now, except while a module dialog is active (cancel or /cancel aborts it).

Unknown / commands always get a reply (unhandled / forbidden / …) in both 1:1 and MUC.

Modules

Actor

This module is designed to manage access to Bot.

Commands:

• /actor list: lists all known actors
• /actor set actor group: assigns a group to an actor. default is a special actor name, group from it is assigned to all new actors, not listed in actors section of config

Publish

This module enables bot to publish to PubSub nodes

Commands:

• /publish to node@service title\narticle: Publishes article to the node of the service
• /publish dialog: opens an interactive dialog to do the same thing command to does

Chat

Joins and leaves multi-user chats. Room membership is stored under the module’s rooms section in the main config (runtime changes rewrite the file). On connect the bot joins exactly those rooms from a clean local state.

Default nickname is the bot login (localpart of jid) when nick is omitted.

When a MUC does not expose an occupant’s real JID, that user is treated as actors.default and a warning is logged.

Commands:

• /chat join room@conference… [nick]: join and persist the room
• /chat leave [room@conference…]: leave and remove from config (room optional in a MUC — leaves the current room)
• /chat list: list configured rooms

Optional replies.join / replies.leave lists announce in the room after joining / before leaving (omit or empty to stay silent).

Permission: manage

Notes

• 1:1 replies lock onto the peer’s full JID after they speak (RFC 6121 §5.1).
• / text commands are a Jay convention; XEP-0050 Ad-Hoc Commands are not used yet.
• Disco identity is client / bot.