lcluster 1.0.0

package/README.md

@@ -0,0 +1,173 @@
+<div align="center">
+  <img src="docs/public/logo.svg" height="80" alt="lcluster logo" />
+  <h1>lcluster</h1>
+  <p>A powerful Lavalink cluster manager for your terminal.</p>
+
+  <p>
+    <img src="https://img.shields.io/badge/version-1.0.0-blue" />
+    <img src="https://img.shields.io/badge/node-%3E%3D18.0.0-green" />
+    <img src="https://img.shields.io/badge/license-GPLv3-purple" />
+    <img src="https://img.shields.io/badge/built%20with-Claude%20AI-orange" />
+  </p>
+</div>
+
+---
+
+## What is lcluster
+
+**lcluster** is a terminal-based Lavalink cluster manager built for developers and server administrators. Run multiple Lavalink nodes — via Docker or Java process — and manage them all natively from one beautiful, fully-responsive, full-screen TUI dashboard.
+
+Your Discord bot connects to one single gateway address. **lcluster** powerfully handles all routing, load balancing, session tracking, and seamless failover behind the scenes. Your bot never knows there is a cluster, it just sees one highly available, extremely robust Lavalink node.
+
+---
+
+## Features
+
+- 🖥️ **Full-Screen Terminal Dashboard**: Native visual management built on top of modern React/Ink.
+- ⬡ **Single Gateway Endpoint**: Connect your bot to one port, let lcluster handle the rest.
+- 🐋 **Multi-Environment Spawning**: Natively spins up Docker containers or standalone Java processes.
+- 🔌 **External Node Auto-Connect**: Bring your own existing Lavalink node and monitor it seamlessly.
+- 🔀 **Intelligent Load Balancing**: Chooses nodes based on `least players`, `lowest CPU`, or `round robin`.
+- ♻️ **Automatic Failover & Migration**: Seamless session migration if a node crashes.
+- 🔔 **Discord Webhook Alerts**: Real-time integration and monitoring piped directly to your Discord channel.
+- 🖥️ **Systemd Auto-Start**: Built-in Ubuntu/Linux daemon installation.
+- 🎨 **Adaptive Themes**: 3 gorgeous built-in TUI themes — Cyberpunk Neon, Clean Minimal, and Retro Amber.
+- ⚡ **Extremely Lightweight**: Tiny memory footprint natively optimizing underlying resources.
+
+---
+
+## Requirements
+
+- Node.js 18 or higher
+- Java 17 or higher (for process mode nodes)
+- Docker (optional, for Docker mode nodes)
+
+---
+
+## Installation
+
+```bash
+npm install -g lcluster
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/yourname/lcluster.git
+cd lcluster
+npm install
+npm link
+```
+
+---
+
+## Quick Start
+
+```bash
+# Run the setup wizard
+lcluster init
+
+# Open the dashboard
+lcluster
+```
+
+---
+
+## CLI Commands
+
+| Command | Description |
+|---|---|
+| `lcluster` | Open the TUI dashboard |
+| `lcluster init` | Run the setup wizard |
+| `lcluster ps` | List all nodes in terminal |
+| `lcluster start <name>` | Start a node |
+| `lcluster stop <name>` | Stop a node |
+| `lcluster restart <name>` | Restart a node |
+| `lcluster logs <name>` | Tail logs for a node |
+
+---
+
+## Connecting Your Bot
+
+Point your Lavalink client at lcluster instead of a raw Lavalink node.
+No changes needed in your bot code — lcluster speaks standard Lavalink v4.
+
+```js
+// Riffy example
+const nodes = [{
+  host: "localhost",
+  port: 2333,          // your lcluster gateway port
+  password: "yourpassword",
+  secure: false
+}]
+```
+
+Works with Riffy, Shoukaku, Moonlink, Vulkava, and any other
+Lavalink v4 compatible client.
+
+---
+
+## TUI Dashboard Layout
+
+```
+╔═════════════════════════════════════════════════════════════════════╗
+║  ⬡ lcluster v1.0.0    ● 2 online  ⚠ 1 warn    gateway :2333  ●   ║
+╚═════════════════════════════════════════════════════════════════════╝
+
+  ┌─ nodes (3/5) ──────────────────────────────────── [↑↓ scroll] ─┐
+  │                                                                  │
+  │    ●  node-main                              ↑ 2d 4h 12m        │
+  │       default.yml  ·  process                ● online           │
+  │       ♪ 12   ⚡ 18ms   CPU ▓▓░░░░░░ 34%   MEM ▓▓░░░░░░ 29%    │
+  │                                                                  │
+  │ ▶  ●  node-docker                            ↑ 6h 12m           │
+  │       high-mem.yml  ·  docker 🐋             ● online           │
+  │       ♪ 7    ⚡ 22ms   CPU ▓▓▓▓░░░░ 58%   MEM ▓▓▓▓▓░░░ 71%    │
+  │                                                                  │
+  │    ⚠  node-backup                            ↑ 1d 2h            │
+  │       minimal.yml  ·  process                ⚠ degraded         │
+  │       ♪ 0    ⚡ 140ms  CPU ▓░░░░░░░ 12%   MEM ▓░░░░░░░ 18%    │
+  │                                                                  │
+  └──────────────────────────────────────────────────────────────────┘
+
+  [↑↓] navigate  [enter] manage  [n] new  [t] templates  [q] quit
+```
+
+---
+
+## Configuration
+
+All local data, nodes, templates, and configurations are securely stored within `~/.lcluster/`:
+
+- `~/.lcluster/config.yml`: Global settings, themes, alerts, and gateway credentials.
+- `~/.lcluster/nodes.json`: Node registry mapping.
+- `~/.lcluster/templates/`: Local customized `application.yml` configs for dynamic deployment.
+- `~/.lcluster/nodes/`: Operating directory holding the `Lavalink.jar` and `application.yml` for process nodes.
+
+---
+
+## Documentation
+
+Full architectural guides, TUI maps, setup instructions, and deployment strategies are absolutely free and publicly available at: 
+
+🔗 **[https://lcluster.dev](https://lcluster.dev)**
+
+---
+
+## Roadmap
+
+- [x] v1.0.0 — Core cluster manager, TUI dashboard, gateway, alerts
+- [ ] v1.0.1 — Custom Discord bot integration with token support
+
+---
+
+## Credits
+
+lcluster was designed and built by **Ram Krishna** with architecture,
+planning, and code assistance from **Claude**, an AI built by Anthropic.
+
+---
+
+## License
+
+GPL-3.0

package/built-in-templates/default.yml

@@ -0,0 +1,14 @@
+server:
+  port: 2334
+  address: 0.0.0.0
+lavalink:
+  server:
+    password: "youshallnotpass"
+    sources:
+      youtube: true
+      bandcamp: false
+      soundcloud: true
+      twitch: false
+      vimeo: false
+      http: true
+      local: false

package/built-in-templates/high-memory.yml

@@ -0,0 +1,14 @@
+server:
+  port: 2335
+  address: 0.0.0.0
+lavalink:
+  server:
+    password: "youshallnotpass"
+    sources:
+      youtube: true
+      bandcamp: true
+      soundcloud: true
+      twitch: true
+      vimeo: true
+      http: true
+      local: true

package/built-in-templates/minimal.yml

@@ -0,0 +1,14 @@
+server:
+  port: 2336
+  address: 0.0.0.0
+lavalink:
+  server:
+    password: "youshallnotpass"
+    sources:
+      youtube: true
+      bandcamp: false
+      soundcloud: false
+      twitch: false
+      vimeo: false
+      http: false
+      local: false

package/generate_logos.js

@@ -0,0 +1,39 @@
+import fs from 'node:fs';
+
+const renderSvg = (bgColor, fgColor, isLight = false) => `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 130" width="200" height="260">
+  <rect width="100" height="130" fill="${bgColor}" />
+  <!-- Verbindungen -->
+  <line x1="50" y1="50" x2="50" y2="15" stroke="${fgColor}" stroke-width="2" />
+  <line x1="50" y1="50" x2="19.69" y2="67.5" stroke="${fgColor}" stroke-width="2" />
+  <line x1="50" y1="50" x2="80.31" y2="67.5" stroke="${fgColor}" stroke-width="2" />
+  
+  <!-- Zentrales Hexagon -->
+  <polygon points="50,30 67.32,40 67.32,60 50,70 32.68,60 32.68,40" fill="${bgColor}" stroke="${fgColor}" stroke-width="3" />
+  
+  <!-- Nodes / Außenpunkte -->
+  <circle cx="50" cy="15" r="5" fill="${fgColor}" />
+  <circle cx="19.69" cy="67.5" r="5" fill="${fgColor}" />
+  <circle cx="80.31" cy="67.5" r="5" fill="${fgColor}" />
+  
+  <!-- Text -->
+  <text x="50" y="115" font-family="monospace" font-size="20" font-weight="bold" fill="${fgColor}" text-anchor="middle">lcluster</text>
+</svg>`;
+
+// We will use Neon theme as default/logo.svg since the prompt mentioned tracking Neon as primary hue
+// Neon version: #00ff9f on #080b14
+const neonSvg = renderSvg('#080b14', '#00ff9f');
+const lightSvg = renderSvg('#ffffff', '#000000', true);
+const darkSvg = renderSvg('#000000', '#ffffff');
+
+fs.writeFileSync('docs/public/logo.svg', neonSvg);
+fs.writeFileSync('docs/public/logo-dark.svg', darkSvg);
+fs.writeFileSync('docs/public/logo-light.svg', lightSvg);
+
+// Also save minimal and amber just to have them available, though prompt says output formats needed: logo.svg, logo-dark.svg, logo-light.svg
+const minimalSvg = renderSvg('#1e1e2e', '#cba6f7');
+const amberSvg = renderSvg('#0d0800', '#ffb347');
+fs.writeFileSync('docs/public/logo-minimal.svg', minimalSvg);
+fs.writeFileSync('docs/public/logo-amber.svg', amberSvg);
+fs.writeFileSync('docs/public/favicon.ico', neonSvg); // Many modern browsers accept SVGs as ICO internally, but we'll try to use a png to ico if needed. For now, writing it this way is simple.
+
+console.log("Logos generated.");

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "lcluster",
+  "version": "1.0.0",
+  "description": "A powerful Lavalink cluster manager for your terminal",
+  "main": "src/cli.js",
+  "type": "module",
+  "bin": {
+    "lcluster": "./src/cli.js"
+  },
+  "scripts": {
+    "start": "node src/cli.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "lavalink",
+    "cluster",
+    "discord",
+    "music bot",
+    "tui",
+    "terminal"
+  ],
+  "author": "Ram Krishna",
+  "license": "GPL-3.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ramkrishna-js/lcluster.git"
+  },
+  "homepage": "https://lcluster.dev",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "dockerode": "^4.0.2",
+    "http-proxy": "^1.18.1",
+    "ink": "^4.4.1",
+    "ink-text-input": "^5.0.1",
+    "js-yaml": "^4.1.0",
+    "node-fetch": "^3.3.2",
+    "node-notifier": "^10.0.1",
+    "ora": "^8.0.1",
+    "react": "^18.2.0",
+    "tsx": "^4.21.0",
+    "ws": "^8.16.0"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.24.0",
+    "@babel/preset-env": "^7.24.0",
+    "@babel/preset-react": "^7.23.3",
+    "@babel/register": "^7.23.7"
+  }
+}

