@unbound-app/debugger 0.8.0 → 0.10.1

package/dist/index.mjs

@@ -1,10 +1,10 @@
 #!/usr/bin/env bun
 import { stripEscapeSequences, terminal } from "terminal-kit";
 import { join } from "node:path";
-import { parseMessage } from "@unbound-app/debugger-protocol";
+import { CONTROLLER_ENDPOINT_MARKER, DEFAULT_BRIDGE_PORT, DEFAULT_EVAL_TIMEOUT_MS, MAX_EVAL_TIMEOUT_MS, parseMessage } from "@unbound-app/debugger-protocol";
 import os from "node:os";
 import { cli } from "cleye";
-//#region src/lib/history.ts
+// src/lib/history.ts
 const HISTORY_PATH = join(__dirname, "..", "..", ".history.json");
 const HISTORY_FILE = Bun.file(HISTORY_PATH);
 let history = [];
@@ -25,10 +25,10 @@ function addHistoryItem(item) {
 function persistHistory() {
 	HISTORY_FILE.write(JSON.stringify(history, null, 2));
 }
-//#endregion
-//#region src/lib/session.ts
+// src/lib/session.ts
 const state$2 = {
 	device: null,
+	deviceInfo: null,
 	controllers: /* @__PURE__ */ new Set()
 };
 const pending = /* @__PURE__ */ new Map();
@@ -38,20 +38,20 @@ const deviceListeners = /* @__PURE__ */ new Set();
 const evalListeners = /* @__PURE__ */ new Set();
 const resultListeners = /* @__PURE__ */ new Set();
 const controllerListeners = /* @__PURE__ */ new Set();
-/** How long to wait for a device to answer an eval before failing it. */
-const EVAL_TIMEOUT_MS = 1e4;
 const PLUGIN_PUSH_TIMEOUT_MS = 6e4;
 /**
-* @description Registers the connected device, rejecting a second one so eval routing stays
-* unambiguous.
+* @description Registers the connected device, replacing any earlier one so a relaunched or
+* reconnecting app always takes over from a socket that died without closing.
 * @param socket The device's socket.
-* @returns Whether the device was accepted (false if one is already connected).
 */
 function attachDevice(socket) {
-	if (state$2.device) return false;
+	const previous = state$2.device;
+	if (previous) {
+		detachDevice(previous);
+		previous.close();
+	}
 	state$2.device = socket;
 	broadcastDeviceStatus(true);
-	return true;
 }
 /**
 * @description Clears the device on disconnect, notifies controllers, and fails every in-flight eval
@@ -61,6 +61,7 @@ function attachDevice(socket) {
 function detachDevice(socket) {
 	if (state$2.device !== socket) return;
 	state$2.device = null;
+	state$2.deviceInfo = null;
 	for (const [id, entry] of pending) {
 		clearTimeout(entry.timer);
 		entry.deliver({
@@ -113,18 +114,27 @@ function detachController(socket) {
 * @description Runs code on the device on behalf of a controller socket, delivering the id-correlated
 * result back over that same socket. Sends an error frame instead if no device is connected.
 * @param socket The controller that issued the request.
-* @param id The controller-chosen correlation id, echoed on the result.
-* @param code The JavaScript to evaluate on the device.
+* @param request The controller's eval, whose `id` correlates the result and whose `timeout` bounds the wait.
 */
-function evaluateForController(socket, id, code) {
+function evaluateForController(socket, request) {
+	const { id, code } = request;
 	const deliver = getControllerDelivery(socket);
 	for (const listener of evalListeners) listener(code);
-	dispatch(id, code, (result) => {
+	dispatch(id, code, resolveEvalTimeout(request.timeout), (result) => {
 		for (const listener of resultListeners) listener(result);
 		deliver(result);
 	});
 }
 /**
+* @description Picks how long an eval may run: the requested timeout when it is a positive number of
+* milliseconds, capped at {@link MAX_EVAL_TIMEOUT_MS}, otherwise {@link DEFAULT_EVAL_TIMEOUT_MS}.
+* @param requested The timeout the controller asked for, if any.
+* @returns The timeout to apply, in milliseconds.
+*/
+function resolveEvalTimeout(requested) {
+	return typeof requested === "number" && requested > 0 ? Math.min(requested, MAX_EVAL_TIMEOUT_MS) : DEFAULT_EVAL_TIMEOUT_MS;
+}
+/**
 * @description Forwards a controller's {@link PluginPushRequest} to the device and delivers the
 * id-correlated {@link PluginPushResult} back over that same controller's socket. Replies with an
 * error frame instead if no device is connected or it doesn't answer within {@link PLUGIN_PUSH_TIMEOUT_MS}.
@@ -161,16 +171,16 @@ function pushPluginForController(socket, request) {
 /**
 * @description Runs code on the device on behalf of an in-process caller (the terminal REPL),
 * resolving with the device's answer. Rejects if no device is connected or it doesn't answer within
-* {@link EVAL_TIMEOUT_MS}.
+* {@link DEFAULT_EVAL_TIMEOUT_MS}.
 * @param code The JavaScript to evaluate on the device.
 * @returns The device's {@link EvalResult}.
 */
 function evaluate(code) {
 	return new Promise((resolve) => {
-		dispatch(crypto.randomUUID(), code, resolve);
+		dispatch(crypto.randomUUID(), code, DEFAULT_EVAL_TIMEOUT_MS, resolve);
 	});
 }
-function dispatch(id, code, deliver) {
+function dispatch(id, code, timeout, deliver) {
 	if (!state$2.device) {
 		deliver({
 			type: "eval-result",
@@ -186,9 +196,9 @@ function dispatch(id, code, deliver) {
 			type: "eval-result",
 			id,
 			ok: false,
-			error: `Evaluation timed out after ${EVAL_TIMEOUT_MS}ms.`
+			error: `Evaluation timed out after ${timeout}ms.`
 		});
-	}, EVAL_TIMEOUT_MS);
+	}, timeout);
 	pending.set(id, {
 		deliver,
 		timer
@@ -221,6 +231,11 @@ function handleDeviceMessage$1(message) {
 		entry.deliver(message);
 		return;
 	}
+	if (message.type === "hello") {
+		state$2.deviceInfo = message.device;
+		broadcastDeviceStatus(true);
+		return;
+	}
 	if (message.type !== "log") return;
 	for (const socket of state$2.controllers) socket.send(JSON.stringify(message));
 	for (const listener of logListeners) listener(message);
@@ -235,6 +250,15 @@ function onLog(listener) {
 	return () => void logListeners.delete(listener);
 }
 /**
+* @description Subscribes to device connect/disconnect transitions.
+* @param listener Called with whether a device is now connected.
+* @returns An unsubscribe function.
+*/
+function onDevice(listener) {
+	deviceListeners.add(listener);
+	return () => void deviceListeners.delete(listener);
+}
+/**
 * @description Subscribes to code a controller (e.g. the MCP) sends to evaluate.
 * @param listener Called with each controller's code.
 * @returns An unsubscribe function.
@@ -270,17 +294,21 @@ function getControllerDelivery(socket) {
 	return deliver;
 }
 function sendDeviceStatus(socket, connected) {
-	socket.send(JSON.stringify({
+	const status = connected ? {
+		type: "device-status",
+		connected,
+		device: state$2.deviceInfo ?? void 0
+	} : {
 		type: "device-status",
 		connected
-	}));
+	};
+	socket.send(JSON.stringify(status));
 }
 function broadcastDeviceStatus(connected) {
 	for (const socket of state$2.controllers) sendDeviceStatus(socket, connected);
-	for (const listener of deviceListeners) listener(connected);
+	for (const listener of deviceListeners) listener(connected, state$2.deviceInfo);
 }
-//#endregion
-//#region src/lib/repl.ts
+// src/lib/repl.ts
 const state$1 = {
 	repl: null,
 	currentInput: ""
@@ -322,8 +350,7 @@ function abortCurrentReplInput({ deletePrompt = false, deleteCurrentInput = fals
 	if (deletePrompt) terminal.deleteLine(-1);
 	if (deleteCurrentInput) state$1.currentInput = "";
 }
-//#endregion
-//#region src/lib/format-log.ts
+// src/lib/format-log.ts
 /**
 * @description Cleans a Hermes-joined console line into space-separated, unquoted output.
 * @param message The raw `nativeLoggingHook` message string.
@@ -344,7 +371,7 @@ function splitTopLevel(input) {
 	let inString = false;
 	let start = 0;
 	for (let i = 0, len = input.length; i < len; i++) {
-		const char = input[i];
+		const char = input.charAt(i);
 		if (inString) {
 			if (char === "\\") {
 				i++;
@@ -384,8 +411,7 @@ function unquoteSegment(segment) {
 	if (trimmed.length < 2 || trimmed[0] !== "'" || trimmed[trimmed.length - 1] !== "'") return trimmed;
 	return trimmed.slice(1, -1).replace(/\\'/g, "'");
 }
-//#endregion
-//#region src/lib/banner.ts
+// src/lib/banner.ts
 /**
 * Renders the debugger's startup banner: a pink rounded box sized to the terminal, capped on wide
 * ones, falling back to plain starred lines when the terminal is too narrow for a box.
@@ -430,27 +456,27 @@ function rowText(line) {
 function printBox(title, lines, inner) {
 	const pad = " ".repeat(PADDING);
 	const horizontal = "─".repeat(inner + 4);
-	rgb(PINK, `╭${horizontal}╮\n`);
-	rgb(PINK, `│${pad}`);
-	boldRgb(PINK, center(title, inner));
-	rgb(PINK, `${pad}│\n`);
-	rgb(PINK, `├${horizontal}┤\n`);
+	terminal.colorRgbHex(PINK, `╭${horizontal}╮\n`);
+	terminal.colorRgbHex(PINK, `│${pad}`);
+	terminal.bold.colorRgbHex(PINK, center(title, inner));
+	terminal.colorRgbHex(PINK, `${pad}│\n`);
+	terminal.colorRgbHex(PINK, `├${horizontal}┤\n`);
 	for (const line of lines) {
 		const label = line.label.padEnd(8);
 		const filler = " ".repeat(Math.max(inner - rowText(line).length, 0));
-		rgb(PINK, `│${pad}`);
-		boldRgb(PINK, label);
-		rgb(GREY, line.value);
+		terminal.colorRgbHex(PINK, `│${pad}`);
+		terminal.bold.colorRgbHex(PINK, label);
+		terminal.colorRgbHex(GREY, line.value);
 		terminal(filler);
-		rgb(PINK, `${pad}│\n`);
+		terminal.colorRgbHex(PINK, `${pad}│\n`);
 	}
-	rgb(PINK, `╰${horizontal}╯\n`);
+	terminal.colorRgbHex(PINK, `╰${horizontal}╯\n`);
 }
 function printFallback(title, lines) {
-	boldRgb(PINK, `✦ ${title}\n`);
+	terminal.bold.colorRgbHex(PINK, `✦ ${title}\n`);
 	for (const line of lines) {
-		rgb(PINK, `  ${line.label.padEnd(8)}`);
-		rgb(GREY, `${line.value}\n`);
+		terminal.colorRgbHex(PINK, `  ${line.label.padEnd(8)}`);
+		terminal.colorRgbHex(GREY, `${line.value}\n`);
 	}
 }
 /** The usable terminal width: terminal-kit's when it's a real TTY, else stdout's, else a default. */
@@ -466,24 +492,16 @@ function center(text, width) {
 	const left = Math.floor(total / 2);
 	return " ".repeat(left) + text + " ".repeat(total - left);
 }
-function rgb(hex, text) {
-	terminal.colorRgbHex(hex, text);
-}
-function boldRgb(hex, text) {
-	terminal.bold.colorRgbHex(hex, text);
-}
-//#endregion
-//#region src/lib/cli.ts
+// src/lib/cli.ts
 const argv = cli({
 	name: "ub-debugger",
 	flags: { port: {
 		type: Number,
 		description: "The port number to host the debugger on.",
-		default: 9090
+		default: DEFAULT_BRIDGE_PORT
 	} }
 });
-//#endregion
-//#region src/lib/ws.ts
+// src/lib/ws.ts
 const state = { isInitialized: false };
 const MESSAGE_LEVELS = {
 	1: terminal.gray,
@@ -505,7 +523,24 @@ const SYSTEM_COLORS = {
 * @param text The line to print (the glyph is prepended and a trailing newline added).
 */
 function system(color, text) {
-	terminal.bold.colorRgbHex(SYSTEM_COLORS[color], `${SYSTEM_GLYPH} ${text}\n`);
+	terminal.bold.colorRgbHex(SYSTEM_COLORS[color], `${timestamp()} ${SYSTEM_GLYPH} ${text}\n`);
+}
+/**
+* @description Formats the current local time for the start of a bridge log line.
+* @param now The moment to format.
+* @returns The time as `HH:MM:SS.mmm`.
+*/
+function timestamp(now = /* @__PURE__ */ new Date()) {
+	const pad = (value, width = 2) => String(value).padStart(width, "0");
+	return `${pad(now.getHours())}:${pad(now.getMinutes())}:${pad(now.getSeconds())}.${pad(now.getMilliseconds(), 3)}`;
+}
+/**
+* @description Describes a device from its hello for the bridge log.
+* @param device What the device reported.
+* @returns A one-line summary such as `ios, Discord 351.0, loader 1.0.0, client 0.9.0`.
+*/
+function describeDevice(device) {
+	return `${device.platform}, Discord ${device.discordVersion}, loader ${device.loaderVersion}, client ${device.clientVersion}`;
 }
 /**
 * @description Boots the bridge: the phone-facing WebSocket server, the shared session routing, and
@@ -518,11 +553,10 @@ function setupWebSocket() {
 	Bun.serve({
 		port: argv.flags.port,
 		fetch(request, server) {
-			if (new URL(request.url).searchParams.has("mcp")) {
+			if (new URL(request.url).searchParams.has(CONTROLLER_ENDPOINT_MARKER)) {
 				server.upgrade(request, { data: { role: "controller" } });
 				return;
 			}
-			if (state$2.device) return new Response(JSON.stringify({ error: "A device is already connected." }), { status: 503 });
 			server.upgrade(request, { data: { role: "device" } });
 		},
 		websocket: {
@@ -543,7 +577,7 @@ function setupWebSocket() {
 					handleControllerMessage(ws, message);
 					return;
 				}
-				handleDeviceMessage(message);
+				if (ws === state$2.device) handleDeviceMessage(message);
 			},
 			close(ws) {
 				if (ws.data.role === "controller") {
@@ -561,18 +595,24 @@ function setupWebSocket() {
 	});
 	onLog((log) => {
 		abortCurrentReplInput({ deletePrompt: true });
-		MESSAGE_LEVELS[log.level](`« ${formatLog(stripEscapeSequences(log.message))}\n`);
+		MESSAGE_LEVELS[log.level](`${timestamp()} « ${formatLog(stripEscapeSequences(log.message))}\n`);
 		takeReplInput();
 	});
 	onControllerEval((code) => {
 		abortCurrentReplInput({ deletePrompt: true });
-		terminal.magenta(`» [mcp] ${code}\n`);
+		terminal.magenta(`${timestamp()} » [mcp] ${code}\n`);
 		takeReplInput();
 	});
 	onControllerResult((result) => {
 		abortCurrentReplInput({ deletePrompt: true });
-		if (result.ok) terminal.gray(`« ${result.value}\n`);
-		else terminal.red(`« ${result.error}\n`);
+		if (result.ok) terminal.gray(`${timestamp()} « ${result.value}\n`);
+		else terminal.red(`${timestamp()} « ${result.error}\n`);
+		takeReplInput();
+	});
+	onDevice((connected, device) => {
+		if (!connected || !device) return;
+		abortCurrentReplInput({ deletePrompt: true });
+		system("green", `Device identified: ${describeDevice(device)}`);
 		takeReplInput();
 	});
 	onController((connected, count) => {
@@ -581,12 +621,12 @@ function setupWebSocket() {
 		system("pink", connected ? `MCP connected - ${count} ${plural} attached` : `MCP disconnected - ${count} ${plural} attached`);
 		takeReplInput();
 	});
-	printBanner(`${getLocalAddress()}:${argv.flags.port}`, `ws://127.0.0.1:${argv.flags.port}?mcp`);
+	printBanner(`${getLocalAddress()}:${argv.flags.port}`, `ws://127.0.0.1:${argv.flags.port}?${CONTROLLER_ENDPOINT_MARKER}`);
 }
 function handleDeviceMessage(raw) {
 	const message = parseMessage(raw);
 	if (!message) {
-		system("red", "Parsing failed on message from device");
+		system("red", `Parsing failed on message from device: ${JSON.stringify(raw.slice(0, 200))}`);
 		return;
 	}
 	handleDeviceMessage$1(message);
@@ -594,7 +634,7 @@ function handleDeviceMessage(raw) {
 function handleControllerMessage(ws, raw) {
 	const message = parseMessage(raw);
 	if (message?.type === "eval") {
-		evaluateForController(ws, message.id, message.code);
+		evaluateForController(ws, message);
 		return;
 	}
 	if (message?.type === "plugin-push") pushPluginForController(ws, message);
@@ -610,9 +650,7 @@ function getLocalAddress() {
 		for (const iface of ifaces) if (iface.family === "IPv4" && !iface.internal) return iface.address;
 	}
 }
-//#endregion
-//#region src/index.ts
+// src/index.ts
 await loadHistory();
 setupWebSocket();
-//#endregion
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@unbound-app/debugger",
-	"version": "0.8.0",
+	"version": "0.10.1",
 	"description": "A REPL debugger for @unbound-app/client runtime instances.",
 	"author": {
 		"name": "Mario P.",
@@ -21,14 +21,15 @@
 	"type": "module",
 	"module": "./dist/index.mjs",
 	"scripts": {
-		"build": "tsdown"
+		"build": "tsdown",
+		"typecheck": "tsc --noEmit -p ."
 	},
 	"dependencies": {
-		"@unbound-app/debugger-protocol": "0.8.0",
-		"cleye": "^1.3.4",
-		"terminal-kit": "^3.1.2"
+		"@unbound-app/debugger-protocol": "0.11.0",
+		"cleye": "^2.7.0",
+		"terminal-kit": "^3.1.4"
 	},
 	"peerDependencies": {
-		"typescript": "^5.9.3"
+		"typescript": "^7.0.2"
 	}
 }