cubyz-discord-relay 1.0.0

package/README.md

@@ -0,0 +1,61 @@
+# Cubyz Discord Relay
+
+CLI tool that streams Cubyz game server chat events into a Discord channel in near real time.
+
+## Features
+- Watches the Cubyz `latest.log` file without locking it
+- Detects join, leave, death, and chat events
+- Cleans Cubyz markdown-style usernames before relaying
+- Filters events based on configuration
+- Graceful shutdown via `q` + Enter or `Ctrl+C`
+
+## Prerequisites
+- Node.js 18 or newer
+- Discord bot token with permission to post in the target channel
+
+## Installation
+Install via npm:
+
+```bash
+npm install -g cubyz-discord-relay
+
+# Start the relay (defaults to ./config.json)
+cubyz-discord-relay
+
+# Provide a custom config path
+cubyz-discord-relay /path/to/config.json
+```
+
+You can also run once without a global install via `npx cubyz-discord-relay`.
+
+## Development
+
+### Setup
+```bash
+npm install
+```
+
+### Configuration
+1. Copy `config.example.json` to `config.json`.
+2. Update the fields:
+   - `cubyzLogPath`: absolute path to Cubyz `latest.log`
+   - `discord.token`: bot token
+   - `discord.channelId`: target channel ID
+   - `events`: event types to relay (`join`, `leave`, `death`, `chat`)
+   - `updateIntervalMs`: polling interval in milliseconds
+
+> First run convenience: if `config.json` is missing, the CLI writes a fresh template in your working directory and exits so you can fill it in before retrying.
+
+### Usage
+```bash
+npm run dev            # Run directly with tsx (recompiles on change)
+npm run build          # Compile TypeScript to dist/
+npm start              # Run compiled output (after build)
+```
+
+During execution press `q` + Enter to exit gracefully.
+
+## Troubleshooting
+- **Bot not posting**: verify bot token, channel ID, and permissions
+- **No events forwarded**: ensure `events` include the desired types and the log is updating
+- **Missing log file**: the tool waits for `cubyzLogPath` to appear and resumes automatically

package/config.example.json

@@ -0,0 +1,9 @@
+{
+	"cubyzLogPath": "/path/to/cubyz/logs/latest.log",
+	"discord": {
+		"token": "YOUR_DISCORD_BOT_TOKEN",
+		"channelId": "YOUR_CHANNEL_ID"
+	},
+	"events": ["join", "leave", "death", "chat"],
+	"updateIntervalMs": 1000
+}

package/dist/config.d.ts

@@ -0,0 +1,10 @@
+import type { Config, EventType } from "./types.js";
+declare const DEFAULT_EVENTS: EventType[];
+declare const DEFAULT_INTERVAL_MS = 1000;
+export declare class ConfigTemplateCreatedError extends Error {
+    readonly configPath: string;
+    constructor(configPath: string);
+}
+export declare function validateConfig(config: Config): void;
+export declare function loadConfig(configPath: string): Promise<Config>;
+export { DEFAULT_EVENTS, DEFAULT_INTERVAL_MS };

package/dist/config.js

