creepercli 1.0.0

package/README.md

@@ -0,0 +1,117 @@
+# CreeperCLI (`creepercli`)
+
+> Remote Administration CLI for Minecraft (Paper / Spigot) Servers
+
+[![npm version](https://img.shields.io/npm/v/creepercli.svg)](https://www.npmjs.com/package/creepercli)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![Discord](https://img.shields.io/badge/chat-Discord-5865F2.svg)](https://discord.com/invite/zCkE44hsBR)
+
+**CreeperCLI** is a zero-dependency, ultra-fast Node.js command-line interface for managing Paper and Spigot Minecraft servers remotely. It pairs with the official **CreeperCLI Paper Plugin** to deliver hardened TCP remote control, real-time log streaming, live performance metrics, and sandboxed file management.
+
+---
+
+## ⚡ Quick Start
+
+### Installation
+
+Install globally via `npm`:
+
+```bash
+npm install -g creepercli
+```
+
+Or run instantly without installing using `npx`:
+
+```bash
+npx creepercli login --host <your-server-ip> --port <your-port>
+```
+
+---
+
+## 🚀 Usage Guide
+
+### 1. Authenticate & Launch REPL
+
+Log in to your Minecraft server and automatically enter the interactive REPL shell:
+
+```bash
+creepercli login --host 89.106.64.70 --port 30087
+```
+
+You will be prompted for your username and password. On successful authentication, CreeperCLI drops into an interactive shell:
+
+```text
+Authenticated as admin. Session valid for 15 minutes.
+Entering interactive REPL shell (type "help" for commands, "exit" or "q" to quit)...
+
+admin@89.106.64.70:/> 
+```
+
+### 2. Interactive REPL Shell
+
+Inside the REPL, commands are typed directly without `creepercli` prefixes:
+
+```text
+admin@89.106.64.70:/> stats
+Uptime:       1d 4h 12m
+CPU load:     0.15   process: 1.0%
+Memory heap:  494.1M / 680.0M (max 8.0G)
+Disk (root):  40.3G / 192.7G (usable 152.4G)
+Java:         25.0.3 (2 cores)
+
+admin@89.106.64.70:/> tps
+TPS: 1m 20.0 | 5m 20.0 | 15m 20.0  [████████████████████]  tick 50ms
+
+admin@89.106.64.70:/> ls /plugins
+banned-ips.json  bukkit.yml  config/  logs/  plugins/  server.properties
+
+admin@89.106.64.70:/> cd plugins
+Changed directory to /plugins
+
+admin@89.106.64.70:/plugins> q
+```
+
+---
+
+## 🛠️ Complete CLI Command Reference
+
+| Command | Usage | Description |
+|---|---|---|
+| `login` | `creepercli login [--host H] [--port P]` | Log in and auto-launch the interactive REPL shell |
+| `logout` | `creepercli logout` | Invalidate active session and clear local credentials |
+| `whoami` | `creepercli whoami` | Display active session token info, IP, and permissions |
+| `stats` | `creepercli stats` | View live server CPU, RAM heap, disk usage, and Java runtime stats |
+| `tps` | `creepercli tps` | View 1m/5m/15m TPS breakdown with tick health bar |
+| `top` | `creepercli top` | Real-time live dashboard monitoring TPS, RAM, and online players |
+| `log` | `creepercli log [--grep regex]` | Stream live server console logs directly to terminal |
+| `exec` | `creepercli exec <command>` | Run allowlisted Minecraft console commands (`list`, `say`, `restart`) |
+| `ls` | `creepercli ls [path] [-l] [-a]` | List files in server directory |
+| `cd` | `creepercli cd <path>` | Change working directory (`cd ~` or `cd /` goes to jail root) |
+| `cat` | `creepercli cat <file>` | Read file contents from server |
+| `edit` | `creepercli edit <file>` | Pull, edit in local `$EDITOR`, and push back under exclusive lock |
+| `cpush` | `creepercli cpush <local> <remote> [--force]` | Upload a file with SHA-256 integrity verification |
+| `cpull` | `creepercli cpull <remote> <local>` | Download a file with SHA-256 integrity verification |
+| `csync` | `creepercli csync <remote> <local> [-y]` | Two-way directory sync comparing mtimes and checksums |
+
+---
+
+## 🔒 Security Architecture
+
+- **Path Jailing**: All file operations are jailed inside the server working directory (`server-root`). Symlinks and `..` path escapes are blocked (`E_PATH_ESCAPE`).
+- **BCrypt & TOTP 2FA**: User credentials are hashed with BCrypt (cost 12). Optional 2FA with 6-digit TOTP tokens supported.
+- **Fail2Ban Protection**: Automatic IP ban after 3 failed login attempts.
+- **Allowlist Execution**: Only console commands explicitly allowed in `config.yml` can be executed remotely.
+
+---
+
+## 🔗 Links & Resources
+
+- **GitHub Repository**: [DemonZDevelopment/creepercli](https://github.com/DemonZDevelopment/creepercli)
+- **Discord Community**: [Join Support Discord](https://discord.com/invite/zCkE44hsBR)
+- **Modrinth Project**: [CreeperCLI on Modrinth](https://modrinth.com/project/creepercli)
+
+---
+
+## 📄 License
+
+Licensed under the [Apache License, Version 2.0](LICENSE).

package/bin/creepercli.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/*
+ * Copyright 2026 DemonZDevelopment
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+'use strict';
+
+const { main } = require('../src/index');
+
+main(process.argv.slice(2)).then((code) => {
+  if (typeof code === 'number') process.exitCode = code;
+}).catch((err) => {
+  console.error(err && err.message ? err.message : String(err));
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "creepercli",
+  "version": "1.0.0",
+  "description": "Remote administration CLI for Minecraft (Paper/Spigot) servers running the CreeperCLI plugin",
+  "author": "DemonZDevelopment",
+  "license": "Apache-2.0",
+  "type": "commonjs",
+  "main": "src/index.js",
+  "bin": {
+    "creepercli": "bin/creepercli.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test",
+    "start": "node bin/creepercli.js"
+  },
+  "dependencies": {
+    "qrcode-terminal": "^0.12.0"
+  },
+  "keywords": [
+    "minecraft",
+    "spigot",
+    "paper",
+    "bukkit",
+    "admin",
+    "cli",
+    "remote",
+    "server",
+    "creeper",
+    "creepercli"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DemonZDevelopment/creepercli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/DemonZDevelopment/creepercli/issues"
+  },
+  "homepage": "https://github.com/DemonZDevelopment/creepercli"
+}

package/src/client.js

@@ -0,0 +1,127 @@
+/*
+ * Copyright 2026 DemonZDevelopment
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+'use strict';
+
+const net = require('net');
+const crypto = require('crypto');
+const { EventEmitter } = require('events');
+const { StringDecoder } = require('string_decoder');
+const { ProtocolError, ERR } = require('./protocol');
+
+class CreeperClient extends EventEmitter {
+  constructor({ host, port, timeoutMs = 300000 }) {
+    super();
+    this.host = host;
+    this.port = port;
+    this.timeoutMs = timeoutMs;
+    this.socket = null;
+    this.buffer = '';
+    this._decoder = new StringDecoder('utf8');
+    this.pending = new Map();
+  }
+
+  connect() {
+    return new Promise((resolve, reject) => {
+      const socket = net.connect({ host: this.host, port: this.port });
+      this.socket = socket;
+      socket.setNoDelay(true);
+      socket.on('connect', () => resolve());
+      socket.on('error', (err) => reject(err));
+      socket.on('close', () => this._onClose());
+      socket.on('data', (chunk) => this._onData(chunk));
+    });
+  }
+
+  _onData(chunk) {
+    this.buffer += this._decoder.write(chunk);
+    let idx;
+    while ((idx = this.buffer.indexOf('\n')) !== -1) {
+      const line = this.buffer.slice(0, idx).trim();
+      this.buffer = this.buffer.slice(idx + 1);
+      if (!line) continue;
+      this._handleLine(line);
+    }
+  }
+
+  _handleLine(line) {
+    let frame;
+    try {
+      frame = JSON.parse(line);
+    } catch {
+      return;
+    }
+    if (frame.type === 'response') {
+      const entry = this.pending.get(frame.id);
+      if (!entry) return;
+      this.pending.delete(frame.id);
+      clearTimeout(entry.timer);
+      if (frame.ok) {
+        entry.resolve(frame.data || {});
+      } else {
+        entry.reject(new ProtocolError(frame.error && frame.error.code, frame.error && frame.error.message));
+      }
+    } else if (frame.type === 'event') {
+      this.emit('event', frame.event, frame.data || {});
+    }
+  }
+
+  async flush() {
+    while (this.pending.size > 0) {
+      await new Promise((r) => setTimeout(r, 25));
+    }
+  }
+
+  request(action, params = {}, { timeoutMs } = {}) {
+    if (!this.socket) {
+      return Promise.reject(new ProtocolError(ERR.INTERNAL, 'Connection closed'));
+    }
+    const id = crypto.randomUUID();
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new ProtocolError(ERR.TIMEOUT, `Request timed out (${action})`));
+      }, timeoutMs || this.timeoutMs);
+      this.pending.set(id, { resolve, reject, timer });
+      const frame = JSON.stringify({ v: 1, type: 'request', id, action, params });
+      try {
+        this.socket.write(frame + '\n');
+      } catch (err) {
+        clearTimeout(timer);
+        this.pending.delete(id);
+        reject(new ProtocolError(ERR.INTERNAL, `Connection closed (${err.code || err.message})`));
+      }
+    });
+  }
+
+  _onClose() {
+    for (const { reject, timer } of this.pending.values()) {
+      clearTimeout(timer);
+      reject(new ProtocolError(ERR.INTERNAL, 'Connection closed by server'));
+    }
+    this.pending.clear();
+  }
+
+  close() {
+    if (this.socket) {
+      this.socket.end();
+      this.socket.destroy();
+      this.socket = null;
+    }
+  }
+}
+
+module.exports = { CreeperClient };

package/src/commands/auth.js

@@ -0,0 +1,108 @@
+/*
+ * Copyright 2026 DemonZDevelopment
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+'use strict';
+
+const { question, readSecret } = require('../prompts');
+const session = require('../session');
+const config = require('../config');
+
+function saveCreds(cfg, res) {
+  session.save({
+    host: cfg.host,
+    port: cfg.port,
+    token: res.token,
+    username: res.username,
+    expiresAt: Date.now() + res.expiresInMinutes * 60000,
+  });
+  config.save({ host: cfg.host, port: cfg.port });
+}
+
+async function doLogin(ctx) {
+  const user = await question('Username: ');
+  const pass = await readSecret('Password: ');
+  let res;
+  try {
+    res = await ctx.client.request('auth.login', { username: user, password: pass }, { timeoutMs: 30000 });
+  } catch (err) {
+    if (err.code === 'E_TOTP_REQUIRED') {
+      const code = await question('TOTP code: ');
+      res = await ctx.client.request('auth.login', { username: user, password: pass, totp: code }, { timeoutMs: 30000 });
+    } else {
+      throw err;
+    }
+  }
+  saveCreds(ctx.cfg, res);
+  ctx.username = res.username;
+  ctx.cwd = '/';
+  console.log(`Authenticated as ${res.username}. Session valid for ${res.expiresInMinutes} minutes.`);
+  return res;
+}
+
+async function login(ctx) {
+  await doLogin(ctx);
+}
+
+async function logout(ctx) {
+  const creds = session.load(ctx.cfg.host, ctx.cfg.port);
+  await ctx.client.request('auth.logout', { token: creds ? creds.token : null }).catch(() => {});
+  session.clear();
+  ctx.username = null;
+  console.log('Logged out. Local credentials cleared.');
+}
+
+async function whoami(ctx) {
+  const res = await ctx.client.request('auth.whoami');
+  console.log(`User ${res.username} (IP ${res.ip}), cwd ${res.cwd}, session expires in ${Math.floor(res.expiresInSeconds / 60)}m${res.totpEnabled ? ', 2FA enabled' : ', 2FA disabled'}`);
+}
+
+async function ping(ctx) {
+  const res = await ctx.client.request('ping', {}, { timeoutMs: 15000 });
+  console.log(`pong (protocol v${res.protocol}, plugin v${res.pluginVersion}, server time ${new Date(res.serverTime).toISOString()})`);
+}
+
+async function passwd(ctx) {
+  const oldP = await readSecret('Current password: ');
+  const newP = await readSecret('New password: ');
+  if (newP.length < 8) throw new Error('New password must be at least 8 characters');
+  await ctx.client.request('auth.passwd', { oldPassword: oldP, newPassword: newP });
+  console.log('Password changed. Other sessions were invalidated.');
+}
+
+async function totp(ctx, args) {
+  const sub = args[0];
+  if (sub === 'setup') {
+    const pass = await readSecret('Password: ');
+    const res = await ctx.client.request('auth.totp.setup', { password: pass });
+    console.log('Scan the QR below with your authenticator app, or enter the secret manually:');
+    console.log(`Secret: ${res.secret}`);
+    console.log(`(setup expires in ${Math.floor((res.expiresInSeconds || 600) / 60)} minutes)`);
+    const qr = require('qrcode-terminal');
+    qr.generate(res.otpauthUrl, { small: true });
+    const code = await question('Enter the 6-digit code from your authenticator app: ');
+    await ctx.client.request('auth.totp.verify', { code });
+    console.log('TOTP enabled.');
+  } else if (sub === 'disable') {
+    const pass = await readSecret('Password: ');
+    const code = await question('TOTP code: ');
+    await ctx.client.request('auth.totp.disable', { password: pass, code });
+    console.log('TOTP disabled.');
+  } else {
+    throw new Error('Usage: totp <setup|disable>');
+  }
+}
+
+module.exports = { login, logout, whoami, ping, passwd, totp, doLogin };

package/src/commands/exec.js

@@ -0,0 +1,37 @@
+/*
+ * Copyright 2026 DemonZDevelopment
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+'use strict';
+
+async function exec(ctx, args) {
+  if (!args.length) throw new Error('Usage: exec <minecraft command>');
+  const command = args.join(' ');
+  const res = await ctx.client.request('exec.run', { command }, { timeoutMs: 150000 });
+  if (res.lines && res.lines.length) console.log(res.lines.join('\n'));
+  if (!res.success) console.error('Command reported failure');
+  if (res.elapsedMs != null) console.error(`(completed in ${res.elapsedMs}ms)`);
+  return res.success ? 0 : 1;
+}
+
+function say(ctx, args) {
+  return exec(ctx, ['say', ...args]);
+}
+
+function restart(ctx, args) {
+  return exec(ctx, ['restart', ...args]);
+}
+
+module.exports = { exec, say, restart };

package/src/commands/fs.js

@@ -0,0 +1,152 @@
+/*
+ * Copyright 2026 DemonZDevelopment
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+'use strict';
+
+const { formatLs, formatTree, humanSize, formatInfo } = require('../formatters');
+const { editFile } = require('../editor');
+
+async function pwd(ctx) {
+  const res = await ctx.client.request('fs.pwd');
+  ctx.cwd = res.cwd;
+  console.log(res.cwd);
+}
+
+async function ls(ctx, args) {
+  const flags = args.filter((a) => a.startsWith('-') && a !== '-');
+  const longFormat = flags.some((f) => f.includes('l'));
+  const all = flags.some((f) => f.includes('a'));
+  const path = args.find((a) => !a.startsWith('-')) || '.';
+  const res = await ctx.client.request('fs.ls', { path, long: longFormat, all });
+  ctx.cwd = res.cwd;
+  console.log(formatLs(res.entries, { longFormat }));
+}
+
+async function cd(ctx, args) {
+  let path = args[0] || '/';
+  if (path === '~' || path.startsWith('~/')) {
+    path = '/' + path.slice(1).replace(/^\/+/, '');
+  }
+  const res = await ctx.client.request('fs.cd', { path });
+  ctx.cwd = res.cwd;
+  console.log(`Changed directory to ${res.cwd}`);
+}
+
+async function tree(ctx, args) {
+  let depth = 3;
+  const pathArgs = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '-d' || args[i] === '--depth') {
+      depth = parseInt(args[++i], 10) || 3;
+    } else {
+      pathArgs.push(args[i]);
+    }
+  }
+  const res = await ctx.client.request('fs.tree', { path: pathArgs[0] || '.', depth });
+  console.log(formatTree(res.children || []));
+  if (res.truncated) console.log('(tree truncated)');
+}
+
+async function cat(ctx, args) {
+  if (!args[0]) throw new Error('Usage: cat <path>');
+  const res = await ctx.client.request('fs.cat', { path: args[0] });
+  process.stdout.write(res.content);
+  if (!res.content.endsWith('\n')) process.stdout.write('\n');
+  if (res.truncated) console.error(`(truncated: file is ${humanSize(res.size)})`);
+}
+
+async function head(ctx, args) {
+  const { lines, path } = parseTailArgs(args, 10);
+  const res = await ctx.client.request('fs.head', { path, lines });
+  console.log(res.lines.join('\n'));
+  if (res.truncated) console.error('(truncated)');
+}
+
+async function tail(ctx, args) {
+  if (args.includes('-f') || args.includes('--follow')) {
+    throw new Error('Live follow is available via the "log" command: creepercli log [--grep <regex>]');
+  }
+  const { lines, path } = parseTailArgs(args, 10);
+  const res = await ctx.client.request('fs.tail', { path, lines });
+  console.log(res.lines.join('\n'));
+  if (res.truncated) console.error('(truncated)');
+}
+
+function parseTailArgs(args, def) {
+  let n = def;
+  let path = null;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '-n') n = parseInt(args[++i], 10) || def;
+    else path = args[i];
+  }
+  if (!path) throw new Error('Usage: <command> [-n N] <path>');
+  return { lines: n, path };
+}
+
+async function wc(ctx, args) {
+  if (!args[0]) throw new Error('Usage: wc <path>');
+  const res = await ctx.client.request('fs.wc', { path: args[0] });
+  console.log(`${res.lines} ${res.words} ${res.chars} ${humanSize(res.bytes)} ${args[0]}`);
+}
+
+async function touch(ctx, args) {
+  if (!args[0]) throw new Error('Usage: touch <path>');
+  const res = await ctx.client.request('fs.touch', { path: args[0] });
+  console.log(`touched ${res.path}`);
+}
+
+async function mkdir(ctx, args) {
+  const parents = args.includes('-p') || args.includes('--parents');
+  const path = args.find((a) => !a.startsWith('-'));
+  if (!path) throw new Error('Usage: mkdir [-p] <path>');
+  const res = await ctx.client.request('fs.mkdir', { path, parents });
+  console.log(`created ${res.path}`);
+}
+
+async function rm(ctx, args) {
+  const recursive = args.includes('-r') || args.includes('-R') || args.includes('--recursive');
+  const path = args.find((a) => !a.startsWith('-'));
+  if (!path) throw new Error('Usage: rm [-r] <path>');
+  const res = await ctx.client.request('fs.rm', { path, recursive });
+  console.log(`removed ${res.path}`);
+}
+
+async function cp(ctx, args) {
+  const recursive = args.includes('-r') || args.includes('-R') || args.includes('--recursive');
+  const rest = args.filter((a) => !a.startsWith('-'));
+  if (rest.length < 2) throw new Error('Usage: cp [-r] <src> <dst>');
+  const res = await ctx.client.request('fs.cp', { src: rest[0], dst: rest[1], recursive });
+  console.log(`copied ${res.src} -> ${res.dst}`);
+}
+
+async function mv(ctx, args) {
+  if (args.length < 2) throw new Error('Usage: mv <src> <dst>');
+  const res = await ctx.client.request('fs.mv', { src: args[0], dst: args[1] });
+  console.log(`moved ${res.src} -> ${res.dst}`);
+}
+
+async function info(ctx, args) {
+  if (!args[0]) throw new Error('Usage: info <path>');
+  const res = await ctx.client.request('fs.info', { path: args[0] });
+  console.log(formatInfo(res));
+}
+
+async function edit(ctx, args) {
+  if (!args[0]) throw new Error('Usage: edit <path>');
+  return editFile(ctx, args[0]);
+}
+
+module.exports = { pwd, ls, cd, tree, cat, head, tail, wc, touch, mkdir, rm, cp, mv, info, edit };