@unbound-app/debugger 0.4.0 → 0.7.0

package/dist/index.mjs

@@ -8,6 +8,7 @@ import { cli } from "cleye";
 const HISTORY_PATH = join(__dirname, "..", "..", ".history.json");
 const HISTORY_FILE = Bun.file(HISTORY_PATH);
 let history = [];
+/** @description Loads the persisted REPL history from disk, if present. */
 async function loadHistory() {
 	try {
 		if (await HISTORY_FILE.exists()) history = await HISTORY_FILE.json();
@@ -15,10 +16,12 @@ async function loadHistory() {
 		terminal.red.bold(`Failed to load history.\n`);
 	}
 }
+/** @description Appends an entry to the REPL history and persists it. */
 function addHistoryItem(item) {
 	history.push(item);
 	persistHistory();
 }
+/** @description Writes the REPL history to disk. */
 function persistHistory() {
 	HISTORY_FILE.write(JSON.stringify(history, null, 2));
 }
@@ -37,6 +40,7 @@ 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.
@@ -123,7 +127,7 @@ function evaluateForController(socket, id, code) {
 /**
 * @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 EVAL_TIMEOUT_MS}.
+* error frame instead if no device is connected or it doesn't answer within {@link PLUGIN_PUSH_TIMEOUT_MS}.
 * @param socket The controller that issued the push.
 * @param request The push to forward verbatim; its `id` correlates the result.
 */
@@ -144,9 +148,9 @@ function pushPluginForController(socket, request) {
 			type: "plugin-push-result",
 			id: request.id,
 			ok: false,
-			error: `Plugin push timed out after ${EVAL_TIMEOUT_MS}ms.`
+			error: `Plugin push timed out after ${PLUGIN_PUSH_TIMEOUT_MS}ms.`
 		});
-	}, EVAL_TIMEOUT_MS);
+	}, PLUGIN_PUSH_TIMEOUT_MS);
 	pendingPushes.set(request.id, {
 		deliver,
 		timer,
@@ -217,29 +221,41 @@ function handleDeviceMessage$1(message) {
 		entry.deliver(message);
 		return;
 	}
-	if (message.type === "log") {
-		for (const socket of state$2.controllers) socket.send(JSON.stringify(message));
-		for (const listener of logListeners) listener(message);
-	}
+	if (message.type !== "log") return;
+	for (const socket of state$2.controllers) socket.send(JSON.stringify(message));
+	for (const listener of logListeners) listener(message);
 }
-/** @description Subscribes to device log lines; returns an unsubscribe function. */
+/**
+* @description Subscribes to device log lines.
+* @param listener Called with each log line.
+* @returns An unsubscribe function.
+*/
 function onLog(listener) {
 	logListeners.add(listener);
 	return () => void logListeners.delete(listener);
 }
-/** @description Subscribes to code a controller (e.g. the MCP) sends to evaluate; returns an unsubscribe function. */
+/**
+* @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.
+*/
 function onControllerEval(listener) {
 	evalListeners.add(listener);
 	return () => void evalListeners.delete(listener);
 }
-/** @description Subscribes to the results of controller evals; returns an unsubscribe function. */
+/**
+* @description Subscribes to the results of controller evals.
+* @param listener Called with each controller eval's result.
+* @returns An unsubscribe function.
+*/
 function onControllerResult(listener) {
 	resultListeners.add(listener);
 	return () => void resultListeners.delete(listener);
 }
 /**
-* @description Subscribes to controller (MCP) connect/disconnect transitions, with the resulting
-* controller count; returns an unsubscribe function.
+* @description Subscribes to controller (MCP) connect/disconnect transitions.
+* @param listener Called with the transition and the resulting controller count.
+* @returns An unsubscribe function.
 */
 function onController(listener) {
 	controllerListeners.add(listener);
@@ -269,12 +285,14 @@ const state$1 = {
 	repl: null,
 	currentInput: ""
 };
+/** @description Exits the debugger on Ctrl+C. */
 function setupReplListeners() {
-	terminal.on("key", (name, ...t) => {
+	terminal.on("key", (name) => {
 		if (name !== "CTRL_C") return;
 		process.exit(0);
 	});
 }
+/** @description Draws a fresh prompt and evaluates the submitted line on the device. */
 async function takeReplInput() {
 	abortCurrentReplInput();
 	terminal.bold.cyan("» ");
@@ -296,27 +314,17 @@ async function takeReplInput() {
 	});
 	await state$1.repl.promise;
 }
+/** @description Cancels the active prompt, optionally erasing it and the pending input. */
 function abortCurrentReplInput({ deletePrompt = false, deleteCurrentInput = false } = {}) {
-	if (state$1.repl) {
-		state$1.repl.abort();
-		state$1.repl = null;
-		if (deletePrompt) terminal.deleteLine(-1);
-		if (deleteCurrentInput) state$1.currentInput = "";
-	}
+	if (!state$1.repl) return;
+	state$1.repl.abort();
+	state$1.repl = null;
+	if (deletePrompt) terminal.deleteLine(-1);
+	if (deleteCurrentInput) state$1.currentInput = "";
 }
 //#endregion
 //#region src/lib/format-log.ts
 /**
-* Reformats a log line as Hermes hands it to `nativeLoggingHook`. Hermes inspects each `console.*`
-* argument and joins them with `, ` — quoting string args (`'a', 'b', { x: 1 }`). That reads badly
-* in the debugger terminal, so we split on the top-level commas Hermes inserted, unquote the plain
-* string segments, and rejoin with spaces — leaving inspected objects/arrays untouched.
-*
-* This is best-effort: it only rewrites what parses cleanly as Hermes's join format. A segment it
-* can't confidently classify is left exactly as received, so worst case a line is unchanged, never
-* mangled.
-*/
-/**
 * @description Cleans a Hermes-joined console line into space-separated, unquoted output.
 * @param message The raw `nativeLoggingHook` message string.
 * @returns The reformatted line, or the original if it doesn't look like a Hermes join.
@@ -379,9 +387,8 @@ function unquoteSegment(segment) {
 //#endregion
 //#region src/lib/banner.ts
 /**
-* Renders the debugger's startup banner: a rounded box, tinted in the brand pink, that adapts to the
-* terminal's width. The box shrinks to fit narrow terminals and caps at a comfortable reading width
-* on wide ones; when the terminal is too narrow for a box, it falls back to plain starred lines.
+* 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.
 */
 /** Brand pink used for the banner frame and title. */
 const PINK = "#ff5fbf";
@@ -449,7 +456,7 @@ function printFallback(title, lines) {
 /** The usable terminal width: terminal-kit's when it's a real TTY, else stdout's, else a default. */
 function terminalWidth() {
 	const fromKit = terminal.width;
-	if (typeof fromKit === "number" && Number.isFinite(fromKit)) return fromKit;
+	if (Number.isFinite(fromKit)) return fromKit;
 	const fromStdout = process.stdout.columns;
 	if (typeof fromStdout === "number" && fromStdout > 0) return fromStdout;
 	return 80;
@@ -493,9 +500,7 @@ const SYSTEM_COLORS = {
 	gray: "#9ca3af"
 };
 /**
-* @description Prints a bold, glyph-prefixed banner line for a bridge lifecycle event, tinted with
-* the given hex colour. Uses terminal-kit's runtime `colorRgbHex`, which `@types/terminal-kit`
-* doesn't declare, so the chain is reached through a narrow cast.
+* @description Prints a bold, glyph-prefixed banner line for a bridge lifecycle event.
 * @param color The banner colour, keyed into {@link SYSTEM_COLORS}.
 * @param text The line to print (the glyph is prepended and a trailing newline added).
 */
@@ -594,6 +599,10 @@ function handleControllerMessage(ws, raw) {
 	}
 	if (message?.type === "plugin-push") pushPluginForController(ws, message);
 }
+/**
+* @description Finds the machine's first external IPv4 address, for devices on the LAN to dial.
+* @returns The address, or `undefined` if the machine has none.
+*/
 function getLocalAddress() {
 	const interfaces = os.networkInterfaces();
 	for (const ifaces of Object.values(interfaces)) {
@@ -604,6 +613,6 @@ function getLocalAddress() {
 //#endregion
 //#region src/index.ts
 await loadHistory();
-await setupWebSocket();
+setupWebSocket();
 //#endregion
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@unbound-app/debugger",
-	"version": "0.4.0",
+	"version": "0.7.0",
 	"description": "A REPL debugger for @unbound-app/client runtime instances.",
 	"author": {
 		"name": "Mario P.",
@@ -24,7 +24,7 @@
 		"build": "tsdown"
 	},
 	"dependencies": {
-		"@unbound-app/debugger-protocol": "0.4.0",
+		"@unbound-app/debugger-protocol": "0.7.0",
 		"cleye": "^1.3.4",
 		"terminal-kit": "^3.1.2"
 	},