@unbound-app/debugger-protocol 0.1.0

package/dist/controller.d.mts

@@ -0,0 +1,27 @@
+import { o as EvalResult } from "./index-DA_F_n3N.mjs";
+//#region src/controller.d.ts
+declare class ControllerClient {
+  private ws;
+  private readonly pending;
+  private deviceConnected;
+  private closed;
+  private readonly url;
+  constructor(url: string);
+  /** @description Opens the socket and keeps it open, reconnecting on drop until {@link close}d. */
+  connect(): void;
+  /** @description Tears the client down and fails any in-flight evals. Twin of {@link connect}. */
+  close(): void;
+  /** @description Whether a device is currently connected to the bridge. */
+  get isDeviceConnected(): boolean;
+  /**
+   * @description Sends code to the device via the bridge and resolves with its result. Fails fast
+   * if the socket isn't open or the bridge doesn't answer in time.
+   * @param code The JavaScript to evaluate on the device.
+   * @returns The device's {@link EvalResult}.
+   */
+  evaluate(code: string): Promise<EvalResult>;
+  private onMessage;
+  private onClose;
+}
+//#endregion
+export { ControllerClient };

package/dist/controller.mjs

@@ -0,0 +1,115 @@
+import { parseMessage, serializeMessage } from "./index.mjs";
+//#region src/controller.ts
+/** How long the client waits for a result before failing an eval (must exceed the bridge's own). */
+const EVAL_TIMEOUT_MS = 15e3;
+/** How long to wait between reconnection attempts when the bridge is unreachable. */
+const RECONNECT_DELAY_MS = 1e3;
+var ControllerClient = class {
+	ws = null;
+	pending = /* @__PURE__ */ new Map();
+	deviceConnected = false;
+	closed = false;
+	url;
+	constructor(url) {
+		this.url = url;
+	}
+	/** @description Opens the socket and keeps it open, reconnecting on drop until {@link close}d. */
+	connect() {
+		if (this.closed) return;
+		this.ws = new WebSocket(this.url);
+		this.ws.addEventListener("message", (event) => this.onMessage(String(event.data)));
+		this.ws.addEventListener("close", () => this.onClose());
+		this.ws.addEventListener("error", () => this.ws?.close());
+	}
+	/** @description Tears the client down and fails any in-flight evals. Twin of {@link connect}. */
+	close() {
+		this.closed = true;
+		this.ws?.close();
+		for (const [id, entry] of this.pending) {
+			clearTimeout(entry.timer);
+			entry.resolve({
+				type: "eval-result",
+				id,
+				ok: false,
+				error: "Debugger client shut down.",
+				logs: entry.logs
+			});
+		}
+		this.pending.clear();
+	}
+	/** @description Whether a device is currently connected to the bridge. */
+	get isDeviceConnected() {
+		return this.deviceConnected;
+	}
+	/**
+	* @description Sends code to the device via the bridge and resolves with its result. Fails fast
+	* if the socket isn't open or the bridge doesn't answer in time.
+	* @param code The JavaScript to evaluate on the device.
+	* @returns The device's {@link EvalResult}.
+	*/
+	evaluate(code) {
+		const id = crypto.randomUUID();
+		return new Promise((resolve) => {
+			if (this.ws?.readyState !== WebSocket.OPEN) {
+				resolve({
+					type: "eval-result",
+					id,
+					ok: false,
+					error: "Not connected to the debugger bridge."
+				});
+				return;
+			}
+			const logs = [];
+			const timer = setTimeout(() => {
+				this.pending.delete(id);
+				resolve({
+					type: "eval-result",
+					id,
+					ok: false,
+					error: `Evaluation timed out after ${EVAL_TIMEOUT_MS}ms.`,
+					logs
+				});
+			}, EVAL_TIMEOUT_MS);
+			this.pending.set(id, {
+				resolve,
+				timer,
+				logs
+			});
+			this.ws.send(serializeMessage({
+				type: "eval",
+				id,
+				code
+			}));
+		});
+	}
+	onMessage(raw) {
+		const message = parseMessage(raw);
+		if (!message) return;
+		if (message.type === "device-status") {
+			this.deviceConnected = message.connected;
+			return;
+		}
+		if (message.type === "log") {
+			for (const entry of this.pending.values()) entry.logs.push(message);
+			return;
+		}
+		if (message.type === "eval-result") {
+			const entry = this.pending.get(message.id);
+			if (!entry) return;
+			clearTimeout(entry.timer);
+			this.pending.delete(message.id);
+			entry.resolve({
+				...message,
+				logs: entry.logs
+			});
+		}
+	}
+	onClose() {
+		this.ws = null;
+		this.deviceConnected = false;
+		if (this.closed) return;
+		setTimeout(() => this.connect(), RECONNECT_DELAY_MS);
+	}
+};
+//#endregion
+export { ControllerClient };

