@sxl-studio/bridge 1.2.0

package/dist/types.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Shared types for the Bridge server.
+ */
+export type CommandStatus = "pending" | "running" | "completed" | "failed" | "timeout" | "cancelled";
+export type BridgeCommand = {
+    commandId: string;
+    commandType: string;
+    payload: Record<string, unknown>;
+    status: CommandStatus;
+    createdAt: number;
+    startedAt?: number;
+    completedAt?: number;
+    result?: unknown;
+    error?: string;
+    events?: unknown[];
+    durationMs?: number;
+    resolve?: (result: CommandResult) => void;
+};
+export type CommandResult = {
+    commandId: string;
+    status: CommandStatus;
+    result?: unknown;
+    error?: string;
+    events?: unknown[];
+    durationMs?: number;
+};
+export type SessionInfo = {
+    connected: boolean;
+    pluginName: string | null;
+    connectedAt: number | null;
+    lastHeartbeat: number | null;
+};
+export type BridgeStatus = {
+    /** Single port: plugin WebSocket, HTTP REST, and MCP `/mcp` (same numeric value twice for older clients). */
+    ports: {
+        websocket: number;
+        http: number;
+    };
+    /** Cursor / MCP clients: Streamable HTTP endpoint (same host as REST, path `/mcp`). */
+    mcpStreamableHttp: string;
+    session: SessionInfo;
+    queueLength: number;
+    currentCommand: string | null;
+};

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * Shared types for the Bridge server.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/ws-server.d.ts

@@ -0,0 +1,31 @@
+/**
+ * WebSocket server for Bridge.
+ *
+ * Accepts a single plugin connection. Receives commands from the CommandQueue
+ * and forwards results back from the plugin.
+ *
+ * Shares one HTTP server with REST + MCP (see http-api.ts): same BRIDGE_PORT for
+ * `ws://127.0.0.1:PORT` upgrades and `http://127.0.0.1:PORT/api/*`, `/mcp`.
+ */
+import type { Server } from "node:http";
+import { CommandQueue } from "./command-queue.js";
+import { SessionManager } from "./session.js";
+export declare class BridgeWSServer {
+    private wss;
+    private httpServer;
+    private pluginSocket;
+    readonly commandQueue: CommandQueue;
+    readonly session: SessionManager;
+    /**
+     * Attach plugin WebSocket handling to an existing HTTP server (same port as REST + MCP).
+     */
+    attachToHttpServer(httpServer: Server): void;
+    /**
+     * Drop the plugin WebSocket, clear session, and cancel queued commands.
+     * Used after heartbeat timeout, HTTP POST /api/disconnect, or manual recovery.
+     */
+    disconnectPluginSocket(code: number, reason: string): void;
+    private sendToPlugin;
+    private handlePluginMessage;
+    stop(): void;
+}

package/dist/ws-server.js