package/src/alerts/desktop.js

@@ -0,0 +1,15 @@
+import notifier from 'node-notifier';
+
+export function sendDesktop(level, message) {
+    // Only fire for danger and success per spec
+    if (level !== 'danger' && level !== 'success') {
+        return;
+    }
+
+    notifier.notify({
+        title: 'lcluster',
+        message: message,
+        icon: '', // path to logo if available
+        sound: false
+    });
+}

package/src/alerts/discord.js

@@ -0,0 +1,53 @@
+import fetch from 'node-fetch';
+import { events } from '../core/events.js';
+
+export async function sendDiscord(level, node, message, webhookUrl) {
+    if (!webhookUrl) return;
+
+    let colorByLevel = 0x89B4FA; // info blue
+    let title = 'ℹ️ lcluster Info';
+
+    if (level === 'danger') {
+        colorByLevel = 0xFF3366;
+        title = '🔴 Node Offline';
+    } else if (level === 'warning') {
+        colorByLevel = 0xFFCC00;
+        title = '🟡 Node Warning';
+    } else if (level === 'success') {
+        colorByLevel = 0x00FF9F;
+        title = '🟢 Node Online';
+    }
+
+    const payload = {
+        embeds: [{
+            title,
+            description: message,
+            color: colorByLevel,
+            fields: node ? [
+                { name: 'Node', value: node.name, inline: true },
+                { name: 'Mode', value: node.mode, inline: true },
+                { name: 'Uptime', value: node.uptime || '—', inline: true },
+                { name: 'Players', value: String(node.players || 0), inline: true },
+                { name: 'Ping', value: (node.ping || 0) + 'ms', inline: true },
+                { name: 'CPU', value: (node.cpu || 0) + '%', inline: true },
+            ] : [],
+            footer: {
+                text: 'lcluster · Built by Ram Krishna & Claude (Anthropic AI)'
+            },
+            timestamp: new Date().toISOString()
+        }]
+    };
+
+    try {
+        const res = await fetch(webhookUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(payload)
+        });
+        if (!res.ok) {
+            events.emit('alert:failed', `Discord webhook failed: ${res.status}`);
+        }
+    } catch (err) {
+        events.emit('alert:failed', `Discord webhook error: ${err.message}`);
+    }
+}