@@ -0,0 +1,82 @@
+import { access, copyFile, mkdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+const DEFAULT_EVENTS = ["join", "leave", "death", "chat"];
+const DEFAULT_INTERVAL_MS = 1000;
+const CONFIG_TEMPLATE_PATH = fileURLToPath(new URL("../config.example.json", import.meta.url));
+const isNotFoundError = (error) => typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    error.code === "ENOENT";
+export class ConfigTemplateCreatedError extends Error {
+    configPath;
+    constructor(configPath) {
+        super(`Configuration file not found. A template has been created at ${configPath}. Update it and rerun the cli.`);
+        this.name = "ConfigTemplateCreatedError";
+        this.configPath = configPath;
+    }
+}
+function applyDefaults(partial) {
+    const events = Array.isArray(partial.events) && partial.events.length > 0
+        ? [...partial.events]
+        : DEFAULT_EVENTS;
+    return {
+        cubyzLogPath: partial.cubyzLogPath ?? "",
+        discord: {
+            token: partial.discord?.token ?? "",
+            channelId: partial.discord?.channelId ?? "",
+        },
+        events: events,
+        updateIntervalMs: typeof partial.updateIntervalMs === "number" &&
+            partial.updateIntervalMs > 0
+            ? Math.floor(partial.updateIntervalMs)
+            : DEFAULT_INTERVAL_MS,
+    };
+}
+async function ensureConfigFile(resolvedPath) {
+    try {
+        await access(resolvedPath);
+    }
+    catch (error) {
+        if (isNotFoundError(error)) {
+            await mkdir(path.dirname(resolvedPath), { recursive: true });
+            await copyFile(CONFIG_TEMPLATE_PATH, resolvedPath);
+            throw new ConfigTemplateCreatedError(resolvedPath);
+        }
+        throw error;
+    }
+}
+export function validateConfig(config) {
+    if (!config.cubyzLogPath || typeof config.cubyzLogPath !== "string") {
+        throw new Error('Configuration error: "cubyzLogPath" must be a non-empty string.');
+    }
+    if (!config.discord?.token || typeof config.discord.token !== "string") {
+        throw new Error('Configuration error: "discord.token" must be provided.');
+    }
+    if (!config.discord?.channelId ||
+        typeof config.discord.channelId !== "string") {
+        throw new Error('Configuration error: "discord.channelId" must be provided.');
+    }
+    if (!Array.isArray(config.events) || config.events.length === 0) {
+        throw new Error('Configuration error: "events" must include at least one supported event type.');
+    }
+    const unknownEvents = config.events.filter((event) => !DEFAULT_EVENTS.includes(event));
+    if (unknownEvents.length > 0) {
+        throw new Error(`Configuration error: unsupported event types: ${unknownEvents.join(", ")}.`);
+    }
+    if (typeof config.updateIntervalMs !== "number" ||
+        config.updateIntervalMs <= 0) {
+        throw new Error('Configuration error: "updateIntervalMs" must be a positive number.');
+    }
+}
+export async function loadConfig(configPath) {
+    const resolvedPath = path.resolve(process.cwd(), configPath);
+    await ensureConfigFile(resolvedPath);
+    const raw = await readFile(resolvedPath, "utf8");
+    const parsed = JSON.parse(raw);
+    const config = applyDefaults(parsed);
+    validateConfig(config);
+    return config;
+}
+export { DEFAULT_EVENTS, DEFAULT_INTERVAL_MS };

package/dist/discordClient.d.ts

@@ -0,0 +1,4 @@
+import { Client } from "discord.js";
+export declare function initializeDiscordClient(token: string): Promise<Client<boolean>>;
+export declare function sendMessage(channelId: string, message: string): Promise<void>;
+export declare function cleanup(): Promise<void>;

package/dist/discordClient.js

@@ -0,0 +1,63 @@
+import { Client, GatewayIntentBits } from "discord.js";
+const channelCache = new Map();
+let clientInstance = null;
+function ensureClient() {
+    if (!clientInstance) {
+        throw new Error("Discord client has not been initialized.");
+    }
+    return clientInstance;
+}
+function assertSendable(channel, channelId) {
+    if (typeof channel.send !== "function") {
+        throw new Error(`Channel ${channelId} cannot send messages.`);
+    }
+}
+async function getChannel(channelId) {
+    const client = ensureClient();
+    const cached = channelCache.get(channelId);
+    if (cached) {
+        return cached;
+    }
+    const channel = await client.channels.fetch(channelId);
+    if (!channel || !channel.isTextBased()) {
+        throw new Error(`Channel ${channelId} is not a text-based channel or could not be fetched.`);
+    }
+    assertSendable(channel, channelId);
+    channelCache.set(channelId, channel);
+    return channel;
+}
+export async function initializeDiscordClient(token) {
+    if (clientInstance) {
+        return clientInstance;
+    }
+    clientInstance = new Client({
+        intents: [GatewayIntentBits.Guilds],
+    });
+    await clientInstance.login(token);
+    return clientInstance;
+}
+export async function sendMessage(channelId, message) {
+    const channel = await getChannel(channelId);
+    const maxAttempts = 3;
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        try {
+            await channel.send(message);
+            return;
+        }
+        catch (error) {
+            if (attempt === maxAttempts) {
+                throw error;
+            }
+            const delay = 500 * attempt;
+            await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+    }
+}
+export async function cleanup() {
+    if (!clientInstance) {
+        return;
+    }
+    channelCache.clear();
+    await clientInstance.destroy();
+    clientInstance = null;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+import process from "node:process";
+import readline from "node:readline";
+import { ConfigTemplateCreatedError, loadConfig } from "./config.js";
+import { cleanup, initializeDiscordClient, sendMessage, } from "./discordClient.js";
+import { initializePosition, parseChatLine, readNewLines, } from "./logParser.js";
+import { formatMessage, shouldRelayEvent } from "./messageFormatter.js";
+const DEFAULT_CONFIG_PATH = "config.json";
+let isRunning = true;
+let isShuttingDown = false;
+let readlineInterface = null;
+const delay = (ms) => new Promise((resolve) => {
+    setTimeout(resolve, ms);
+});
+function getConfigPath() {
+    const [, , providedPath] = process.argv;
+    return providedPath ?? DEFAULT_CONFIG_PATH;
+}
+async function relayMessages(config, chatMessages) {
+    for (const chatMessage of chatMessages) {
+        if (!shouldRelayEvent(chatMessage.type, config)) {
+            continue;
+        }
+        const payload = formatMessage(chatMessage);
+        try {
+            await sendMessage(config.discord.channelId, payload);
+        }
+        catch (error) {
+            console.error("Failed to send message to Discord:", error);
+        }
+    }
+}
+async function pollLoop(config) {
+    let lastPosition = await initializePosition(config.cubyzLogPath);
+    let warnedMissingFile = false;
+    while (isRunning) {
+        try {
+            const previousPosition = lastPosition;
+            const { lines, newPosition, fileMissing } = await readNewLines(config.cubyzLogPath, lastPosition);
+            if (fileMissing && !warnedMissingFile) {
+                console.warn("Log file not found. Waiting for it to appear...");
+                warnedMissingFile = true;
+            }
+            if (!fileMissing && warnedMissingFile) {
+                console.info("Log file detected. Resuming monitoring.");
+                warnedMissingFile = false;
+                lastPosition = await initializePosition(config.cubyzLogPath);
+                await delay(config.updateIntervalMs);
+                continue;
+            }
+            if (!fileMissing && newPosition < previousPosition) {
+                console.info("Log file size decreased. Assuming rotation and continuing from new end.");
+            }
+            lastPosition = newPosition;
+            if (lines.length > 0) {
+                const messages = [];
+                for (const line of lines) {
+                    const chatMessage = parseChatLine(line);
+                    if (chatMessage) {
+                        messages.push(chatMessage);
+                    }
+                }
+                if (messages.length > 0) {
+                    await relayMessages(config, messages);
+                }
+            }
+        }
+        catch (error) {
+            console.error("Error while processing log file:", error);
+        }
+        await delay(config.updateIntervalMs);
+    }
+}
+async function shutdown() {
+    if (isShuttingDown) {
+        return;
+    }
+    isShuttingDown = true;
+    isRunning = false;
+    if (readlineInterface) {
+        readlineInterface.close();
+        readlineInterface = null;
+    }
+    try {
+        await cleanup();
+    }
+    catch (error) {
+        console.error("Error during cleanup:", error);
+    }
+}
+function setupQuitHandler() {
+    readlineInterface = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+        terminal: false,
+    });
+    readlineInterface.on("line", (input) => {
+        if (input.trim().toLowerCase() === "q") {
+            void shutdown();
+        }
+    });
+    process.on("SIGINT", () => {
+        console.log("\nReceived SIGINT. Shutting down...");
+        void shutdown();
+    });
+    console.log("Press q + Enter to quit.");
+}
+async function main() {
+    try {
+        const configPath = getConfigPath();
+        const config = await loadConfig(configPath);
+        console.log("Connecting to Discord...");
+        await initializeDiscordClient(config.discord.token);
+        console.log("Connected to Discord.");
+        setupQuitHandler();
+        console.log(`Monitoring log file: ${config.cubyzLogPath}`);
+        await pollLoop(config);
+    }
+    catch (error) {
+        if (error instanceof ConfigTemplateCreatedError) {
+            console.warn(error.message);
+            console.warn("Update the generated config file and run the command again.");
+            process.exitCode = 1;
+        }
+        else {
+            console.error("Fatal error:", error);
+            process.exitCode = 1;
+        }
+    }
+    finally {
+        await shutdown();
+    }
+}
+void main();