package/dist/index-DA_F_n3N.d.mts

@@ -0,0 +1,75 @@
+//#region src/index.d.ts
+/**
+ * The wire protocol shared by the bridge, the on-device debugger, and any controller (the terminal
+ * REPL or an MCP client). Everything crossing a socket is a JSON-encoded {@link BridgeMessage}.
+ *
+ * Two planes travel over the single device socket:
+ *   - control: a controller issues an {@link EvalRequest}; the device answers with the matching
+ *     {@link EvalResult} (correlated by `id`).
+ *   - telemetry: the device streams {@link LogMessage}s, broadcast to every controller.
+ *
+ * Device-safe and dependency-free so it can be bundled into the React Native client.
+ */
+/** A request to evaluate code on the device, sent controller → bridge → device. */
+interface EvalRequest {
+  type: 'eval';
+  /** Correlation id echoed back on the matching {@link EvalResult}. */
+  id: string;
+  code: string;
+}
+/** The outcome of an {@link EvalRequest}, sent device → bridge → the one waiting controller. */
+interface EvalResult {
+  type: 'eval-result';
+  /** The `id` of the {@link EvalRequest} this answers. */
+  id: string;
+  ok: boolean;
+  /** Present when `ok`; the inspected return value. */
+  value?: string;
+  /** Present when `!ok`; the inspected error. */
+  error?: string;
+  /**
+   * Console output captured on the device for the duration of this eval, so a caller sees the
+   * side effects (`console.log`s) the code produced, not just its return value. Populated by the
+   * controller that owns the request, not sent by the device.
+   */
+  logs?: LogMessage[];
+}
+/** A `console.*` / `nativeLoggingHook` line, streamed device → bridge → all controllers. */
+interface LogMessage {
+  type: 'log';
+  /** 1 = log/gray, 2 = warn/yellow, 3 = error/red. */
+  level: 1 | 2 | 3;
+  message: string;
+}
+/** Bridge → controller, once on attach and whenever the device connects or drops. */
+interface DeviceStatus {
+  type: 'device-status';
+  connected: boolean;
+}
+/** Every framed message on the wire. */
+type BridgeMessage = EvalRequest | EvalResult | LogMessage | DeviceStatus;
+/** The default port the bridge listens on and controllers dial. */
+declare const DEFAULT_BRIDGE_PORT = 9090;
+/** The query marker a controller appends to its URL so the bridge routes it as a controller, not a device. */
+declare const CONTROLLER_ENDPOINT_MARKER = "mcp";
+/**
+ * @description Safely parses a raw wire frame into a {@link BridgeMessage}, guarding against invalid
+ * JSON and unknown shapes so both ends can trust what they route.
+ * @param raw The JSON string received off the socket.
+ * @returns The parsed message, or `undefined` if it isn't a recognised frame.
+ */
+declare function parseMessage(raw: string): BridgeMessage | undefined;
+/**
+ * @description Serialises a {@link BridgeMessage} into its wire form. Inverse of {@link parseMessage}.
+ * @param message The message to frame.
+ * @returns The JSON string to send over the socket.
+ */
+declare function serializeMessage(message: BridgeMessage): string;
+declare const _default: {
+  DEFAULT_BRIDGE_PORT: number;
+  CONTROLLER_ENDPOINT_MARKER: string;
+  parseMessage: typeof parseMessage;
+  serializeMessage: typeof serializeMessage;
+};
+//#endregion
+export { EvalRequest as a, _default as c, DeviceStatus as i, parseMessage as l, CONTROLLER_ENDPOINT_MARKER as n, EvalResult as o, DEFAULT_BRIDGE_PORT as r, LogMessage as s, BridgeMessage as t, serializeMessage as u };

package/dist/index.d.mts

@@ -0,0 +1,2 @@
+import { a as EvalRequest, c as _default, i as DeviceStatus, l as parseMessage, n as CONTROLLER_ENDPOINT_MARKER, o as EvalResult, r as DEFAULT_BRIDGE_PORT, s as LogMessage, t as BridgeMessage, u as serializeMessage } from "./index-DA_F_n3N.mjs";
+export { BridgeMessage, CONTROLLER_ENDPOINT_MARKER, DEFAULT_BRIDGE_PORT, DeviceStatus, EvalRequest, EvalResult, LogMessage, _default as default, parseMessage, serializeMessage };

