@atezer/figma-mcp-bridge 1.2.0 → 1.2.2

package/dist/cloudflare/core/plugin-bridge-server.js

@@ -1,9 +1,14 @@
 /**
  * Plugin Bridge WebSocket Server
  *
- * Listens for connections from the F-MCP ATezer Bridge plugin (no CDP needed).
- * When the plugin connects, MCP tools can send JSON-RPC style requests and get
- * responses (variables, execute, component, etc.).
+ * Listens on a FIXED port for connections from the F-MCP ATezer Bridge plugin
+ * (no CDP needed). Supports MULTIPLE simultaneous plugin connections
+ * (e.g. Figma Desktop + FigJam browser + Figma browser — all on one port).
+ * Each connected plugin identifies itself with a fileKey; requests are routed accordingly.
+ *
+ * Port strategy: no auto-scanning. If the configured port is busy, the server
+ * probes it to distinguish a live F-MCP instance from a stale/dead process.
+ * Stale ports get one automatic retry after a short delay.
  */
 import { WebSocketServer } from "ws";
 import { createServer, get as httpGet } from "http";
@@ -12,41 +17,84 @@ import { auditTool, auditPlugin } from "./audit-log.js";
 const HEARTBEAT_INTERVAL_MS = 3000;
 const MIN_PORT = 5454;
 const MAX_PORT = 5470;