package/dist/logParser.d.ts

@@ -0,0 +1,8 @@
+import type { ChatMessage } from "./types.js";
+export declare function initializePosition(filePath: string): Promise<number>;
+export declare function readNewLines(filePath: string, fromPosition: number): Promise<{
+    lines: string[];
+    newPosition: number;
+    fileMissing: boolean;
+}>;
+export declare function parseChatLine(rawLine: string): ChatMessage | null;

package/dist/logParser.js

@@ -0,0 +1,103 @@
+import { Buffer } from "node:buffer";
+import { open, stat } from "node:fs/promises";
+import { cleanUsername } from "./messageFormatter.js";
+const CHAT_PATTERN = /\[info\]:\s*(?:User \[info\]:\s*)?Chat:\s*(.+)/i;
+const isNotFoundError = (error) => typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    error.code === "ENOENT";
+export async function initializePosition(filePath) {
+    try {
+        const fileStats = await stat(filePath);
+        return fileStats.size;
+    }
+    catch (error) {
+        if (isNotFoundError(error)) {
+            return 0;
+        }
+        throw error;
+    }
+}
+export async function readNewLines(filePath, fromPosition) {
+    try {
+        const fileHandle = await open(filePath, "r");
+        const fileStats = await fileHandle.stat();
+        if (fileStats.size < fromPosition) {
+            await fileHandle.close();
+            return { lines: [], newPosition: fileStats.size, fileMissing: false };
+        }
+        if (fileStats.size === fromPosition) {
+            await fileHandle.close();
+            return { lines: [], newPosition: fromPosition, fileMissing: false };
+        }
+        const bytesToRead = fileStats.size - fromPosition;
+        const buffer = Buffer.alloc(bytesToRead);
+        await fileHandle.read(buffer, 0, bytesToRead, fromPosition);
+        await fileHandle.close();
+        const content = buffer.toString("utf8");
+        const normalized = content.replace(/\r\n/g, "\n");
+        const lines = normalized
+            .split("\n")
+            .filter((line) => line.length > 0);
+        return { lines, newPosition: fileStats.size, fileMissing: false };
+    }
+    catch (error) {
+        if (isNotFoundError(error)) {
+            return { lines: [], newPosition: 0, fileMissing: true };
+        }
+        throw error;
+    }
+}
+export function parseChatLine(rawLine) {
+    const match = CHAT_PATTERN.exec(rawLine);
+    if (!match) {
+        return null;
+    }
+    const payload = match[1].trim();
+    const timestamp = new Date();
+    const chatMatch = /^\[(.+?)\]\s*(.*)$/.exec(payload);
+    if (chatMatch) {
+        const rawUsername = chatMatch[1].trim();
+        const message = chatMatch[2].trim();
+        return {
+            type: "chat",
+            rawUsername,
+            username: cleanUsername(rawUsername),
+            message,
+            timestamp,
+        };
+    }
+    const joinMatch = /^(.+?) joined$/.exec(payload);
+    if (joinMatch) {
+        const rawUsername = joinMatch[1].trim();
+        return {
+            type: "join",
+            rawUsername,
+            username: cleanUsername(rawUsername),
+            timestamp,
+        };
+    }
+    const leaveMatch = /^(.+?) left$/.exec(payload);
+    if (leaveMatch) {
+        const rawUsername = leaveMatch[1].trim();
+        return {
+            type: "leave",
+            rawUsername,
+            username: cleanUsername(rawUsername),
+            timestamp,
+        };
+    }
+    const deathMatch = /^(.+?) died(.*)$/.exec(payload);
+    if (deathMatch) {
+        const rawUsername = deathMatch[1].trim();
+        const message = `died${deathMatch[2]}`.trim();
+        return {
+            type: "death",
+            rawUsername,
+            username: cleanUsername(rawUsername),
+            message,
+            timestamp,
+        };
+    }
+    return null;
+}