package/dist/index.mjs

@@ -0,0 +1,45 @@
+//#region src/index.ts
+/** The default port the bridge listens on and controllers dial. */
+const DEFAULT_BRIDGE_PORT = 9090;
+/** The query marker a controller appends to its URL so the bridge routes it as a controller, not a device. */
+const CONTROLLER_ENDPOINT_MARKER = "mcp";
+const MESSAGE_TYPES = /* @__PURE__ */ new Set([
+	"eval",
+	"eval-result",
+	"log",
+	"device-status"
+]);
+/**
+* @description Safely parses a raw wire frame into a {@link BridgeMessage}, guarding against invalid
+* JSON and unknown shapes so both ends can trust what they route.
+* @param raw The JSON string received off the socket.
+* @returns The parsed message, or `undefined` if it isn't a recognised frame.
+*/
+function parseMessage(raw) {
+	let value;
+	try {
+		value = JSON.parse(raw);
+	} catch {
+		return;
+	}
+	if (typeof value !== "object" || value === null) return void 0;
+	const type = value.type;
+	if (typeof type !== "string" || !MESSAGE_TYPES.has(type)) return void 0;
+	return value;
+}
+/**
+* @description Serialises a {@link BridgeMessage} into its wire form. Inverse of {@link parseMessage}.
+* @param message The message to frame.
+* @returns The JSON string to send over the socket.
+*/
+function serializeMessage(message) {
+	return JSON.stringify(message);
+}
+var src_default = {
+	DEFAULT_BRIDGE_PORT,
+	CONTROLLER_ENDPOINT_MARKER: "mcp",
+	parseMessage,
+	serializeMessage
+};
+//#endregion
+export { CONTROLLER_ENDPOINT_MARKER, DEFAULT_BRIDGE_PORT, src_default as default, parseMessage, serializeMessage };

package/dist/registry.d.mts

@@ -0,0 +1,37 @@
+import { ControllerClient } from "./controller.mjs";
+import { z } from "zod";
+//#region src/registry.d.ts
+/**
+ * A single command definition is the one source both surfaces derive from: the CLI adapter builds
+ * flags and positionals from its schema, the MCP adapter uses the schema as the tool's input schema.
+ * Defining a command once keeps the two surfaces structurally in parity.
+ */
+/** The shared runtime a command handler runs against: the bridge controller it evaluates through. */
+type CommandContext = {
+  client: ControllerClient;
+};
+/** What a command handler returns: a success flag, human-readable text, and optional structured data. */
+type CommandOutput = {
+  ok: boolean;
+  text: string;
+  data?: unknown;
+};
+/** A command usable from both the CLI and (when opted in) the MCP server. */
+type CommandDefinition<S extends z.ZodObject<z.ZodRawShape>> = {
+  name: string;
+  description: string;
+  /** MCP ⊂ CLI: every MCP action is a CLI command; not every CLI command is an MCP tool. */
+  surfaces: {
+    cli: true;
+    mcp: boolean;
+  };
+  /** Used directly as the MCP inputSchema; the CLI adapter derives flags from its fields. */
+  schema: S;
+  /** Which schema fields the CLI presents as positionals; the rest become flags. */
+  cli?: {
+    positionals?: (keyof z.infer<S>)[];
+  };
+  handler: (input: z.infer<S>, context: CommandContext) => Promise<CommandOutput>;
+};
+//#endregion
+export { CommandContext, CommandDefinition, CommandOutput };

package/dist/registry.mjs

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,41 @@
+{
+	"name": "@unbound-app/debugger-protocol",
+	"version": "0.1.0",
+	"description": "The wire protocol and controller client shared by the debugger bridge, the on-device client, and the CLI.",
+	"author": {
+		"name": "Mario P.",
+		"email": "contact@marioparaschiv.com",
+		"url": "https://github.com/marioparaschiv"
+	},
+	"files": [
+		"dist"
+	],
+	"type": "module",
+	"types": "./dist/index.d.mts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.mts",
+			"import": "./dist/index.mjs"
+		},
+		"./controller": {
+			"types": "./dist/controller.d.mts",
+			"import": "./dist/controller.mjs"
+		},
+		"./registry": {
+			"types": "./dist/registry.d.mts",
+			"import": "./dist/registry.mjs"
+		}
+	},
+	"scripts": {
+		"build": "tsdown"
+	},
+	"dependencies": {
+		"zod": "^4.0.0"
+	},
+	"devDependencies": {
+		"tsdown": "^0.22.9"
+	},
+	"peerDependencies": {
+		"typescript": "^5.9.3"
+	}
+}