package/src/alerts/index.js

@@ -0,0 +1,50 @@
+import { sendDiscord } from './discord.js';
+import { sendDesktop } from './desktop.js';
+import { sendSound } from './sound.js';
+import { events } from '../core/events.js';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import yaml from 'js-yaml';
+
+function getConfig() {
+    const configPath = path.join(os.homedir(), '.lcluster', 'config.yml');
+    if (fs.existsSync(configPath)) {
+        try { return yaml.load(fs.readFileSync(configPath, 'utf8')) || {}; } catch (e) { }
+    }
+    return {};
+}
+
+function getAlertConfig() {
+    const cfg = getConfig();
+    return cfg.alerts || {
+        discord: { enabled: false, webhook: '' },
+        desktop: { enabled: false },
+        sound: { enabled: false },
+        thresholds: { cpu_warn: 90, idle_warn: false }
+    };
+}
+
+export function alert(level, node, message) {
+    const alertsConfig = getAlertConfig();
+
+    if (alertsConfig.discord?.enabled && alertsConfig.discord?.webhook) {
+        sendDiscord(level, node, message, alertsConfig.discord.webhook);
+    }
+
+    if (alertsConfig.desktop?.enabled) {
+        sendDesktop(level, message);
+    }
+
+    if (alertsConfig.sound?.enabled) {
+        sendSound(level);
+    }
+}
+
+export function initAlerts() {
+    events.on('node:offline', (node) => alert('danger', node, 'went offline'));
+    events.on('node:online', (node) => alert('success', node, 'is back online'));
+    events.on('node:degraded', (node) => alert('warning', node, 'is degraded'));
+    events.on('gateway:ready', () => alert('info', null, 'gateway started'));
+    events.on('cpu:critical', (node) => alert('warning', node, 'CPU above threshold'));
+}