package/dist/messageFormatter.d.ts

@@ -0,0 +1,5 @@
+import type { ChatMessage, Config, EventType } from "./types.js";
+export declare function isFormattedUsername(username: string): boolean;
+export declare function cleanUsername(raw: string): string;
+export declare function formatMessage(chatMessage: ChatMessage): string;
+export declare function shouldRelayEvent(eventType: EventType, config: Config): boolean;

package/dist/messageFormatter.js

@@ -0,0 +1,36 @@
+const FORMATTED_USERNAME_PATTERN = /(?:\*+|_+|~+)(?:#[0-9A-Fa-f]{6}.)+(?:\*+|_+|~+)(?:§#[0-9A-Fa-f]{6})?/;
+export function isFormattedUsername(username) {
+    return FORMATTED_USERNAME_PATTERN.test(username);
+}
+export function cleanUsername(raw) {
+    const withoutSuffix = raw.replace(/§#[0-9A-Fa-f]{6}$/g, "");
+    const colorCharMatches = [
+        ...withoutSuffix.matchAll(/#[0-9A-Fa-f]{6}([A-Za-z0-9_])/g),
+    ];
+    if (colorCharMatches.length > 0) {
+        return colorCharMatches.map((match) => match[1]).join("");
+    }
+    const stripped = withoutSuffix
+        .replace(/[*~_[\]]/g, "")
+        .replace(/#[0-9A-Fa-f]{6}/g, "")
+        .trim();
+    return stripped;
+}
+export function formatMessage(chatMessage) {
+    const username = chatMessage.username || cleanUsername(chatMessage.rawUsername);
+    switch (chatMessage.type) {
+        case "join":
+            return `👋 ${username} joined the game`;
+        case "leave":
+            return `👋 ${username} left the game`;
+        case "death":
+            return `💀 ${username} ${chatMessage.message ?? "died"}`;
+        case "chat":
+            return `${username}: ${chatMessage.message ?? ""}`;
+        default:
+            return `${username}: ${chatMessage.message ?? ""}`;
+    }
+}
+export function shouldRelayEvent(eventType, config) {
+    return config.events.includes(eventType);
+}

package/dist/types.d.ts

@@ -0,0 +1,17 @@
+export type EventType = "join" | "leave" | "death" | "chat";
+export interface Config {
+    cubyzLogPath: string;
+    discord: {
+        token: string;
+        channelId: string;
+    };
+    events: EventType[];
+    updateIntervalMs: number;
+}
+export interface ChatMessage {
+    type: EventType;
+    username: string;
+    rawUsername: string;
+    message?: string;
+    timestamp: Date;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,43 @@
+{
+	"name": "cubyz-discord-relay",
+	"version": "1.0.0",
+	"description": "CLI tool that relays Cubyz server chat events to Discord in real time.",
+	"type": "module",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"bin": {
+		"cubyz-discord-relay": "dist/index.js"
+	},
+	"scripts": {
+		"check": "biome check .",
+		"check:write": "biome check --write .",
+		"build": "tsc",
+		"start": "node dist/index.js",
+		"dev": "tsx src/index.ts",
+		"watch": "tsc --watch",
+		"test": "tsx test/messageFormatter.test.ts",
+		"prepublishOnly": "npm run build"
+	},
+	"keywords": [
+		"cubyz",
+		"discord",
+		"relay",
+		"cli"
+	],
+	"author": "",
+	"license": "MIT",
+	"files": [
+		"dist",
+		"config.example.json",
+		"README.md"
+	],
+	"dependencies": {
+		"discord.js": "^14.14.1"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.2.6",
+		"@types/node": "^20.10.0",
+		"tsx": "^4.7.0",
+		"typescript": "^5.3.0"
+	}
+}