@mincraft/cli 1.2.0 → 1.4.0

package/dist/index.mjs

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
-import{Option as I,program as n}from"commander";import*as v from"readline";import{createBot as M}from"mineflayer";import{SocksClient as E}from"socks";var p=class{proxy;client;server;options;logger;isLoggedIn;bot;constructor({proxy:t,client:e,server:o,options:i},s){this.proxy=t,this.client=e,this.server=o,this.options=i,this.logger=s,this.isLoggedIn=!1}async registerAndLogIn(){let t={host:this.server.host,port:this.server.port,username:this.client.account.email,auth:this.client.account.auth,version:this.client.version,hideErrors:!0};this.proxy&&(t.connect=e=>{this.connectViaProxy(e)}),this.bot=M(t),this.options.verboseLogging&&this.registerClientEvents(),this.registerBotEvents()}connectViaProxy(t){this.logger.log("connecting via proxy");let{host:e,port:o,user:i,pass:s,type:a}=this.proxy,c=this.server;E.createConnection({proxy:{host:e,port:o,type:a,userId:i,password:s},command:"connect",destination:{host:c.host,port:c.port},timeout:3e4}).then(l=>{t.setSocket(l.socket),t.emit("connect")}).catch(l=>{this.logger.error(`proxy connection failed: ${l.message}`),t.emit("error",l)})}registerClientEvents(){this.bot._client.on("connect",()=>{this.logger.log("TCP connection established")}),this.bot._client.on("login",()=>{this.logger.log("login packet received")}),this.bot._client.on("error",t=>{this.logger.error(`client error: ${t.message}`)}),this.bot._client.on("end",t=>{this.logger.warn(`client ended: ${t}`)})}registerBotEvents(){this.bot.once("spawn",()=>{let{ign:t,uuid:e}=this.client.account;this.logger.log(`logged in as ${t} (${e})`),this.isLoggedIn=!0}),this.bot.once("kicked",t=>{this.logger.warn(`kicked: ${JSON.stringify(t)}`),this.disconnect()}),this.bot.once("error",t=>{this.logger.error(`bot error: ${t.message}`),this.isLoggedIn=!1}),this.bot.once("end",t=>{this.logger.warn(`disconnected by server: ${JSON.stringify(t)}`),this.disconnect()}),this.options.logMessages&&this.bot.on("messagestr",t=>{let e=t.split(`
-`);if(e.length===1)this.logger.log(t,"chat");else{this.logger.log(e[0],"chat");for(let o=1;o<e.length;o++)this.logger.raw(`          ${e[o]}`)}})}disconnect(){this.bot&&(this.proxy?this.bot._client.socket?.destroy():this.bot.quit(),this.isLoggedIn=!1)}sendMessage(t){this.bot.chat(t)}};import*as u from"readline";function m(r){let t=(o,i="")=>`[mc${i?`/${i}`:""}] ${o}`,e=o=>{r?(u.clearLine(process.stdout,0),u.cursorTo(process.stdout,0),console.log(o),r.prompt(!0)):console.log(o)};return{log:(o,i)=>e(t(o,i)),warn:(o,i="warn")=>e(t(o,i)),error:(o,i="err")=>e(t(o,i)),raw:e}}import*as g from"fs/promises";import*as d from"path";import*as x from"esbuild";async function O(r){let e=(await x.build({entryPoints:[r],bundle:!0,write:!1,platform:"node",format:"esm",target:"es2022",loader:{".ts":"ts"},external:["mineflayer"],logLevel:"silent"})).outputFiles[0].text,o=r.replace(/\.ts$/,".macro.mjs");return await g.writeFile(o,e),o}async function S(r){try{await g.unlink(r)}catch{}}function F(r){return d.isAbsolute(r)?r:d.resolve(process.cwd(),r)}async function k(r){try{return await g.access(r),!0}catch{return!1}}async function b(r,t){let e=F(r),o=e,i=null;try{if(!await k(e))return t.logger.error(`macro file not found: ${e}`),!1;e.endsWith(".ts")&&(t.logger.log("compiling typescript macro"),i=await O(e),o=i);let c=await import(`file://${o}?t=${Date.now()}`);return typeof c.default!="function"?(t.logger.error("macro file must export a default function"),!1):(await c.default(t),!0)}catch(s){return t.logger.error(`could not load macro: ${s.message}`),!1}finally{i&&await S(i)}}var C=(i=>(i.Exit=".exit",i.Logout=".lo",i.Login=".li",i.Macro=".macro",i))(C||{});function w(r){return Object.values(C).some(t=>r.startsWith(t))}async function L(r){let t=null,e=v.createInterface({input:process.stdin,output:process.stdout}),o=m(e);e.setPrompt("> ");let i=async s=>{if(s=s.trim(),!w(s)&&!t?.isLoggedIn){o.raw("log in using .li before sending messages"),e.prompt();return}if(w(s)){let[a,...c]=s.split(" "),l=!1;switch(a){case".exit":{t?.disconnect(),e.close(),l=!0;break}case".li":{t?.isLoggedIn?o.error("client is already logged in"):(t=new p(r,o),t.registerAndLogIn());break}case".lo":{t?.isLoggedIn?t?.disconnect():o.error("client isn't logged in");break}case".macro":{if(!t?.isLoggedIn){o.error("client must be logged in to run macros");break}let f=c.join(" ");if(!f){o.error("usage: .macro <filepath>");break}let y=t.bot;y&&(o.log(`loading macro: ${f}`),await b(f,{bot:y,logger:o}));break}}l&&process.exit(0)}else t?.sendMessage(s);e.prompt()};e.on("line",i),console.log("=== mincraft REPL ==="),console.log("input plain text to send a message to the server"),console.log(`input .li to log in to ${r.server.host}`),console.log(`input .lo to log out from ${r.server.host}`),console.log("input .macro <filepath> to run a macro"),console.log("input .exit to exit the REPL"),e.prompt()}n.name("mincraft").description("Mineflayer CLI tool with supports for macros and proxies.").version("1.0.0").addHelpText("after",`
+import{Option as O,program as l}from"commander";function F(t){let o=[],e="",r=0;for(;r<t.length;)t[r]==="\\"&&r+1<t.length?(e+=t[r]+t[r+1],r+=2):t[r]===","?(o.push(e),e="",r++):(e+=t[r],r++);return o.push(e),o}function T(t){let o="",e=0;for(;e<t.length;)if(t[e]==="\\"&&e+1<t.length){let r=t[e+1];r===","||r==="{"||r==="}"?(o+=r,e+=2):(o+=t[e],e++)}else o+=t[e],e++;return o}function v(t){let o=[],e=F(t),r=/^\{\{(\d+(?:\.\d+)?)\}\}$/;for(let n of e){let s=n.trim();if(!s)continue;let a=s.match(r);if(a){let i=parseFloat(a[1]),c=Math.round(i*1e3);o.push({command:"",delay:c})}else{let i=T(s);o.push({command:i,delay:0})}}return o}import*as I from"readline";import p from"chalk";import{createBot as A}from"mineflayer";import{SocksClient as D}from"socks";var u=class{proxy;client;server;options;logger;isLoggedIn;bot;constructor({proxy:o,client:e,server:r,options:n},s){this.proxy=o,this.client=e,this.server=r,this.options=n,this.logger=s,this.isLoggedIn=!1}async registerAndLogIn(){let o={host:this.server.host,port:this.server.port,username:this.client.account.email,auth:this.client.account.auth,version:this.client.version,hideErrors:!0};this.proxy&&(o.connect=e=>{this.connectViaProxy(e)}),this.bot=A(o),this.options.verboseLogging&&this.registerClientEvents(),this.registerBotEvents()}connectViaProxy(o){this.logger.log("connecting via proxy");let{host:e,port:r,user:n,pass:s,type:a}=this.proxy,i=this.server;D.createConnection({proxy:{host:e,port:r,type:a,userId:n,password:s},command:"connect",destination:{host:i.host,port:i.port},timeout:3e4}).then(c=>{o.setSocket(c.socket),o.emit("connect")}).catch(c=>{this.logger.error(`proxy connection failed: ${c.message}`),o.emit("error",c)})}registerClientEvents(){this.bot._client.on("connect",()=>{this.logger.log("TCP connection established")}),this.bot._client.on("login",()=>{this.logger.log("login packet received")}),this.bot._client.on("error",o=>{this.logger.error(`client error: ${o.message}`)}),this.bot._client.on("end",o=>{this.logger.warn(`client ended: ${o}`)})}registerBotEvents(){this.bot.once("spawn",()=>{let{ign:o,uuid:e}=this.client.account;this.logger.log(`logged in as ${o} (${e})`),this.isLoggedIn=!0}),this.bot.once("kicked",o=>{this.logger.warn(`kicked: ${JSON.stringify(o)}`),this.disconnect()}),this.bot.once("error",o=>{this.logger.error(`bot error: ${o.message}`),this.isLoggedIn=!1}),this.bot.once("end",o=>{this.logger.warn(`disconnected by server: ${JSON.stringify(o)}`),this.disconnect()}),this.options.logMessages&&this.bot.on("messagestr",o=>{let e=o.split(`
+`);if(e.length===1)this.logger.log(o,"chat");else{this.logger.log(e[0],"chat");for(let r=1;r<e.length;r++)this.logger.raw(`          ${e[r]}`)}})}disconnect(){this.bot&&(this.proxy?this.bot._client.socket?.destroy():this.bot.quit(),this.isLoggedIn=!1)}sendMessage(o){this.bot.chat(o)}};import*as y from"readline";import h from"chalk";function U(t){return t?`/${t.split("/").map((r,n)=>n===0?r==="err"?h.red(r):r==="warn"?h.yellow(r):h.gray(r):h.blue(r)).join("/")}`:""}function m(t,o){let e=(n,s="")=>{let a=o?s?`${o}/${s}`:o:s;return`[mc${U(a)}] ${n}`},r=n=>{t?(y.clearLine(process.stdout,0),y.cursorTo(process.stdout,0),console.log(n),t.prompt(!0)):console.log(n)};return{log:(n,s)=>r(e(n,s)),warn:(n,s="warn")=>r(e(n,s)),error:(n,s="err")=>r(e(n,s)),raw:r}}import*as f from"fs/promises";import*as d from"path";import*as C from"esbuild";async function j(t){let e=(await C.build({entryPoints:[t],bundle:!0,write:!1,platform:"node",format:"esm",target:"es2022",loader:{". ts":"ts"},external:["mineflayer"],logLevel:"silent"})).outputFiles[0].text,r=t.replace(/\.ts$/,". macro.mjs");return await f.writeFile(r,e),r}async function B(t){try{await f.unlink(t)}catch{}}function N(t){return d.isAbsolute(t)?t:d.resolve(process.cwd(),t)}async function R(t){try{return await f.access(t),!0}catch{return!1}}function _(t){return d.basename(t).replace(/\.(ts|js|mjs)$/,"")}async function $(t,o,e){let r=N(t),n=r,s=null,a=m(e,`macro/${_(t)}`);try{if(!await R(r))return a.error(`file not found: ${r}`),!1;r.endsWith(".ts")&&(a.log("compiling macro to js"),s=await j(r),n=s);let g=await import(`file://${n}?t=${Date.now()}`);return typeof g.default!="function"?(a.error("macro file must export a default function"),!1):(a.log("running"),await g.default({bot:o,logger:a}),a.log("finished"),!0)}catch(i){return a.error(`failed: ${i.message}`),!1}finally{s&&await B(s)}}var E=(s=>(s.Exit=".exit",s.Logout=".lo",s.Login=".li",s.Macro=".macro",s.Help=".help",s))(E||{});function L(t){return Object.values(E).some(o=>t.startsWith(o))}function H(t,o){t(`type ${p.magenta(".li")} to log in to ${o}`),t(`type ${p.magenta(".lo")} to log out from ${o}`),t(`type ${p.magenta(".macro <filepath>")} to run a macro`),t(`type ${p.magenta(".help")} to show this REPL reference`),t(`type ${p.magenta(".exit")} to exit the REPL`),t(`type ${p.bold("any other value")} to send a message to the server`)}async function P(t,o){process.stdout.write("\x1B[2J\x1B[2;0H");let e=null,r=I.createInterface({input:process.stdin,output:process.stdout}),n=m(r),s=i=>n.raw(`>> ${i}`);r.setPrompt("> ");let a=async i=>{if(i=i.trim(),!i)return!1;if(!L(i)&&!e?.isLoggedIn)return n.error("log in using .li before sending messages"),!1;if(L(i)){let[c,...g]=i.split(" ");switch(c){case".exit":return e?.disconnect(),r.close(),!0;case".li":{e?.isLoggedIn?n.error("client is already logged in"):(e=new u(t,n),e.registerAndLogIn());break}case".lo":{e?.isLoggedIn?e?.disconnect():n.error("client isn't logged in");break}case".macro":{if(!e?.isLoggedIn){n.error("client must be logged in to run macros");break}let b=g.join(" ");if(!b){n.error("usage: .macro <filepath>");break}let w=e.bot;w&&await $(b,w,r);break}case".help":{H(s,t.server.host);break}}}else e?.sendMessage(i);return!1};if(r.on("line",async i=>{await a(i)&&process.exit(0),r.prompt()}),console.log(p.green(`mincraft REPL ${M}`)),s('type ".help" for more information.'),o&&o.length>0)for(let{command:i,delay:c}of o)c>0&&await new Promise(g=>setTimeout(g,c)),i&&(n.raw(`> ${i}`),await a(i)&&process.exit(0));r.prompt()}l.name("mincraft").description("Mineflayer CLI tool with supports for macros and proxies.").version("1.0.0").addHelpText("after",`
 Examples:
 $ mincraft mc.hypixel.net 1.21.4 --ign FuriousDestroyer --email you@example.com
 $ mincraft mythic.gg 1.7.10 -p 58585 --ign MangoSyrup --email you@example.com --prox proxy.com:1234:mango:secret
-`);n.argument("<host>","Server hostname").option("-p, --port <PORT>","Server port",r=>parseInt(r,10),25565);n.argument("<version>","Client version, e.g. 1.21.4");var P=["host","port","user","pass"],$=":";n.option("--prox <HOST:PORT:USER:PASS>","Connect to the server with a proxy").option("--prox-field-order <FORMAT>",'The order of the proxy credential fields, e.g. "user,pass,host,port".').option("--prox-field-sep <SEP>","The separator of the proxy credential fields").option("--prox-type <4|5>","The SOCKS proxy type",r=>parseInt(r,10),5);var T="microsoft";n.addOption(new I("--ign <IN-GAME NAME>","Player username").conflicts("uuid")).addOption(new I("--uuid <UUID>","Player UUID").conflicts("ign")).requiredOption("--email <EMAIL>","Account email").option("--auth <AUTH>","Account authentication method",T);n.option("--no-log-messages","Do not log messages your client receives").option("--verbose","Enable additional logging messages");n.action(async(r,t,e)=>{if(!e.ign&&!e.uuid&&n.error("error: must specify either --ign or --uuid"),e.proxFieldOrder){let i=e.proxyFieldSep??$;e.proxFieldOrder.split(i).every(a=>P.includes(a))||n.error("error: --prox-field-order includes invalid fields")}let o=await B(n);await L(o)});async function A(r){let e=await(await fetch(`https://sessionserver.mojang.com/session/minecraft/profile/${r}`)).json();if(!e?.name)throw new Error("Could not fetch IGN from UUID");return e.name}async function U(r){let e=await(await fetch(`https://api.mojang.com/users/profiles/minecraft/${r}`)).json();if(!e?.id)throw new Error("Could not fetch UUID from IGN");return e.id}function j(r,t,e){let o=r.split(e),i=Object.fromEntries(t.map((s,a)=>[s,o[a]]));return i.port=+i.port,i}async function B(r){let t=r.args,e=r.opts();return{server:{host:t[0],port:e.port},client:{version:t[1],account:{auth:e.auth,uuid:e.uuid??await U(e.ign),ign:e.ign??await A(e.uuid),email:e.email}},...e.prox?{proxy:{...j(e.prox,e.proxFieldOrder??P,e.proxFieldSep??$),type:e.proxType}}:{},options:{logMessages:e.noLogMessages??!0,verboseLogging:e.verbose??!1}}}var h=m(),Y=h.log,Z=h.warn,ee=h.error;n.parse();export{h as defaultLogger,ee as error,Y as log,Z as warn};
+$ mincraft mc.hypixel.net 1.21.4 --ign Player --email you@example.com --exec "{{1}},.li,{{2.5}},hello,{{0.5}},.lo"
+$ mincraft mc.hypixel.net 1.21.4 --ign Player --email you@example.com --exec "{{1.5}},.li,{{5}},hello\\,world,{{0.5}},.lo"
+`);l.argument("<host>","Server hostname").option("-p, --port <PORT>","Server port",t=>parseInt(t,10),25565);l.argument("<version>","Client version, e.g. 1.21.4");var S=["host","port","user","pass"],k=":";l.option("--prox <HOST:PORT:USER:PASS>","Connect to the server with a proxy").option("--prox-field-order <FORMAT>",'The order of the proxy credential fields, e.g. "user,pass,host,port".').option("--prox-field-sep <SEP>","The separator of the proxy credential fields").option("--prox-type <4|5>","The SOCKS proxy type",t=>parseInt(t,10),5);var G="microsoft";l.addOption(new O("--ign <IN-GAME NAME>","Player username").conflicts("uuid")).addOption(new O("--uuid <UUID>","Player UUID").conflicts("ign")).requiredOption("--email <EMAIL>","Account email").option("--auth <AUTH>","Account authentication method",G);l.option("--no-log-messages","Do not log messages your client receives").option("--verbose","Enable additional logging messages").option("--exec <COMMANDS>",'Execute REPL commands on startup with optional delays, e.g. "{{1}},.li,{{2.5}},hello,{{0.5}},.lo", where {{N}} represents a delay. You can escape curly braces and commas to include them in commands/messages.',(t,o)=>o.concat(t),[]);l.action(async(t,o,e)=>{if(!e.ign&&!e.uuid&&l.error("error: must specify either --ign or --uuid"),e.proxFieldOrder){let s=e.proxyFieldSep??k;e.proxFieldOrder.split(s).every(i=>S.includes(i))||l.error("error: --prox-field-order includes invalid fields")}let r=await W(l),n=[];for(let s of e.exec){let a=v(s);n.push(...a)}await P(r,n.length>0?n:void 0)});async function J(t){let e=await(await fetch(`https://sessionserver.mojang.com/session/minecraft/profile/${t}`)).json();if(!e?.name)throw new Error("Could not fetch IGN from UUID");return e.name}async function q(t){let e=await(await fetch(`https://api.mojang.com/users/profiles/minecraft/${t}`)).json();if(!e?.id)throw new Error("Could not fetch UUID from IGN");return e.id}function V(t,o,e){let r=t.split(e),n=Object.fromEntries(o.map((s,a)=>[s,r[a]]));return n.port=+n.port,n}async function W(t){let o=t.args,e=t.opts();return{server:{host:o[0],port:e.port},client:{version:o[1],account:{auth:e.auth,uuid:e.uuid??await q(e.ign),ign:e.ign??await J(e.uuid),email:e.email}},...e.prox?{proxy:{...V(e.prox,e.proxFieldOrder??S,e.proxFieldSep??k),type:e.proxType}}:{},options:{logMessages:e.noLogMessages??!0,verboseLogging:e.verbose??!1}}}var x=m(),de=x.log,ue=x.warn,he=x.error,M="v1.4.0";l.parse();export{x as defaultLogger,he as error,de as log,M as version,ue as warn};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mincraft/cli",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Mineflayer CLI tool with support for macros and proxies",
   "bin": {
     "mincraft": "./dist/index.mjs"
@@ -13,11 +13,12 @@
   ],
   "dependencies": {
     "@inquirer/prompts": "^8.1.0",
+    "chalk": "^5.6.2",
     "commander": "^14.0.2",
     "esbuild": "^0.27.2",
     "mineflayer": "^4.33.0",
     "socks": "^2.8.7",
-    "@mincraft/types": "1.2.0"
+    "@mincraft/types": "1.4.0"
   },
   "devDependencies": {
     "@types/debug": "^4.1.12",

package/src/cli.ts

@@ -1,6 +1,11 @@
-import type { Config, ProxyCredentials } from "@mincraft/types";
+import type {
+	Config,
+	DelayableCommands,
+	ProxyCredentials,
+} from "@mincraft/types";
 import { type Command, Option, program } from "commander";
-import { run } from "./runner";
+import { parseExecCommands } from "./exec";
+import { run } from "./repl";
 
 // meta
 program
@@ -13,6 +18,8 @@ program
 Examples:
 $ mincraft mc.hypixel.net 1.21.4 --ign FuriousDestroyer --email you@example.com
 $ mincraft mythic.gg 1.7.10 -p 58585 --ign MangoSyrup --email you@example.com --prox proxy.com:1234:mango:secret
+$ mincraft mc.hypixel.net 1.21.4 --ign Player --email you@example.com --exec "{{1}},.li,{{2.5}},hello,{{0.5}},.lo"
+$ mincraft mc.hypixel.net 1.21.4 --ign Player --email you@example.com --exec "{{1.5}},.li,{{5}},hello\\,world,{{0.5}},.lo"
 `,
 	);
 
@@ -66,7 +73,14 @@ program
 // extra options
 program
 	.option("--no-log-messages", "Do not log messages your client receives")
-	.option("--verbose", "Enable additional logging messages");
+	.option("--verbose", "Enable additional logging messages")
+	.option(
+		"--exec <COMMANDS>",
+		'Execute REPL commands on startup with optional delays, e.g. "{{1}},.li,{{2.5}},hello,{{0.5}},.lo", where {{N}} represents a delay.' +
+			" You can escape curly braces and commas to include them in commands/messages.",
+		(val: string, prev: string[]) => prev.concat(val),
+		[],
+	);
 
 program.action(async (_host, _version, options) => {
 	if (!options.ign && !options.uuid) {
@@ -83,7 +97,13 @@ program.action(async (_host, _version, options) => {
 	}
 
 	const config = await getConfig(program);
-	await run(config);
+
+	const commands: DelayableCommands = [];
+	for (const cmd of options.exec) {
+		const parsed = parseExecCommands(cmd);
+		commands.push(...parsed);
+	}
+	await run(config, commands.length > 0 ? commands : undefined);
 });
 
 async function getIGN(uuid: string) {

package/src/exec.ts

@@ -0,0 +1,73 @@
+import type { DelayableCommands } from "@mincraft/types";
+
+function splitByUnescapedCommas(input: string) {
+	const parts: string[] = [];
+	let current = "";
+	let i = 0;
+
+	while (i < input.length) {
+		if (input[i] === "\\" && i + 1 < input.length) {
+			current += input[i] + input[i + 1];
+			i += 2;
+		} else if (input[i] === ",") {
+			parts.push(current);
+			current = "";
+			i++;
+		} else {
+			current += input[i];
+			i++;
+		}
+	}
+	parts.push(current);
+
+	return parts;
+}
+
+function unescapeString(input: string) {
+	let result = "";
+	let i = 0;
+
+	while (i < input.length) {
+		if (input[i] === "\\" && i + 1 < input.length) {
+			const nextChar = input[i + 1];
+			if (nextChar === "," || nextChar === "{" || nextChar === "}") {
+				result += nextChar;
+				i += 2;
+			} else {
+				result += input[i];
+				i++;
+			}
+		} else {
+			result += input[i];
+			i++;
+		}
+	}
+
+	return result;
+}
+
+export function parseExecCommands(input: string) {
+	const result: DelayableCommands = [];
+	const parts = splitByUnescapedCommas(input);
+
+	const delayPattern = /^\{\{(\d+(?:\.\d+)?)\}\}$/;
+
+	for (const part of parts) {
+		const trimmed = part.trim();
+		if (!trimmed) {
+			continue;
+		}
+
+		const delayMatch = trimmed.match(delayPattern);
+		if (delayMatch) {
+			const delaySeconds = parseFloat(delayMatch[1]);
+			const delayMs = Math.round(delaySeconds * 1000);
+			result.push({ command: "", delay: delayMs });
+		} else {
+			const command = unescapeString(trimmed);
+			result.push({ command, delay: 0 });
+		}
+	}
+
+	return result;
+}

package/src/index.ts

@@ -6,4 +6,6 @@ export const log = defaultLogger.log;
 export const warn = defaultLogger.warn;
 export const error = defaultLogger.error;
 
+export const version = "v1.4.0";
+
 program.parse();

package/src/logger.ts

@@ -1,9 +1,35 @@
 import * as readline from "node:readline";
 import type { Logger } from "@mincraft/types";
+import chalk from "chalk";
 
-export function createLogger(rl?: readline.Interface): Logger {
-	const format = (msg: string, scope = "") =>
-		`[mc${scope ? `/${scope}` : ""}] ${msg}`;
+function formatScope(fullScope: string) {
+	if (!fullScope) return "";
+
+	const parts = fullScope.split("/");
+	const colored = parts.map((part, i) => {
+		if (i === 0) {
+			if (part === "err") return chalk.red(part);
+			if (part === "warn") return chalk.yellow(part);
+			return chalk.gray(part);
+		}
+		return chalk.blue(part);
+	});
+
+	return `/${colored.join("/")}`;
+}
+
+export function createLogger(
+	rl?: readline.Interface,
+	baseScope?: string,
+): Logger {
+	const format = (msg: string, scope = "") => {
+		const fullScope = baseScope
+			? scope
+				? `${baseScope}/${scope}`
+				: baseScope
+			: scope;
+		return `[mc${formatScope(fullScope)}] ${msg}`;
+	};
 
 	const write = (msg: string) => {
 		if (rl) {

package/src/macro.ts

@@ -1,7 +1,10 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import type { MacroContext, MacroModule } from "@mincraft/types";
+import type { Interface } from "node:readline";
+import type { MacroModule } from "@mincraft/types";
 import * as esbuild from "esbuild";
+import type { Bot } from "mineflayer";
+import { createLogger } from "./logger";
 
 async function compileToJS(filepath: string) {
 	const result = await esbuild.build({
@@ -11,13 +14,13 @@ async function compileToJS(filepath: string) {
 		platform: "node",
 		format: "esm",
 		target: "es2022",
-		loader: { ".ts": "ts" },
+		loader: { ". ts": "ts" },
 		external: ["mineflayer"],
 		logLevel: "silent",
 	});
 
 	const jsCode = result.outputFiles[0].text;
-	const jsFilePath = filepath.replace(/\.ts$/, ".macro.mjs");
+	const jsFilePath = filepath.replace(/\.ts$/, ". macro.mjs");
 	await fs.writeFile(jsFilePath, jsCode);
 
 	return jsFilePath;
@@ -45,21 +48,31 @@ async function fileExists(filepath: string) {
 	}
 }
 
-export async function loadAndRunMacro(filepath: string, ctx: MacroContext) {
+function getMacroName(filepath: string) {
+	return path.basename(filepath).replace(/\.(ts|js|mjs)$/, "");
+}
+
+export async function loadAndRunMacro(
+	filepath: string,
+	bot: Bot,
+	rl?: Interface,
+) {
 	const absolutePath = resolveMacroPath(filepath);
 	let importPath = absolutePath;
 	let compiledPath: string = null;
 
+	const logger = createLogger(rl, `macro/${getMacroName(filepath)}`);
+
 	try {
 		if (!(await fileExists(absolutePath))) {
-			ctx.logger.error(`macro file not found: ${absolutePath}`);
+			logger.error(`file not found: ${absolutePath}`);
 			return false;
 		}
 
 		const isTypescriptFile = absolutePath.endsWith(".ts");
 
 		if (isTypescriptFile) {
-			ctx.logger.log("compiling typescript macro");
+			logger.log("compiling macro to js");
 			compiledPath = await compileToJS(absolutePath);
 			importPath = compiledPath;
 		}
@@ -68,14 +81,16 @@ export async function loadAndRunMacro(filepath: string, ctx: MacroContext) {
 		const module = (await import(fileUrl)) as MacroModule;
 
 		if (typeof module.default !== "function") {
-			ctx.logger.error("macro file must export a default function");
+			logger.error("macro file must export a default function");
 			return false;
 		}
 
-		await module.default(ctx);
+		logger.log("running");
+		await module.default({ bot, logger });
+		logger.log("finished");
 		return true;
 	} catch (err) {
-		ctx.logger.error(`could not load macro: ${(err as Error).message}`);
+		logger.error(`failed: ${(err as Error).message}`);
 		return false;
 	} finally {
 		if (compiledPath) {

package/src/repl.ts

@@ -0,0 +1,137 @@
+import * as readline from "node:readline";
+import type { Config, DelayableCommands } from "@mincraft/types";
+import chalk from "chalk";
+import { version } from ".";
+import { BotClient } from "./bot";
+import { createLogger } from "./logger";
+import { loadAndRunMacro } from "./macro";
+
+export enum BotCommand {
+	Exit = ".exit",
+	Logout = ".lo",
+	Login = ".li",
+	Macro = ".macro",
+	Help = ".help",
+}
+
+function isCommand(value: string) {
+	return Object.values(BotCommand).some((cmd) => value.startsWith(cmd));
+}
+
+function showReplHelp(log: (msg: string) => void, serverHost: string) {
+	log(`type ${chalk.magenta(".li")} to log in to ${serverHost}`);
+	log(`type ${chalk.magenta(".lo")} to log out from ${serverHost}`);
+	log(`type ${chalk.magenta(".macro <filepath>")} to run a macro`);
+	log(`type ${chalk.magenta(".help")} to show this REPL reference`);
+	log(`type ${chalk.magenta(".exit")} to exit the REPL`);
+	log(`type ${chalk.bold("any other value")} to send a message to the server`);
+}
+
+export async function run(config: Config, commands?: DelayableCommands) {
+	process.stdout.write("\u001b[2J\u001b[2;0H");
+	let bot: BotClient = null;
+
+	const rl = readline.createInterface({
+		input: process.stdin,
+		output: process.stdout,
+	});
+
+	const logger = createLogger(rl);
+	const helpLogger = (msg: string) => logger.raw(`>> ${msg}`);
+
+	rl.setPrompt("> ");
+
+	const handleInput = async (input: string) => {
+		input = input.trim();
+
+		if (!input) {
+			return false;
+		}
+
+		if (!isCommand(input) && !bot?.isLoggedIn) {
+			logger.error("log in using .li before sending messages");
+			return false;
+		}
+
+		if (isCommand(input)) {
+			const [cmd, ...args] = input.split(" ");
+
+			switch (cmd) {
+				case BotCommand.Exit: {
+					bot?.disconnect();
+					rl.close();
+					return true;
+				}
+				case BotCommand.Login: {
+					if (bot?.isLoggedIn) {
+						logger.error("client is already logged in");
+					} else {
+						bot = new BotClient(config, logger);
+						bot.registerAndLogIn();
+					}
+					break;
+				}
+				case BotCommand.Logout: {
+					if (!bot?.isLoggedIn) {
+						logger.error("client isn't logged in");
+					} else {
+						bot?.disconnect();
+					}
+					break;
+				}
+				case BotCommand.Macro: {
+					if (!bot?.isLoggedIn) {
+						logger.error("client must be logged in to run macros");
+						break;
+					}
+					const filepath = args.join(" ");
+					if (!filepath) {
+						logger.error("usage: .macro <filepath>");
+						break;
+					}
+					const mineflayer = bot.bot;
+					if (mineflayer) {
+						await loadAndRunMacro(filepath, mineflayer, rl);
+					}
+					break;
+				}
+				case BotCommand.Help: {
+					showReplHelp(helpLogger, config.server.host);
+					break;
+				}
+			}
+		} else {
+			bot?.sendMessage(input);
+		}
+
+		return false;
+	};
+
+	rl.on("line", async (input) => {
+		const shouldExit = await handleInput(input);
+		if (shouldExit) {
+			process.exit(0);
+		}
+		rl.prompt();
+	});
+
+	console.log(chalk.green(`mincraft REPL ${version}`));
+	helpLogger('type ".help" for more information.');
+
+	if (commands && commands.length > 0) {
+		for (const { command, delay } of commands) {
+			if (delay > 0) {
+				await new Promise((resolve) => setTimeout(resolve, delay));
+			}
+			if (command) {
+				logger.raw(`> ${command}`);
+				const shouldExit = await handleInput(command);
+				if (shouldExit) {
+					process.exit(0);
+				}
+			}
+		}
+	}
+
+	rl.prompt();
+}

package/src/runner.ts

@@ -1,106 +0,0 @@
-import * as readline from "node:readline";
-import type { Config } from "@mincraft/types";
-import { BotClient } from "./bot";
-import { createLogger } from "./logger";
-import { loadAndRunMacro } from "./macro";
-
-export enum BotCommand {
-	Exit = ".exit",
-	Logout = ".lo",
-	Login = ".li",
-	Macro = ".macro",
-}
-
-function isCommand(value: string) {
-	return Object.values(BotCommand).some((cmd) => value.startsWith(cmd));
-}
-
-export async function run(config: Config) {
-	let bot: BotClient | null = null;
-
-	const rl = readline.createInterface({
-		input: process.stdin,
-		output: process.stdout,
-	});
-
-	const logger = createLogger(rl);
-
-	rl.setPrompt("> ");
-
-	const handleInput = async (input: string) => {
-		input = input.trim();
-
-		if (!isCommand(input) && !bot?.isLoggedIn) {
-			logger.raw("log in using .li before sending messages");
-			rl.prompt();
-			return;
-		}
-
-		if (isCommand(input)) {
-			const [cmd, ...args] = input.split(" ");
-			let exit = false;
-
-			switch (cmd) {
-				case BotCommand.Exit: {
-					bot?.disconnect();
-					rl.close();
-					exit = true;
-					break;
-				}
-				case BotCommand.Login: {
-					if (bot?.isLoggedIn) {
-						logger.error("client is already logged in");
-					} else {
-						bot = new BotClient(config, logger);
-						bot.registerAndLogIn();
-					}
-					break;
-				}
-				case BotCommand.Logout: {
-					if (!bot?.isLoggedIn) {
-						logger.error("client isn't logged in");
-					} else {
-						bot?.disconnect();
-					}
-					break;
-				}
-				case BotCommand.Macro: {
-					if (!bot?.isLoggedIn) {
-						logger.error("client must be logged in to run macros");
-						break;
-					}
-					const filepath = args.join(" ");
-					if (!filepath) {
-						logger.error("usage: .macro <filepath>");
-						break;
-					}
-					const mineflayer = bot.bot;
-					if (mineflayer) {
-						logger.log(`loading macro: ${filepath}`);
-						await loadAndRunMacro(filepath, { bot: mineflayer, logger });
-					}
-					break;
-				}
-			}
-
-			if (exit) {
-				process.exit(0);
-			}
-		} else {
-			bot?.sendMessage(input);
-		}
-
-		rl.prompt();
-	};
-
-	rl.on("line", handleInput);
-
-	console.log("=== mincraft REPL ===");
-	console.log("input plain text to send a message to the server");
-	console.log(`input .li to log in to ${config.server.host}`);
-	console.log(`input .lo to log out from ${config.server.host}`);
-	console.log("input .macro <filepath> to run a macro");
-	console.log("input .exit to exit the REPL");
-
-	rl.prompt();
-}