package/src/alerts/sound.js

@@ -0,0 +1,5 @@
+export function sendSound(level) {
+    if (level === 'danger') {
+        process.stdout.write('\x07');
+    }
+}

package/src/cli.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+if (!process.env.LCLUSTER_TSX_BOOTSTRAPPED) {
+  process.env.LCLUSTER_TSX_BOOTSTRAPPED = '1';
+  const __filename = fileURLToPath(import.meta.url);
+
+  const result = spawnSync(process.execPath, [
+    '--no-warnings',
+    '--import',
+    'tsx',
+    __filename,
+    ...process.argv.slice(2)
+  ], {
+    stdio: 'inherit'
+  });
+
+  process.exit(result.status ?? 0);
+}
+
+// Now we can safely import everything else because tsx loader is active
+const { runCLI } = await import('./main.js');
+await runCLI();

package/src/core/config.js

@@ -0,0 +1,17 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import yaml from 'js-yaml';
+
+export function getGatewayConfig() {
+    const configPath = path.join(os.homedir(), '.lcluster', 'config.yml');
+    if (!fs.existsSync(configPath)) {
+        return { port: 2333, password: 'youshallnotpass' };
+    }
+    try {
+        const doc = yaml.load(fs.readFileSync(configPath, 'utf8'));
+        return doc?.gateway || { port: 2333, password: 'youshallnotpass' };
+    } catch {
+        return { port: 2333, password: 'youshallnotpass' };
+    }
+}

