@unbound-app/debugger 1.0.0

package/TODO.md

@@ -0,0 +1,2 @@
+- Add this as an installable global binary.
+- .help, .clearhistory, etc.

package/package.json

@@ -0,0 +1,21 @@
+{
+	"name": "@unbound-app/debugger",
+	"description": "A REPL debugger for @unbound-app instances.",
+	"version": "1.0.0",
+	"module": "src/index.ts",
+	"type": "module",
+	"bin": {
+		"ub-debugger": "src/index.ts"
+	},
+	"devDependencies": {
+		"@types/bun": "latest",
+		"@types/terminal-kit": "^2.5.7"
+	},
+	"peerDependencies": {
+		"typescript": "^5"
+	},
+	"dependencies": {
+		"cleye": "^1.3.4",
+		"terminal-kit": "^3.1.2"
+	}
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+import { loadHistory } from './lib/history';
+import { setupWebSocket } from './lib/ws';
+
+
+await loadHistory();
+await setupWebSocket();

package/src/lib/cli.ts

@@ -0,0 +1,15 @@
+import { cli } from 'cleye';
+
+
+const argv = cli({
+	name: 'ub-debugger',
+	flags: {
+		port: {
+			type: Number,
+			description: 'The port number to host the debugger on.',
+			default: 9090
+		}
+	}
+});
+
+export default argv;

package/src/lib/history.ts

@@ -0,0 +1,29 @@
+import { terminal } from 'terminal-kit';
+import { join } from 'node:path';
+
+
+type History = string[];
+
+const HISTORY_PATH = join(__dirname, '..', '..', '.history.json');
+const HISTORY_FILE = Bun.file(HISTORY_PATH);
+
+export let history: History = [];
+
+export async function loadHistory() {
+	try {
+		if (await HISTORY_FILE.exists()) {
+			history = await HISTORY_FILE.json();
+		}
+	} catch (error) {
+		terminal.red.bold(`Failed to load history.\n`);
+	}
+}
+
+export function addHistoryItem(item: string) {
+	history.push(item);
+	persistHistory();
+}
+
+export function persistHistory() {
+	HISTORY_FILE.write(JSON.stringify(history, null, 2));
+}

package/src/lib/repl.ts

@@ -0,0 +1,47 @@
+import { terminal } from 'terminal-kit';
+
+import { addHistoryItem, history } from './history';
+import { send } from './ws';
+
+
+export const state: {
+	repl: ReturnType<typeof terminal.inputField> | null;
+} = {
+	repl: null
+};
+
+export function setupReplListeners() {
+	terminal.on('key', (name: string) => {
+		if (name !== 'CTRL_C') return;
+		process.exit(0);
+	});
+}
+
+export async function takeReplInput() {
+	abortCurrentReplInput();
+
+	terminal.bold.cyan('» ');
+
+	state.repl = terminal.inputField({
+		minLength: 1,
+		history
+	}, (error, input) => {
+		if (error) return console.error(error);
+		if (!input) return;
+
+		abortCurrentReplInput(true);
+		terminal.white.bold(`» ${input}\n`);
+		addHistoryItem(input);
+		send(input);
+
+		takeReplInput();
+	});
+}
+
+export function abortCurrentReplInput(shouldDeletePrompt: boolean = false) {
+	if (state.repl) {
+		state.repl.abort();
+		state.repl = null;
+		if (shouldDeletePrompt) terminal.deleteLine(-1);
+	}
+}

package/src/lib/ws.ts

@@ -0,0 +1,97 @@
+import { terminal } from 'terminal-kit';
+import os from 'node:os';
+
+import { abortCurrentReplInput, setupReplListeners, takeReplInput } from './repl';
+import argv from './cli';
+
+
+interface SocketMessage {
+	level: 1 | 2 | 3;
+	message: string;
+}
+
+export const state: {
+	isInitialized: boolean,
+	socket: Bun.ServerWebSocket | null;
+} = {
+	isInitialized: false,
+	socket: null
+};
+
+export const MESSAGE_LEVELS = {
+	1: terminal.gray,
+	2: terminal.yellow,
+	3: terminal.red
+};
+
+export function setupWebSocket() {
+	if (state.isInitialized) return;
+
+	Bun.serve({
+		port: argv.flags.port,
+		fetch(request, server) {
+			if (state.socket) {
+				return new Response(
+					JSON.stringify({ error: 'Debugger is busy.' }),
+					{ status: 503 }
+				);
+			}
+
+			server.upgrade(request);
+		},
+		websocket: {
+			open(ws) {
+				state.socket = ws;
+				terminal.bold.green('Client connected.\n');
+
+				setupReplListeners();
+				takeReplInput();
+			},
+			message(_, message: string) {
+				try {
+					const payload: SocketMessage = JSON.parse(message);
+					abortCurrentReplInput(true);
+
+					MESSAGE_LEVELS[payload.level](`« ${payload.message}\n`);
+
+					takeReplInput();
+				} catch (error) {
+					terminal.red(`Parsing failed on message from client.\n`);
+				}
+			},
+			close() {
+				state.socket = null;
+				abortCurrentReplInput(true);
+				terminal.red('Client disconnected.\n');
+			}
+		}
+	});
+
+	const localAddress = getLocalAddress();
+
+	terminal.gray(`Unbound's Debugger is now active. Connect using ${localAddress}:${argv.flags.port}\n`);
+}
+
+export function getLocalAddress() {
+	const interfaces = os.networkInterfaces();
+
+	for (const ifaces of Object.values(interfaces)) {
+		if (!ifaces) continue;
+
+		for (const iface of ifaces) {
+			// Skip over internal (i.e., 127.0.0.1) and non-IPv4 addresses
+			if (iface.family === 'IPv4' && !iface.internal) {
+				return iface.address;
+			}
+		}
+	}
+};
+
+
+export function send(...payload: Parameters<Bun.ServerWebSocket['send']>) {
+	if (!state.socket) {
+		return terminal.bold.red('You cannot send messages without a connected client.\n');
+	}
+
+	state.socket.send(...payload);
+}

package/tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  }
+}