creepercli 1.0.0

package/src/index.js

@@ -0,0 +1,186 @@
+/*
+ * 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 { CreeperClient } = require('./client');
+const { load: loadConfig, applyFlags } = require('./config');
+const session = require('./session');
+const { startRepl } = require('./repl');
+const { runCommand } = require('./commands');
+const { doLogin } = require('./commands/auth');
+const { friendly } = require('./protocol');
+const { checkUpdate } = require('./update');
+
+async function main(argv) {
+  checkUpdate();
+  const flags = parseFlags(argv);
+  const cfg = applyFlags(loadConfig(), flags);
+  if (flags.help) {
+    printUsage();
+    return 0;
+  }
+  const args = flags.args;
+  const cmd = args[0];
+
+  if (cmd === 'login') {
+    const client = await connect(cfg);
+    const ctx = { client, cfg, username: null, cwd: '/', exit: false, flags };
+    try {
+      const res = await doLogin(ctx);
+      if (res && res.token && process.stdout.isTTY) {
+        console.log('Entering interactive REPL shell (type "help" for commands, "exit" or "q" to quit)...\n');
+        startRepl(ctx);
+        return 0;
+      }
+    } catch (err) {
+      console.error(`\nError: ${friendly(err)}\n`);
+      client.close();
+      process.exit(1);
+    } finally {
+      if (!ctx.exit && !process.stdout.isTTY) {
+        client.close();
+      }
+    }
+    return 0;
+  }
+
+  if (cmd === 'logout') {
+    const client = await connect(cfg);
+    try {
+      const creds = session.load(cfg.host, cfg.port);
+      if (creds) {
+        await runCommand({ client, cfg, username: creds.username, cwd: '/' }, 'logout');
+      } else {
+        console.log('No local session to clear.');
+      }
+    } finally {
+      client.close();
+    }
+    return 0;
+  }
+
+  const client = await connect(cfg);
+  const ctx = { client, cfg, username: null, cwd: '/', exit: false, flags };
+  let creds = session.load(cfg.host, cfg.port);
+  if (creds) {
+    ctx.username = creds.username;
+    try {
+      const resume = await client.request('auth.resume', { token: creds.token }, { timeoutMs: 15000 });
+      ctx.username = resume.username;
+      ctx.cwd = resume.cwd || '/';
+    } catch (err) {
+      if (err.code === 'E_SESSION_EXPIRED' || err.code === 'E_UNAUTHORIZED') {
+        session.clear();
+        creds = null;
+        console.log('Session expired, please log in.');
+      } else {
+        throw err;
+      }
+    }
+  }
+  if (!creds) {
+    if (!process.stdout.isTTY) {
+      console.error('Not authenticated and stdin is not a TTY. Run "creepercli login" first.');
+      client.close();
+      return 1;
+    }
+    await doLogin(ctx);
+  }
+  if (!cmd || cmd === 'repl' || cmd === 'shell') {
+    startRepl(ctx);
+    return 0;
+  }
+  try {
+    return await runCommand(ctx, args.join(' '));
+  } finally {
+    client.close();
+  }
+}
+
+function parseFlags(argv) {
+  const flags = { args: [], host: null, port: null, editor: null, refresh: null, yes: false, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--host') {
+      if (i + 1 < argv.length) flags.host = argv[++i];
+    } else if (a === '--port') {
+      if (i + 1 < argv.length) flags.port = parseInt(argv[++i], 10);
+    } else if (a === '--editor') {
+      if (i + 1 < argv.length) flags.editor = argv[++i];
+    } else if (a === '--refresh') {
+      if (i + 1 < argv.length) flags.refresh = parseInt(argv[++i], 10);
+    } else if (a === '--yes' || a === '-y') {
+      flags.yes = true;
+    } else if (a === '--help' || a === '-h') {
+      flags.help = true;
+    } else {
+      flags.args.push(a);
+    }
+  }
+  return flags;
+}
+
+async function connect(cfg) {
+  const client = new CreeperClient({ host: cfg.host, port: cfg.port });
+  try {
+    await client.connect();
+    return client;
+  } catch (err) {
+    const codeStr = err.code || err.message;
+    console.error(`\nError: Cannot connect to server at ${cfg.host}:${cfg.port} (${codeStr})\n`);
+    console.error(`--------------------------------------------------------------------------------`);
+    console.error(`CREEPER CLI SETUP & TROUBLESHOOTING GUIDE`);
+    console.error(`--------------------------------------------------------------------------------\n`);
+    console.error(`1. INSTALL THE PLUGIN ON YOUR MINECRAFT SERVER:`);
+    console.error(`   * Place CreeperCLI-1.0.0.jar inside your server's 'plugins/' folder.`);
+    console.error(`   * Start or restart your server (Paper / Spigot 1.21+).\n`);
+    console.error(`2. CREATE YOUR ADMIN USER IN SERVER CONSOLE:`);
+    console.error(`   * Open your server console (or run in-game as OP):`);
+    console.error(`     /creepercli user add <username> <password>\n`);
+    console.error(`3. VERIFY NETWORK & PORT FORWARDING:`);
+    console.error(`   * CreeperCLI listens on TCP port ${cfg.port} by default.`);
+    console.error(`   * If connecting to a remote server, specify host & port flags:`);
+    console.error(`     creepercli login --host <your-server-ip> --port ${cfg.port}`);
+    console.error(`   * Or set up an SSH tunnel:`);
+    console.error(`     ssh -L ${cfg.port}:127.0.0.1:${cfg.port} user@<your-server-ip>\n`);
+    console.error(`--------------------------------------------------------------------------------`);
+    console.error(`Documentation: https://github.com/DemonZDevelopment/creepercli\n`);
+    process.exit(1);
+  }
+}
+
+function printUsage() {
+  console.log(`CreeperCLI v1.0.0 — remote Minecraft administration
+
+Usage:
+  creepercli login                       Authenticate with the server
+  creepercli logout                      Clear the local session
+  creepercli <command> [args...]         Run a single command
+  creepercli repl                        Interactive shell (default)
+
+Options:
+  --host <ip>      server address (default 127.0.0.1)
+  --port <port>    server port (default 45678)
+  --editor <cmd>   editor for "edit" (default $EDITOR or vi)
+  --refresh <ms>   dashboard refresh rate for "top"
+  --yes / -y       auto-confirm transfers (csync)
+  --help / -h      show this help
+
+Run "help" inside the REPL for the full command reference.`);
+}
+
+module.exports = { main };

package/src/prompts.js

@@ -0,0 +1,134 @@
+/*
+ * 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 readline = require('readline');
+
+let pipeBuffer = '';
+let pipeWaiters = [];
+let pipeStarted = false;
+let pipeEnded = false;
+
+function startPipeReader() {
+  pipeStarted = true;
+  process.stdin.on('data', (chunk) => {
+    pipeBuffer += chunk.toString();
+    drainPipe();
+  });
+  process.stdin.on('end', () => {
+    pipeEnded = true;
+    drainPipe();
+  });
+}
+
+function drainPipe() {
+  while (pipeWaiters.length > 0) {
+    const idx = pipeBuffer.indexOf('\n');
+    if (idx === -1) {
+      if (pipeEnded && pipeBuffer.length > 0) {
+        const cb = pipeWaiters.shift();
+        const last = pipeBuffer;
+        pipeBuffer = '';
+        cb(last.trim());
+        continue;
+      }
+      break;
+    }
+    const line = pipeBuffer.slice(0, idx);
+    pipeBuffer = pipeBuffer.slice(idx + 1);
+    const cb = pipeWaiters.shift();
+    cb(line.replace(/\r$/, '').trim());
+  }
+  if (pipeEnded && pipeWaiters.length > 0 && pipeBuffer === '') {
+    const cb = pipeWaiters.shift();
+    cb('');
+  }
+}
+
+function pipeQuestion(prompt) {
+  if (!pipeStarted) startPipeReader();
+  process.stdout.write(prompt);
+  return new Promise((resolve) => {
+    pipeWaiters.push(resolve);
+    drainPipe();
+  });
+}
+
+function question(prompt) {
+  if (!process.stdin.isTTY) {
+    return pipeQuestion(prompt);
+  }
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(prompt, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+function readSecret(prompt) {
+  if (!process.stdin.isTTY) {
+    return pipeQuestion(prompt);
+  }
+  return new Promise((resolve, reject) => {
+    const input = process.stdin;
+    const output = process.stdout;
+    input.setRawMode(true);
+    input.resume();
+    output.write(prompt);
+    let value = '';
+    const onData = (chunk) => {
+      for (const ch of chunk.toString()) {
+        if (ch === '\u0003') {
+          cleanup();
+          reject(new Error('Aborted'));
+          return;
+        }
+        if (ch === '\r' || ch === '\n') {
+          output.write('\n');
+          cleanup();
+          resolve(value);
+          return;
+        }
+        if (ch === '\u007f' || ch === '\b') {
+          if (value.length > 0) {
+            value = value.slice(0, -1);
+            output.write('\b \b');
+          }
+        } else {
+          value += ch;
+          output.write('*');
+        }
+      }
+    };
+    const cleanup = () => {
+      input.removeListener('data', onData);
+      input.setRawMode(false);
+      input.pause();
+    };
+    input.on('data', onData);
+  });
+}
+
+async function confirm(text, defYes = false) {
+  const answer = await question(text + (defYes ? ' [Y/n] ' : ' [y/N] '));
+  if (!answer) return defYes;
+  return /^y(es)?$/i.test(answer.trim());
+}
+
+module.exports = { question, readSecret, confirm };

package/src/protocol.js

@@ -0,0 +1,82 @@
+/*
+ * 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 ERR = {
+  UNAUTHORIZED: 'E_UNAUTHORIZED',
+  AUTH_FAILED: 'E_AUTH_FAILED',
+  TOTP_REQUIRED: 'E_TOTP_REQUIRED',
+  BANNED: 'E_BANNED',
+  RATE_LIMITED: 'E_RATE_LIMITED',
+  SESSION_EXPIRED: 'E_SESSION_EXPIRED',
+  INVALID_PARAMS: 'E_INVALID_PARAMS',
+  BAD_REQUEST: 'E_BAD_REQUEST',
+  PATH_ESCAPE: 'E_PATH_ESCAPE',
+  NOT_FOUND: 'E_NOT_FOUND',
+  IS_DIRECTORY: 'E_IS_DIRECTORY',
+  NOT_DIRECTORY: 'E_NOT_DIRECTORY',
+  ALREADY_EXISTS: 'E_ALREADY_EXISTS',
+  FORBIDDEN: 'E_FORBIDDEN',
+  IO: 'E_IO',
+  LOCKED: 'E_LOCKED',
+  ALLOWLIST_DENIED: 'E_ALLOWLIST_DENIED',
+  TIMEOUT: 'E_TIMEOUT',
+  PAYLOAD_TOO_LARGE: 'E_PAYLOAD_TOO_LARGE',
+  CHECKSUM_MISMATCH: 'E_CHECKSUM_MISMATCH',
+  NO_TRANSFER: 'E_NO_TRANSFER',
+  INTERNAL: 'E_INTERNAL',
+  SERVER_FULL: 'E_SERVER_FULL',
+};
+
+const PROTOCOL_VERSION = 1;
+
+const EVENT_LOG_LINE = 'log.line';
+
+class ProtocolError extends Error {
+  constructor(code, message) {
+    super(message || code);
+    this.code = code;
+  }
+}
+
+function friendly(err) {
+  if (err instanceof ProtocolError) {
+    const hints = {
+      [ERR.UNAUTHORIZED]: 'run "creepercli login" first',
+      [ERR.AUTH_FAILED]: 'check your username/password or add user in server console: /creepercli user add <user> <pass>',
+      [ERR.TOTP_REQUIRED]: 'provide your 6-digit TOTP code',
+      [ERR.BANNED]: 'too many failures, this IP is temporarily banned by Fail2Ban',
+      [ERR.RATE_LIMITED]: 'too many requests in a short window, please slow down',
+      [ERR.SESSION_EXPIRED]: 'session expired, run "creepercli login"',
+      [ERR.PATH_ESCAPE]: 'path blocked by server PathSanitizer sandbox',
+      [ERR.ALLOWLIST_DENIED]: 'command restricted by server allowlist config',
+      [ERR.LOCKED]: 'file currently locked by another active session',
+      [ERR.CHECKSUM_MISMATCH]: 'data integrity check failed, partial file cleaned up',
+      [ERR.SERVER_FULL]: 'server connection limit reached',
+      [ERR.TIMEOUT]: 'request timed out, check server load',
+      [ERR.NOT_FOUND]: 'file or directory not found on remote server',
+      [ERR.IS_DIRECTORY]: 'target path is a directory, not a file',
+      [ERR.NOT_DIRECTORY]: 'target path is a file, not a directory',
+      [ERR.FORBIDDEN]: 'permission denied by server policy',
+    };
+    const hint = hints[err.code];
+    return `${err.message}${hint ? ` [${hint}]` : ''} (${err.code})`;
+  }
+  return err && err.message ? err.message : String(err);
+}
+
+module.exports = { ERR, PROTOCOL_VERSION, EVENT_LOG_LINE, ProtocolError, friendly };

package/src/repl.js

@@ -0,0 +1,104 @@
+/*
+ * 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 fs = require('fs');
+const readline = require('readline');
+const { COMMANDS, runCommand } = require('./commands');
+
+function prompt(ctx) {
+  return `${ctx.username || '?'}@${ctx.cfg.host}:${ctx.cwd || '/'}> `;
+}
+
+function startRepl(ctx) {
+  const completions = COMMANDS.map((c) => c.name);
+
+  function completer(line) {
+    const trimmed = line.trimStart();
+    const hits = completions.filter((c) => c.startsWith(trimmed));
+    return [hits.length ? hits : completions, trimmed];
+  }
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: true,
+    historySize: 1000,
+    completer,
+  });
+  try {
+    const history = fs.readFileSync(ctx.cfg.historyFile, 'utf8').split('\n').filter(Boolean).reverse();
+    rl.history = history;
+  } catch {
+  }
+  rl.on('history', (history) => {
+    try {
+      fs.writeFileSync(ctx.cfg.historyFile, history.filter(Boolean).join('\n') + '\n', { mode: 0o600 });
+    } catch {
+    }
+  });
+
+  const queue = [];
+  let running = false;
+  async function pump() {
+    if (running) return;
+    running = true;
+    while (queue.length) {
+      const line = queue.shift();
+      await runCommand(ctx, line);
+      if (ctx.exit) {
+        queue.length = 0;
+        break;
+      }
+      rl.setPrompt(prompt(ctx));
+      rl.prompt();
+    }
+    running = false;
+  }
+
+  rl.setPrompt(prompt(ctx));
+  rl.prompt();
+
+  rl.on('line', (line) => {
+    queue.push(line);
+    pump();
+  });
+
+  rl.on('SIGINT', () => {
+    if (running) {
+      if (ctx.interruptHandler) {
+        console.log('\n(interrupted)');
+        ctx.interruptHandler();
+      } else {
+        console.log('\n(interrupt)');
+      }
+      return;
+    }
+    rl.question('Really quit? [y/N] ', (answer) => {
+      if (/^y/i.test(answer.trim())) rl.close();
+      else rl.prompt();
+    });
+  });
+
+  rl.on('close', async () => {
+    await ctx.client.flush();
+    ctx.client.close();
+    process.exit(0);
+  });
+}
+
+module.exports = { startRepl, prompt };

package/src/session.js

@@ -0,0 +1,58 @@
+/*
+ * 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 fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const DIR = path.join(os.homedir(), '.creepercli');
+const CREDS_FILE = path.join(DIR, 'creds');
+const HISTORY_FILE = path.join(DIR, 'history');
+
+function ensureDir() {
+  fs.mkdirSync(DIR, { recursive: true, mode: 0o700 });
+}
+
+function save(creds) {
+  ensureDir();
+  fs.writeFileSync(CREDS_FILE, JSON.stringify(creds, null, 2), { mode: 0o600 });
+}
+
+function load(host, port) {
+  try {
+    const raw = fs.readFileSync(CREDS_FILE, 'utf8');
+    const creds = JSON.parse(raw);
+    if (creds.host !== host || creds.port !== port) return null;
+    if (creds.expiresAt && Date.now() > creds.expiresAt) {
+      clear();
+      return null;
+    }
+    return creds;
+  } catch {
+    return null;
+  }
+}
+
+function clear() {
+  try {
+    fs.unlinkSync(CREDS_FILE);
+  } catch {
+  }
+}
+
+module.exports = { DIR, CREDS_FILE, HISTORY_FILE, save, load, clear };

package/src/top.js

@@ -0,0 +1,53 @@
+/*
+ * 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 readline = require('readline');
+const { formatStats, formatTps } = require('./formatters');
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+async function runTop(client, refreshMs) {
+  if (process.stdin.isTTY) {
+    readline.emitKeypressEvents(process.stdin);
+    process.stdin.setRawMode(true);
+  }
+  let stopped = false;
+  const onKey = (str, key) => {
+    if (key.name === 'q' || key.name === 'escape' || (key.ctrl && key.name === 'c')) stopped = true;
+  };
+  process.stdin.on('keypress', onKey);
+  try {
+    while (!stopped) {
+      const res = await client.request('monitor.top', {});
+      readline.cursorTo(process.stdout, 0, 0);
+      readline.clearScreenDown(process.stdout);
+      console.log('CreeperCLI top (q to quit)\n');
+      console.log(formatStats(res.stats));
+      console.log();
+      console.log(formatTps(res.tps));
+      await sleep(refreshMs);
+    }
+  } finally {
+    process.stdin.removeListener('keypress', onKey);
+    if (process.stdin.isTTY) process.stdin.setRawMode(false);
+  }
+}
+
+module.exports = { runTop };