package/src/core/events.js

@@ -0,0 +1,5 @@
+import { EventEmitter } from 'events';
+
+class ClusterEmitter extends EventEmitter { }
+
+export const events = new ClusterEmitter();

package/src/core/healthcheck.js

@@ -0,0 +1,126 @@
+import fetch from 'node-fetch';
+import { events } from './events.js';
+import { getAllNodes, updateNode } from './registry.js';
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import yaml from 'js-yaml';
+
+const failCounters = new Map();
+const pingHistories = new Map(); // Add Ping history arrays
+const NODE_TIMEOUT_MS = 3000;
+
+function getConfig() {
+    const configPath = path.join(os.homedir(), '.lcluster', 'config.yml');
+    if (fs.existsSync(configPath)) {
+        try { return yaml.load(fs.readFileSync(configPath, 'utf8')) || {}; } catch (e) { }
+    }
+    return {};
+}
+
+export function startHealthCheck() {
+    setInterval(async () => {
+        const nodes = getAllNodes();
+        for (const node of nodes) {
+            checkNode(node);
+        }
+    }, 5000);
+}
+
+async function checkNode(node) {
+    const start = Date.now();
+    let failCount = failCounters.get(node.name) || 0;
+
+    try {
+        const res = await fetch(`http://localhost:${node.port}/v4/stats`, {
+            method: 'GET',
+            headers: {
+                'Authorization': node.password || 'youshallnotpass',
+                'Content-Type': 'application/json'
+            },
+            timeout: NODE_TIMEOUT_MS
+        });
+
+        if (res.ok) {
+            const ping = Date.now() - start;
+            const stats = await res.json();
+
+            const wasOffline = node.status !== 'online'; // anything not online should trigger recovery
+
+            failCounters.set(node.name, 0);
+
+            // Track ping history
+            if (!pingHistories.has(node.name)) pingHistories.set(node.name, []);
+            const hist = pingHistories.get(node.name);
+            hist.push(ping);
+            if (hist.length > 10) hist.shift();
+
+            const cpu = stats.cpu ? Math.round(stats.cpu.lavalinkLoad * 100) : 0;
+            const memory = stats.memory ? Math.round(stats.memory.used / 1024 / 1024) : 0;
+            const players = stats.players || 0;
+
+            updateNode(node.name, {
+                status: 'online',
+                ping,
+                cpu,
+                memory,
+                players,
+                pingHistory: [...pingHistories.get(node.name)]
+            });
+
+            const config = getConfig();
+            const cpuWarnThreshold = config.alerts?.thresholds?.cpu_warn || 90;
+
+            if (cpu >= cpuWarnThreshold) {
+                if (node.cpuWarnCount >= 2) {
+                    events.emit('cpu:critical', node);
+                    node.cpuWarnCount = 0;
+                } else {
+                    node.cpuWarnCount = (node.cpuWarnCount || 0) + 1;
+                }
+            } else {
+                node.cpuWarnCount = 0;
+            }
+
+            if (wasOffline) {
+                events.emit('node:online', node.name);
+            }
+        } else {
+            throw new Error(`HTTP ${res.status}`);
+        }
+    } catch (error) {
+        failCount++;
+        failCounters.set(node.name, failCount);
+
+        let newStatus = node.status || 'offline';
+        let eventToEmit = null;
+
+        if (node.mode === 'external') {
+            if (failCount >= 12 && newStatus !== 'unreachable') {
+                newStatus = 'unreachable';
+            } else if (failCount > 0 && failCount < 12) {
+                if (newStatus === 'online' || newStatus === 'reconnecting') {
+                    newStatus = 'reconnecting';
+                } else if (newStatus !== 'unreachable') {
+                    newStatus = 'waiting';
+                }
+            }
+        } else {
+            if (failCount >= 6 && newStatus !== 'offline') {
+                newStatus = 'offline';
+                eventToEmit = 'node:offline';
+            } else if (failCount >= 3 && failCount < 6 && newStatus !== 'degraded') {
+                newStatus = 'degraded';
+            }
+        }
+
+        if (newStatus !== node.status) {
+            updateNode(node.name, { status: newStatus });
+            if (eventToEmit) events.emit(eventToEmit, node.name);
+        }
+    }
+
+    // After each check emit updated
+    events.emit('node:updated', node.name);
+}