@@ -0,0 +1,120 @@
+/**
+ * WebSocket server for Bridge.
+ *
+ * Accepts a single plugin connection. Receives commands from the CommandQueue
+ * and forwards results back from the plugin.
+ *
+ * Shares one HTTP server with REST + MCP (see http-api.ts): same BRIDGE_PORT for
+ * `ws://127.0.0.1:PORT` upgrades and `http://127.0.0.1:PORT/api/*`, `/mcp`.
+ */
+import { WebSocketServer, WebSocket } from "ws";
+import { CommandQueue } from "./command-queue.js";
+import { SessionManager } from "./session.js";
+export class BridgeWSServer {
+    wss = null;
+    httpServer = null;
+    pluginSocket = null;
+    commandQueue = new CommandQueue();
+    session = new SessionManager();
+    /**
+     * Attach plugin WebSocket handling to an existing HTTP server (same port as REST + MCP).
+     */
+    attachToHttpServer(httpServer) {
+        this.httpServer = httpServer;
+        this.commandQueue.setSender((cmd) => this.sendToPlugin(cmd));
+        this.session.onDisconnect(() => {
+            this.disconnectPluginSocket(4002, "Heartbeat timeout");
+        });
+        this.wss = new WebSocketServer({ server: httpServer });
+        this.wss.on("error", (err) => {
+            console.error("[WS] WebSocketServer error:", err.message);
+        });
+        this.wss.on("connection", (ws) => {
+            if (this.pluginSocket) {
+                ws.close(4001, "Only one plugin connection allowed");
+                return;
+            }
+            this.pluginSocket = ws;
+            const addr = httpServer.address();
+            const port = addr && typeof addr === "object" ? addr.port : "?";
+            console.error(`[WS] Plugin connected (ws://127.0.0.1:${port})`);
+            ws.on("message", (data) => {
+                try {
+                    const msg = JSON.parse(data.toString());
+                    this.handlePluginMessage(msg);
+                }
+                catch {
+                    console.warn("[WS] Failed to parse plugin message");
+                }
+            });
+            ws.on("close", () => {
+                console.error("[WS] Plugin disconnected");
+                if (this.pluginSocket === ws) {
+                    this.pluginSocket = null;
+                }
+                this.session.disconnect();
+                this.commandQueue.cancelAll();
+            });
+            ws.on("error", (err) => {
+                console.error("[WS] Plugin socket error:", err.message);
+            });
+        });
+    }
+    /**
+     * Drop the plugin WebSocket, clear session, and cancel queued commands.
+     * Used after heartbeat timeout, HTTP POST /api/disconnect, or manual recovery.
+     */
+    disconnectPluginSocket(code, reason) {
+        const sock = this.pluginSocket;
+        this.pluginSocket = null;
+        this.session.disconnect();
+        this.commandQueue.cancelAll();
+        if (sock &&
+            (sock.readyState === WebSocket.OPEN || sock.readyState === WebSocket.CONNECTING)) {
+            sock.close(code, reason);
+        }
+    }
+    sendToPlugin(data) {
+        if (!this.pluginSocket || this.pluginSocket.readyState !== WebSocket.OPEN) {
+            return false;
+        }
+        this.pluginSocket.send(JSON.stringify({ type: "command", ...data }));
+        return true;
+    }
+    handlePluginMessage(msg) {
+        switch (msg.type) {
+            case "plugin-connected":
+                this.session.connect(msg.pluginName);
+                break;
+            case "heartbeat":
+                // If the HTTP layer cleared the session but the socket stayed open (legacy bug),
+                // or /api/disconnect raced, re-attach the session so POST /api/command works again.
+                if (!this.session.connected) {
+                    this.session.connect(typeof msg.pluginName === "string" ? msg.pluginName : undefined);
+                }
+                this.session.heartbeat();
+                if (this.pluginSocket?.readyState === WebSocket.OPEN) {
+                    this.pluginSocket.send(JSON.stringify({ type: "heartbeat-ack" }));
+                }
+                break;
+            case "command-result":
+                this.commandQueue.resolveCommand(msg.commandId, msg.status, msg.result, msg.error, msg.events, msg.durationMs);
+                break;
+            case "plugin-event":
+                break;
+            default:
+                break;
+        }
+    }
+    stop() {
+        this.pluginSocket?.close();
+        this.pluginSocket = null;
+        this.session.disconnect();
+        this.commandQueue.cancelAll();
+        this.wss?.close();
+        this.wss = null;
+        this.httpServer?.close();
+        this.httpServer = null;
+    }
+}
+//# sourceMappingURL=ws-server.js.map

package/dist/ws-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws-server.js","sourceRoot":"","sources":["../src/ws-server.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@sxl-studio/bridge",
+  "version": "1.2.0",
+  "description": "MCP/HTTP bridge server for SXL Studio Figma plugin — enables remote control from IDE",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "sxl-bridge": "dist/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "ws": "^8.18.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.5.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}