+const STALE_PORT_RETRY_DELAY_MS = 1500;
 export class PluginBridgeServer {
     constructor(port, options) {
         this.wss = null;
         this.httpServer = null;
-        this.client = null;
-        this.clientAlive = false;
-        this.missedHeartbeats = 0;
+        this.clients = new Map();
         this.pending = new Map();
         this.requestTimeoutMs = 120000;
         this.heartbeatTimer = null;
-        this.port = port;
+        this.clientIdCounter = 0;
+        const clamped = Math.max(MIN_PORT, Math.min(MAX_PORT, port));
+        this.preferredPort = clamped;
+        this.port = clamped;
         this.auditLogPath = options?.auditLogPath;
     }
-    /**
-     * Start the WebSocket server on the configured port. Fails loudly if port is in use. Idempotent.
-     */
     start() {
         if (this.wss) {
             logger.debug({ port: this.port }, "Plugin bridge server already running");
             return;
         }
-        this.tryListen(this.port);
+        this.tryListenFixed(this.preferredPort, false);
+    }
+    generateClientId() {
+        return `client_${Date.now()}_${++this.clientIdCounter}`;
+    }
+    findClientByFileKey(fileKey) {
+        for (const client of this.clients.values()) {
+            if (client.fileKey === fileKey && client.ws.readyState === 1) {
+                return client;
+            }
+        }
+        return undefined;
+    }
+    getDefaultClient() {
+        let latest;
+        for (const client of this.clients.values()) {
+            if (client.ws.readyState !== 1)
+                continue;
+            if (!latest || client.connectedAt > latest.connectedAt) {
+                latest = client;
+            }
+        }
+        return latest;
+    }
+    resolveClient(fileKey) {
+        if (fileKey) {
+            return this.findClientByFileKey(fileKey) ?? this.getDefaultClient();
+        }
+        return this.getDefaultClient();
     }
-    checkPortConflict(port) {
+    removeClient(clientId, reason) {
+        const info = this.clients.get(clientId);
+        if (!info)
+            return;
+        this.clients.delete(clientId);
+        this.rejectPendingForClient(clientId, reason);
+        auditPlugin(this.auditLogPath, "plugin_disconnect");
+        logger.info({ clientId, fileKey: info.fileKey, fileName: info.fileName }, "Plugin bridge: client disconnected (%s)", reason);
+    }
+    /**
+     * Probe a port via HTTP to determine if a live F-MCP bridge is already
+     * running or if the port is held by a stale/dead process.
+     * Returns "fmcp" | "other" | "dead".
+     */
+    probePort(port, host) {
         return new Promise((resolve) => {
-            const req = httpGet(`http://127.0.0.1:${port}`, (res) => {
+            const req = httpGet({ hostname: host, port, path: "/", timeout: 2000 }, (res) => {
                 let body = "";
-                res.on("data", (c) => { body += c.toString(); });
-                res.on("end", () => resolve(body));
+                res.on("data", (chunk) => { body += chunk; });
+                res.on("end", () => {
+                    resolve(body.includes("F-MCP") ? "fmcp" : "other");
+                });
             });
-            req.on("error", () => resolve(null));
-            req.setTimeout(2000, () => { req.destroy(); resolve(null); });
+            req.on("error", () => resolve("dead"));
+            req.on("timeout", () => { req.destroy(); resolve("dead"); });
         });
     }
-    tryListen(port) {
+    tryListenFixed(port, isRetry) {
         const server = createServer((_req, res) => {
             res.writeHead(200, {
                 "Content-Type": "text/plain",
@@ -55,53 +103,90 @@ export class PluginBridgeServer {
             });
             res.end("F-MCP ATezer Bridge (connect via WebSocket)\n");
         });
+        const bindHost = process.env.FIGMA_BRIDGE_HOST || "127.0.0.1";
         server.on("error", (err) => {
             if (err.code === "EADDRINUSE") {
-                this.checkPortConflict(port).then((body) => {
-                    const isFmcp = body !== null && body.includes("F-MCP");
-                    const hint = process.platform === "win32"
-                        ? `netstat -ano | findstr :${port}`
-                        : `lsof -i :${port}`;
-                    if (isFmcp) {
-                        console.error(`\n❌ Port ${port} is already used by another F-MCP bridge instance.\n` +
-                            `   Find it: ${hint}\n` +
-                            `   Kill it and retry, or set FIGMA_PLUGIN_BRIDGE_PORT to a different port.\n` +
-                            `   ⚠️  Cursor/Claude starts the bridge automatically — do NOT also run 'npm run dev:local'.\n`);
+                server.close();
+                if (isRetry) {
+                    console.error(`\n❌ Port ${port} is still busy after retry.\n` +
+                        `   A process may be holding this port. Find and stop it:\n` +
+                        `     lsof -i :${port}   (macOS/Linux)\n` +
+                        `   Then restart, or set FIGMA_PLUGIN_BRIDGE_PORT to a different value (${MIN_PORT}–${MAX_PORT}).\n`);
+                    process.exit(1);
+                    return;
+                }
+                const probeHost = bindHost === "0.0.0.0" ? "127.0.0.1" : bindHost;
+                this.probePort(port, probeHost).then((status) => {
+                    if (status === "fmcp") {
+                        console.error(`\n⚠️  Port ${port} is already in use by another F-MCP bridge instance.\n` +
+                            `   One bridge is enough for all Figma/FigJam windows.\n` +
+                            `   If you need a separate session, set FIGMA_PLUGIN_BRIDGE_PORT to a different value (${MIN_PORT}–${MAX_PORT}).\n`);
+                        process.exit(1);
+                    }
+                    else if (status === "dead") {
+                        console.error(`\n⚠️  Port ${port} is busy but not responding (stale process).\n` +
+                            `   Retrying in ${STALE_PORT_RETRY_DELAY_MS}ms…\n`);
+                        setTimeout(() => this.tryListenFixed(port, true), STALE_PORT_RETRY_DELAY_MS);
                     }
                     else {
-                        console.error(`\n❌ Port ${port} is already in use by another application.\n` +
-                            `   Find it: ${hint}\n` +
-                            `   Free the port and retry, or set FIGMA_PLUGIN_BRIDGE_PORT to a different port.\n`);
+                        console.error(`\n❌ Port ${port} is in use by a different service (not F-MCP).\n` +
+                            `   Free the port or set FIGMA_PLUGIN_BRIDGE_PORT to a different value (${MIN_PORT}–${MAX_PORT}).\n`);
+                        process.exit(1);
                     }
-                    process.exit(1);
                 });
-                server.close();
                 return;
             }
             logger.error({ err }, "Plugin bridge server error");
         });
-        const bindHost = process.env.FIGMA_BRIDGE_HOST || "127.0.0.1";
         server.listen(port, bindHost, () => {
             this.port = port;
+            process.env.FIGMA_PLUGIN_BRIDGE_PORT = String(port);
+            process.env.FIGMA_MCP_BRIDGE_PORT = String(port);
+            console.error(`F-MCP bridge listening on ws://${bindHost}:${port}\n`);
             this.httpServer = server;
             this.wss = new WebSocketServer({ server });
             this.wss.on("connection", (ws) => {
-                if (this.client && this.client !== ws) {
-                    this.rejectAllPending("Replaced by new plugin connection");
-                    logger.info("Plugin bridge: new connection arrived, switching to it");
-                }
-                this.client = ws;
-                this.clientAlive = true;
-                this.missedHeartbeats = 0;
-                logger.info({ port: this.port }, "Plugin bridge: plugin connected");
+                const clientId = this.generateClientId();
+                const clientInfo = {
+                    ws,
+                    clientId,
+                    fileKey: null,
+                    fileName: null,
+                    alive: true,
+                    missedHeartbeats: 0,
+                    connectedAt: Date.now(),
+                };
+                this.clients.set(clientId, clientInfo);
+                logger.info({ port: this.port, clientId, totalClients: this.clients.size }, "Plugin bridge: new plugin connected");
                 auditPlugin(this.auditLogPath, "plugin_connect");
                 ws.on("message", (data) => {
-                    this.clientAlive = true;
+                    clientInfo.alive = true;
                     try {
                         const msg = JSON.parse(data.toString());
                         if (msg.type === "ready") {
-                            logger.info("Plugin bridge: plugin sent ready, sending welcome");
-                            ws.send(JSON.stringify({ type: "welcome", bridgeVersion: "1.0.0", port: this.port }));
+                            const incomingFileKey = msg.fileKey || null;
+                            const incomingFileName = msg.fileName || null;
+                            if (incomingFileKey) {
+                                const existing = this.findClientByFileKey(incomingFileKey);
+                                if (existing && existing.clientId !== clientId) {
+                                    logger.info({ oldClientId: existing.clientId, newClientId: clientId, fileKey: incomingFileKey }, "Plugin bridge: replacing existing client for same fileKey");
+                                    this.removeClient(existing.clientId, "Replaced by new connection for same file");
+                                    try {
+                                        existing.ws.close();
+                                    }
+                                    catch { /* ignore */ }
+                                }
+                            }
+                            clientInfo.fileKey = incomingFileKey;
+                            clientInfo.fileName = incomingFileName;
+                            logger.info({ clientId, fileKey: incomingFileKey, fileName: incomingFileName }, "Plugin bridge: client registered (fileKey=%s, fileName=%s)", incomingFileKey, incomingFileName);
+                            ws.send(JSON.stringify({
+                                type: "welcome",
+                                bridgeVersion: "1.1.0",
+                                port: this.port,
+                                clientId,
+                                multiClient: true,
+                            }));
                             return;
                         }
                         if (msg.type === "pong" || msg.type === "keepalive") {
@@ -127,42 +212,37 @@ export class PluginBridgeServer {
                     }
                 });
                 ws.on("close", () => {
-                    if (this.client === ws) {
-                        this.client = null;
-                        this.clientAlive = false;
-                        this.clearHeartbeatTimers();
-                        this.rejectAllPending("Plugin disconnected");
-                        auditPlugin(this.auditLogPath, "plugin_disconnect");
-                        logger.info("Plugin bridge: plugin disconnected");
-                    }
+                    this.removeClient(clientId, "WebSocket closed");
                 });
                 ws.on("error", (err) => {
-                    logger.warn({ err }, "Plugin bridge: client error");
+                    logger.warn({ err, clientId }, "Plugin bridge: client error");
                 });
             });
-            logger.info({ port: this.port, host: bindHost }, "Plugin bridge server listening (ws://%s:%s)", bindHost, this.port);
+            logger.info({ port: this.port, host: bindHost }, "Plugin bridge server listening (ws://%s:%s) — multi-client enabled", bindHost, this.port);
             this.heartbeatTimer = setInterval(() => {
-                if (this.client && this.client.readyState === 1) {
-                    if (!this.clientAlive) {
-                        this.missedHeartbeats++;
-                        if (this.missedHeartbeats >= 3) {
-                            logger.warn("Plugin bridge: client not responding to heartbeat, terminating connection");
+                for (const [clientId, info] of this.clients) {
+                    if (info.ws.readyState !== 1) {
+                        this.removeClient(clientId, "WebSocket not open");
+                        continue;
+                    }
+                    if (!info.alive) {
+                        info.missedHeartbeats++;
+                        if (info.missedHeartbeats >= 3) {
+                            logger.warn({ clientId, fileKey: info.fileKey }, "Plugin bridge: client not responding to heartbeat, terminating");
                             try {
-                                this.client.terminate();
+                                info.ws.terminate();
                             }
                             catch { /* ignore */ }
-                            this.client = null;
-                            this.clientAlive = false;
-                            this.missedHeartbeats = 0;
-                            return;
+                            this.removeClient(clientId, "Heartbeat timeout");
+                            continue;
                         }
                     }
                     else {
-                        this.missedHeartbeats = 0;
-                        this.clientAlive = false;
+                        info.missedHeartbeats = 0;
+                        info.alive = false;
                     }
                     try {
-                        this.client.send(JSON.stringify({ type: "ping" }));
+                        info.ws.send(JSON.stringify({ type: "ping" }));
                     }
                     catch { /* ignore */ }
                 }
@@ -170,10 +250,21 @@ export class PluginBridgeServer {
         });
     }
     /**
-     * Send a request to the plugin and wait for the response.
+     * Send a request to a plugin and wait for the response.
+     * If fileKey is specified, routes to the client serving that file.
+     * Otherwise routes to the most recently connected client.
      */
-    async request(method, params) {
-        if (!this.client || this.client.readyState !== 1) {
+    async request(method, params, fileKey) {
+        const client = this.resolveClient(fileKey);
+        if (!client || client.ws.readyState !== 1) {
+            if (fileKey) {
+                const available = this.listConnectedFiles();
+                const fileList = available.length > 0
+                    ? ` Connected files: ${available.map(f => `${f.fileName || "?"} (${f.fileKey || "?"})`).join(", ")}`
+                    : "";
+                throw new Error(`No plugin connected for fileKey "${fileKey}".${fileList} ` +
+                    "Open the target file in Figma and run the F-MCP ATezer Bridge plugin.");
+            }
             throw new Error("F-MCP ATezer Bridge plugin not connected. Open Figma, run the F-MCP ATezer Bridge plugin, and ensure it shows 'Bridge active' (no debug port needed).");
         }
         const id = `req_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
@@ -192,9 +283,10 @@ export class PluginBridgeServer {
                 timeout,
                 method,
                 startTime,
+                clientId: client.clientId,
             });
             try {
-                this.client.send(JSON.stringify(req));
+                client.ws.send(JSON.stringify(req));
             }
             catch (err) {
                 this.pending.delete(id);
@@ -204,11 +296,49 @@ export class PluginBridgeServer {
             }
         });
     }
-    isConnected() {
-        return !!this.client && this.client.readyState === 1;
+    isConnected(fileKey) {
+        if (fileKey) {
+            const client = this.findClientByFileKey(fileKey);
+            return !!client && client.ws.readyState === 1;
+        }
+        for (const client of this.clients.values()) {
+            if (client.ws.readyState === 1)
+                return true;
+        }
+        return false;
     }
-    clearHeartbeatTimers() {
-        // placeholder for future timers
+    listConnectedFiles() {
+        const result = [];
+        for (const client of this.clients.values()) {
+            if (client.ws.readyState === 1) {
+                result.push({
+                    clientId: client.clientId,
+                    fileKey: client.fileKey,
+                    fileName: client.fileName,
+                    connectedAt: client.connectedAt,
+                });
+            }
+        }
+        return result.sort((a, b) => b.connectedAt - a.connectedAt);
+    }
+    connectedClientCount() {
+        let count = 0;
+        for (const client of this.clients.values()) {
+            if (client.ws.readyState === 1)
+                count++;
+        }
+        return count;
+    }
+    rejectPendingForClient(clientId, reason) {
+        for (const [id, p] of this.pending) {
+            if (p.clientId === clientId) {
+                clearTimeout(p.timeout);
+                const durationMs = Date.now() - p.startTime;
+                auditTool(this.auditLogPath, p.method, false, reason, durationMs);
+                p.reject(new Error(`Plugin bridge request '${p.method}' failed: ${reason}`));
+                this.pending.delete(id);
+            }
+        }
     }
     rejectAllPending(reason) {
         for (const [id, p] of this.pending) {
@@ -224,20 +354,14 @@ export class PluginBridgeServer {
             clearInterval(this.heartbeatTimer);
             this.heartbeatTimer = null;
         }
-        for (const p of this.pending.values()) {
-            clearTimeout(p.timeout);
-            p.reject(new Error("Plugin bridge server stopped"));
-        }
-        this.pending.clear();
-        if (this.client) {
+        this.rejectAllPending("Plugin bridge server stopped");
+        for (const client of this.clients.values()) {
             try {
-                this.client.close();
-            }
-            catch {
-                // ignore
+                client.ws.close();
             }
-            this.client = null;
+            catch { /* ignore */ }
         }
+        this.clients.clear();
         if (this.wss) {
             this.wss.close();
             this.wss = null;