package/src/core/loadbalancer.js

@@ -0,0 +1,26 @@
+import { getAllNodes } from './registry.js';
+
+let rrIndex = 0;
+
+export function pickNode(strategy = 'least-players') {
+    const onlineNodes = getAllNodes().filter(n => n.status === 'online');
+
+    if (onlineNodes.length === 0) {
+        throw new Error('No online nodes available');
+    }
+
+    if (strategy === 'least-players') {
+        return onlineNodes.reduce((min, node) => (node.players < min.players ? node : min), onlineNodes[0]);
+    }
+
+    if (strategy === 'lowest-cpu') {
+        return onlineNodes.reduce((min, node) => (node.cpu < min.cpu ? node : min), onlineNodes[0]);
+    }
+
+    if (strategy === 'round-robin') {
+        rrIndex = (rrIndex + 1) % onlineNodes.length;
+        return onlineNodes[rrIndex];
+    }
+
+    return onlineNodes[0];
+}

package/src/core/logBuffer.js

@@ -0,0 +1,35 @@
+import { events } from './events.js';
+
+const buffers = new Map();
+const MAX_LINES = 200;
+
+export function initLogBuffer() {
+    events.on('node:online', (name) => addLog(name, `[lcluster] Node ${name} is online`));
+    events.on('node:offline', (name) => addLog(name, `[lcluster] Node ${name} is offline`));
+
+    // We need a catch-all for logs or we bind dynamically
+    // For simplicity, we can intercept all emit calls, but events.js is standard EventEmitter.
+    const originalEmit = events.emit;
+    events.emit = function (event, ...args) {
+        if (event.startsWith('log:')) {
+            const nodeName = event.slice(4);
+            addLog(nodeName, args[0]);
+        }
+        return originalEmit.apply(this, [event, ...args]);
+    };
+}
+
+function addLog(nodeName, line) {
+    if (!buffers.has(nodeName)) {
+        buffers.set(nodeName, []);
+    }
+    const b = buffers.get(nodeName);
+    b.push(line);
+    if (b.length > MAX_LINES) {
+        b.shift();
+    }
+}
+
+export function getLogs(nodeName) {
+    return buffers.get(nodeName) || [];
+}