@mp3wizard/figma-console-mcp 1.14.0

package/dist/core/port-discovery.js

@@ -0,0 +1,283 @@
+/**
+ * Port Discovery Module
+ *
+ * Handles dynamic WebSocket port assignment with range-based fallback.
+ * When the preferred port (default 9223) is taken by another MCP server instance
+ * (e.g., Claude Desktop Chat tab vs Code tab), the server automatically tries
+ * the next port in a fixed range (9223-9232).
+ *
+ * Port advertisement files are written to /tmp so the Figma plugin can discover
+ * which port to connect to. Each instance writes its own file with PID for
+ * stale-file detection.
+ *
+ * Zombie process detection:
+ *   Active servers refresh their port file every 30s (heartbeat).
+ *   On startup, cleanupStalePortFiles() detects zombies via:
+ *     1. Dead PID — process no longer exists (existing behavior)
+ *     2. Stale heartbeat — lastSeen older than 5 minutes (process frozen/hung)
+ *     3. Age ceiling — startedAt older than 4 hours with no heartbeat (pre-v1.12 compat)
+ *   Zombie processes are terminated with SIGTERM to free their ports.
+ *
+ * Data flow:
+ *   Server binds port → writes /tmp/figma-console-mcp-{port}.json
+ *   Server heartbeat → refreshes lastSeen every 30s
+ *   Plugin scans ports 9223-9232 → connects to first responding server
+ *   External tools read port files for discovery
+ */
+import { writeFileSync, readFileSync, unlinkSync, existsSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { createChildLogger } from './logger.js';
+const logger = createChildLogger({ component: 'port-discovery' });
+/** Default preferred WebSocket port */
+export const DEFAULT_WS_PORT = 9223;
+/** Number of ports in the fallback range (9223-9232 = 10 ports) */
+export const PORT_RANGE_SIZE = 10;
+/** Prefix for port advertisement files in /tmp */
+const PORT_FILE_PREFIX = 'figma-console-mcp-';
+/** Directory for port advertisement files */
+const PORT_FILE_DIR = tmpdir();
+/** Maximum age before a port file without heartbeat is considered stale (4 hours) */
+export const MAX_PORT_FILE_AGE_MS = 4 * 60 * 60 * 1000;
+/** Maximum time since last heartbeat before a process is considered stale (5 minutes) */
+export const HEARTBEAT_STALE_MS = 5 * 60 * 1000;
+/** Interval between heartbeat refreshes (30 seconds) */
+export const HEARTBEAT_INTERVAL_MS = 30 * 1000;
+/**
+ * Try to bind a WebSocket server to ports in a range, starting from the preferred port.
+ * Returns the first port that binds successfully.
+ *
+ * @param preferredPort - The port to try first (default 9223)
+ * @param host - The host to bind to (default 'localhost')
+ * @returns The actual port that was bound
+ * @throws If all ports in the range are exhausted
+ */
+export function getPortRange(preferredPort = DEFAULT_WS_PORT) {
+    const ports = [];
+    for (let i = 0; i < PORT_RANGE_SIZE; i++) {
+        ports.push(preferredPort + i);
+    }
+    return ports;
+}
+/**
+ * Get the file path for a port advertisement file.
+ */
+export function getPortFilePath(port) {
+    return join(PORT_FILE_DIR, `${PORT_FILE_PREFIX}${port}.json`);
+}
+/**
+ * Write a port advertisement file so clients can discover this server instance.
+ * Includes PID for stale-file detection and lastSeen for heartbeat tracking.
+ */
+export function advertisePort(port, host = 'localhost') {
+    const now = new Date().toISOString();
+    const data = {
+        port,
+        pid: process.pid,
+        host,
+        startedAt: now,
+        lastSeen: now,
+    };
+    const filePath = getPortFilePath(port);
+    try {
+        writeFileSync(filePath, JSON.stringify(data, null, 2), { mode: 0o600 });
+        logger.info({ port, filePath }, 'Port advertised');
+    }
+    catch (error) {
+        logger.warn({ port, filePath, error }, 'Failed to write port advertisement file');
+    }
+}
+/**
+ * Refresh the lastSeen timestamp in a port advertisement file.
+ * Called periodically as a heartbeat to prove this server is still active.
+ * Non-fatal — heartbeat failures are silently ignored.
+ */
+export function refreshPortAdvertisement(port) {
+    const filePath = getPortFilePath(port);
+    try {
+        if (!existsSync(filePath))
+            return;
+        const raw = readFileSync(filePath, 'utf-8');
+        const data = JSON.parse(raw);
+        // Only refresh our own port file
+        if (data.pid !== process.pid)
+            return;
+        data.lastSeen = new Date().toISOString();
+        writeFileSync(filePath, JSON.stringify(data, null, 2), { mode: 0o600 });
+    }
+    catch {
+        // Best-effort — heartbeat failures are non-fatal
+    }
+}
+/**
+ * Remove the port advertisement file for this instance.
+ * Call on clean shutdown.
+ */
+export function unadvertisePort(port) {
+    const filePath = getPortFilePath(port);
+    try {
+        if (existsSync(filePath)) {
+            unlinkSync(filePath);
+            logger.debug({ port, filePath }, 'Port advertisement removed');
+        }
+    }
+    catch {
+        // Best-effort cleanup — file may already be gone
+    }
+}
+/**
+ * Check if a PID is still alive.
+ */
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0); // Signal 0 = existence check, doesn't actually kill
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Determine if a port file represents a zombie/stale MCP instance.
+ *
+ * Detection layers:
+ *   1. If lastSeen exists (v1.12+): stale if older than HEARTBEAT_STALE_MS (5 min)
+ *   2. If lastSeen is missing (pre-v1.12): stale if startedAt older than MAX_PORT_FILE_AGE_MS (4h)
+ *
+ * Assumes the owning process IS alive (PID check should happen before calling this).
+ */
+export function isStaleInstance(data) {
+    const now = Date.now();
+    // If heartbeat exists, use it — active servers refresh every 30s
+    if (data.lastSeen) {
+        const lastSeenAge = now - new Date(data.lastSeen).getTime();
+        return lastSeenAge > HEARTBEAT_STALE_MS;
+    }
+    // No heartbeat (pre-v1.12 instance) — fall back to startup age
+    const startedAge = now - new Date(data.startedAt).getTime();
+    return startedAge > MAX_PORT_FILE_AGE_MS;
+}
+/**
+ * Attempt to terminate a process by PID.
+ * Uses SIGTERM for graceful shutdown. On Windows, this calls TerminateProcess
+ * which is immediate and cannot be caught.
+ *
+ * @returns true if the signal was sent successfully, false if the process was already gone
+ */
+function terminateProcess(pid) {
+    try {
+        process.kill(pid, 'SIGTERM');
+        return true;
+    }
+    catch {
+        return false; // Process may have already exited
+    }
+}
+/**
+ * Read and validate a port advertisement file.
+ * Returns null if the file doesn't exist, is invalid, or the owning process is dead.
+ */
+export function readPortFile(port) {
+    const filePath = getPortFilePath(port);
+    if (!existsSync(filePath))
+        return null;
+    try {
+        const raw = readFileSync(filePath, 'utf-8');
+        const data = JSON.parse(raw);
+        // Validate the owning process is still alive
+        if (!isProcessAlive(data.pid)) {
+            logger.debug({ port, pid: data.pid }, 'Stale port file detected (process dead), cleaning up');
+            try {
+                unlinkSync(filePath);
+            }
+            catch { /* best-effort */ }
+            return null;
+        }
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Discover all active Figma Console MCP server instances by scanning port files.
+ * Validates each file's PID to filter out stale entries.
+ */
+export function discoverActiveInstances(preferredPort = DEFAULT_WS_PORT) {
+    const instances = [];
+    for (const port of getPortRange(preferredPort)) {
+        const data = readPortFile(port);
+        if (data) {
+            instances.push(data);
+        }
+    }
+    return instances;
+}
+/**
+ * Clean up stale port files and terminate zombie MCP processes.
+ *
+ * Runs at startup before port binding. Detects stale instances via:
+ *   1. Dead PID — process no longer exists → delete file
+ *   2. Zombie process — alive but stale (no heartbeat or expired heartbeat)
+ *      → send SIGTERM to free the port, then delete file
+ *   3. Corrupt file — invalid JSON → delete file
+ */
+export function cleanupStalePortFiles() {
+    let cleaned = 0;
+    try {
+        const files = readdirSync(PORT_FILE_DIR);
+        for (const file of files) {
+            if (file.startsWith(PORT_FILE_PREFIX) && file.endsWith('.json')) {
+                const filePath = join(PORT_FILE_DIR, file);
+                try {
+                    const raw = readFileSync(filePath, 'utf-8');
+                    const data = JSON.parse(raw);
+                    if (!isProcessAlive(data.pid)) {
+                        // Dead PID — just clean up the file
+                        unlinkSync(filePath);
+                        cleaned++;
+                        logger.debug({ port: data.port, pid: data.pid }, 'Cleaned up stale port file (dead process)');
+                    }
+                    else if (data.pid !== process.pid && isStaleInstance(data)) {
+                        // Live PID but stale — zombie process, terminate it to free the port
+                        logger.info({ port: data.port, pid: data.pid, startedAt: data.startedAt, lastSeen: data.lastSeen }, 'Detected zombie MCP process — sending SIGTERM to free port');
+                        terminateProcess(data.pid);
+                        try {
+                            unlinkSync(filePath);
+                        }
+                        catch { /* best-effort */ }
+                        cleaned++;
+                    }
+                }
+                catch {
+                    // Corrupt file — remove it
+                    try {
+                        unlinkSync(filePath);
+                        cleaned++;
+                    }
+                    catch { /* ignore */ }
+                }
+            }
+        }
+    }
+    catch {
+        // Can't read /tmp — unusual but not fatal
+    }
+    return cleaned;
+}
+/**
+ * Register process exit handlers to clean up port advertisement file.
+ * Should be called once after the port is successfully bound.
+ */
+export function registerPortCleanup(port) {
+    const cleanup = () => unadvertisePort(port);
+    process.on('exit', cleanup);
+    // Re-register SIGINT/SIGTERM to ensure cleanup runs before the
+    // existing handlers in local.ts main() call process.exit()
+    const originalSigintListeners = process.listeners('SIGINT');
+    const originalSigtermListeners = process.listeners('SIGTERM');
+    // Prepend our cleanup — it runs first, then existing handlers take over
+    process.prependListener('SIGINT', cleanup);
+    process.prependListener('SIGTERM', cleanup);
+}
+//# sourceMappingURL=port-discovery.js.map

package/dist/core/port-discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"port-discovery.js","sourceRoot":"","sources":["../../src/core/port-discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,IAAI,CAAC;AACtF,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,MAAM,EAAE,MAAM,IAAI,CAAC;AAC5B,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,MAAM,GAAG,iBAAiB,CAAC,EAAE,SAAS,EAAE,gBAAgB,EAAE,CAAC,CAAC;AAElE,uCAAuC;AACvC,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CAAC;AAEpC,mEAAmE;AACnE,MAAM,CAAC,MAAM,eAAe,GAAG,EAAE,CAAC;AAElC,kDAAkD;AAClD,MAAM,gBAAgB,GAAG,oBAAoB,CAAC;AAE9C,6CAA6C;AAC7C,MAAM,aAAa,GAAG,MAAM,EAAE,CAAC;AAE/B,qFAAqF;AACrF,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAEvD,yFAAyF;AACzF,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;AAEhD,wDAAwD;AACxD,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAE,GAAG,IAAI,CAAC;AAW/C;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,gBAAwB,eAAe;IAClE,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,eAAe,EAAE,CAAC,EAAE,EAAE,CAAC;QACzC,KAAK,CAAC,IAAI,CAAC,aAAa,GAAG,CAAC,CAAC,CAAC;IAChC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,IAAI,CAAC,aAAa,EAAE,GAAG,gBAAgB,GAAG,IAAI,OAAO,CAAC,CAAC;AAChE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,OAAe,WAAW;IACpE,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACrC,MAAM,IAAI,GAAiB;QACzB,IAAI;QACJ,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,IAAI;QACJ,SAAS,EAAE,GAAG;QACd,QAAQ,EAAE,GAAG;KACd,CAAC;IAEF,MAAM,QAAQ,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IACvC,IAAI,CAAC;QACH,aAAa,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QACxE,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,iBAAiB,CAAC,CAAC;IACrD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,yCAAyC,CAAC,CAAC;IACpF,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,wBAAwB,CAAC,IAAY;IACnD,MAAM,QAAQ,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IACvC,IAAI,CAAC;QACH,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;YAAE,OAAO;QAClC,MAAM,GAAG,GAAG,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC5C,MAAM,IAAI,GAAiB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC3C,iCAAiC;QACjC,IAAI,IAAI,CAAC,GAAG,KAAK,OAAO,CAAC,GAAG;YAAE,OAAO;QACrC,IAAI,CAAC,QAAQ,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACzC,aAAa,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC1E,CAAC;IAAC,MAAM,CAAC;QACP,iDAAiD;IACnD,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,MAAM,QAAQ,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IACvC,IAAI,CAAC;QACH,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YACzB,UAAU,CAAC,QAAQ,CAAC,CAAC;YACrB,MAAM,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,4BAA4B,CAAC,CAAC;QACjE,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,iDAAiD;IACnD,CAAC;AACH,CAAC;AAED;;GAEG;AACH,SAAS,cAAc,CAAC,GAAW;IACjC,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,oDAAoD;QAC1E,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,IAAkB;IAChD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAEvB,iEAAiE;IACjE,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QAClB,MAAM,WAAW,GAAG,GAAG,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,OAAO,EAAE,CAAC;QAC5D,OAAO,WAAW,GAAG,kBAAkB,CAAC;IAC1C,CAAC;IAED,+DAA+D;IAC/D,MAAM,UAAU,GAAG,GAAG,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC;IAC5D,OAAO,UAAU,GAAG,oBAAoB,CAAC;AAC3C,CAAC;AAED;;;;;;GAMG;AACH,SAAS,gBAAgB,CAAC,GAAW;IACnC,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;QAC7B,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC,CAAC,kCAAkC;IAClD,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,MAAM,QAAQ,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IAEvC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IAEvC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC5C,MAAM,IAAI,GAAiB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAE3C,6CAA6C;QAC7C,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YAC9B,MAAM,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,sDAAsD,CAAC,CAAC;YAC9F,IAAI,CAAC;gBAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;YAAC,CAAC;YAAC,MAAM,CAAC,CAAC,iBAAiB,CAAC,CAAC;YACzD,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CAAC,gBAAwB,eAAe;IAC7E,MAAM,SAAS,GAAmB,EAAE,CAAC;IAErC,KAAK,MAAM,IAAI,IAAI,YAAY,CAAC,aAAa,CAAC,EAAE,CAAC;QAC/C,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;QAChC,IAAI,IAAI,EAAE,CAAC;YACT,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB;IACnC,IAAI,OAAO,GAAG,CAAC,CAAC;IAEhB,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,WAAW,CAAC,aAAa,CAAC,CAAC;QACzC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,IAAI,CAAC,UAAU,CAAC,gBAAgB,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;gBAChE,MAAM,QAAQ,GAAG,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;gBAC3C,IAAI,CAAC;oBACH,MAAM,GAAG,GAAG,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;oBAC5C,MAAM,IAAI,GAAiB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;oBAE3C,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;wBAC9B,oCAAoC;wBACpC,UAAU,CAAC,QAAQ,CAAC,CAAC;wBACrB,OAAO,EAAE,CAAC;wBACV,MAAM,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,2CAA2C,CAAC,CAAC;oBAChG,CAAC;yBAAM,IAAI,IAAI,CAAC,GAAG,KAAK,OAAO,CAAC,GAAG,IAAI,eAAe,CAAC,IAAI,CAAC,EAAE,CAAC;wBAC7D,qEAAqE;wBACrE,MAAM,CAAC,IAAI,CACT,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,EACtF,4DAA4D,CAC7D,CAAC;wBACF,gBAAgB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;wBAC3B,IAAI,CAAC;4BAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;wBAAC,CAAC;wBAAC,MAAM,CAAC,CAAC,iBAAiB,CAAC,CAAC;wBACzD,OAAO,EAAE,CAAC;oBACZ,CAAC;gBACH,CAAC;gBAAC,MAAM,CAAC;oBACP,2BAA2B;oBAC3B,IAAI,CAAC;wBAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;wBAAC,OAAO,EAAE,CAAC;oBAAC,CAAC;oBAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;gBACjE,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,0CAA0C;IAC5C,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;IAE5C,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE5B,+DAA+D;IAC/D,2DAA2D;IAC3D,MAAM,uBAAuB,GAAG,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IAC5D,MAAM,wBAAwB,GAAG,OAAO,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;IAE9D,wEAAwE;IACxE,OAAO,CAAC,eAAe,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC3C,OAAO,CAAC,eAAe,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;AAC9C,CAAC"}

package/dist/core/snippet-injector.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Snippet Injector
+ * Generates and manages console-based data extraction snippets for Figma
+ */
+import type { ConsoleLogEntry } from './types/index.js';
+export declare class SnippetInjector {
+    /**
+     * Generate variables extraction snippet for Figma console
+     */
+    generateVariablesSnippet(): string;
+    /**
+     * Parse variables from console log entry
+     */
+    parseVariablesFromLog(logEntry: ConsoleLogEntry): {
+        variables: any[];
+        variableCollections: any[];
+        timestamp: number;
+    } | null;
+    /**
+     * Find the most recent variables log entry
+     */
+    findVariablesLog(logs: ConsoleLogEntry[]): ConsoleLogEntry | null;
+}
+//# sourceMappingURL=snippet-injector.d.ts.map

package/dist/core/snippet-injector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snippet-injector.d.ts","sourceRoot":"","sources":["../../src/core/snippet-injector.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAKxD,qBAAa,eAAe;IAC3B;;OAEG;IACH,wBAAwB,IAAI,MAAM;IAyClC;;OAEG;IACH,qBAAqB,CAAC,QAAQ,EAAE,eAAe,GAAG;QACjD,SAAS,EAAE,GAAG,EAAE,CAAC;QACjB,mBAAmB,EAAE,GAAG,EAAE,CAAC;QAC3B,SAAS,EAAE,MAAM,CAAC;KAClB,GAAG,IAAI;IAuCR;;OAEG;IACH,gBAAgB,CAAC,IAAI,EAAE,eAAe,EAAE,GAAG,eAAe,GAAG,IAAI;CAUjE"}

package/dist/core/snippet-injector.js

@@ -0,0 +1,97 @@
+/**
+ * Snippet Injector
+ * Generates and manages console-based data extraction snippets for Figma
+ */
+import { createChildLogger } from './logger.js';
+const logger = createChildLogger({ component: 'snippet-injector' });
+export class SnippetInjector {
+    /**
+     * Generate variables extraction snippet for Figma console
+     */
+    generateVariablesSnippet() {
+        return `
+(async () => {
+  try {
+    const vars = await figma.variables.getLocalVariablesAsync();
+    const collections = await figma.variables.getLocalVariableCollectionsAsync();
+
+    const payload = {
+      timestamp: Date.now(),
+      variables: vars.map(v => ({
+        id: v.id,
+        name: v.name,
+        key: v.key,
+        resolvedType: v.resolvedType,
+        valuesByMode: v.valuesByMode,
+        variableCollectionId: v.variableCollectionId,
+        scopes: v.scopes,
+        description: v.description,
+        hiddenFromPublishing: v.hiddenFromPublishing
+      })),
+      variableCollections: collections.map(c => ({
+        id: c.id,
+        name: c.name,
+        key: c.key,
+        modes: c.modes.map(m => ({ modeId: m.modeId, name: m.name })),
+        defaultModeId: c.defaultModeId,
+        variableIds: c.variableIds
+      }))
+    };
+
+    console.log('[MCP_VARIABLES]', JSON.stringify(payload), '[MCP_VARIABLES_END]');
+    console.log('✅ Variables data captured! Run figma_get_variables({ parseFromConsole: true }) in Claude to retrieve.');
+
+  } catch (error) {
+    console.error('[MCP_VARIABLES_ERROR]', error.message);
+    console.log('❌ Make sure you\\'re running this in a Figma file with variables.');
+  }
+})();
+		`.trim();
+    }
+    /**
+     * Parse variables from console log entry
+     */
+    parseVariablesFromLog(logEntry) {
+        try {
+            // Check for marker
+            if (!logEntry.message.includes('[MCP_VARIABLES]')) {
+                return null;
+            }
+            // Extract JSON from args
+            // The snippet logs: console.log('[MCP_VARIABLES]', JSON.stringify(payload), '[MCP_VARIABLES_END]')
+            // So args[0] is the marker, args[1] is the JSON string
+            const jsonStr = logEntry.args[1] || logEntry.args[0];
+            if (!jsonStr) {
+                throw new Error('No data found in console log');
+            }
+            const data = typeof jsonStr === 'string' ? JSON.parse(jsonStr) : jsonStr;
+            logger.info({
+                variableCount: data.variables?.length || 0,
+                collectionCount: data.variableCollections?.length || 0,
+            }, 'Successfully parsed variables from console log');
+            return {
+                variables: data.variables || [],
+                variableCollections: data.variableCollections || [],
+                timestamp: data.timestamp || Date.now(),
+            };
+        }
+        catch (error) {
+            logger.error({ error }, 'Failed to parse variables from console log');
+            throw new Error(`Failed to parse variables from console log: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Find the most recent variables log entry
+     */
+    findVariablesLog(logs) {
+        // Search in reverse (most recent first)
+        for (let i = logs.length - 1; i >= 0; i--) {
+            const log = logs[i];
+            if (log.message.includes('[MCP_VARIABLES]')) {
+                return log;
+            }
+        }
+        return null;
+    }
+}
+//# sourceMappingURL=snippet-injector.js.map

package/dist/core/snippet-injector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snippet-injector.js","sourceRoot":"","sources":["../../src/core/snippet-injector.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,MAAM,GAAG,iBAAiB,CAAC,EAAE,SAAS,EAAE,kBAAkB,EAAE,CAAC,CAAC;AAEpE,MAAM,OAAO,eAAe;IAC3B;;OAEG;IACH,wBAAwB;QACvB,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCN,CAAC,IAAI,EAAE,CAAC;IACV,CAAC;IAED;;OAEG;IACH,qBAAqB,CAAC,QAAyB;QAK9C,IAAI,CAAC;YACJ,mBAAmB;YACnB,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC;gBACnD,OAAO,IAAI,CAAC;YACb,CAAC;YAED,yBAAyB;YACzB,mGAAmG;YACnG,uDAAuD;YACvD,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAErD,IAAI,CAAC,OAAO,EAAE,CAAC;gBACd,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;YACjD,CAAC;YAED,MAAM,IAAI,GAAG,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;YAEzE,MAAM,CAAC,IAAI,CACV;gBACC,aAAa,EAAE,IAAI,CAAC,SAAS,EAAE,MAAM,IAAI,CAAC;gBAC1C,eAAe,EAAE,IAAI,CAAC,mBAAmB,EAAE,MAAM,IAAI,CAAC;aACtD,EACD,gDAAgD,CAChD,CAAC;YAEF,OAAO;gBACN,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,EAAE;gBAC/B,mBAAmB,EAAE,IAAI,CAAC,mBAAmB,IAAI,EAAE;gBACnD,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,GAAG,EAAE;aACvC,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,MAAM,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,EAAE,4CAA4C,CAAC,CAAC;YACtE,MAAM,IAAI,KAAK,CACd,+CAA+C,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CACvG,CAAC;QACH,CAAC;IACF,CAAC;IAED;;OAEG;IACH,gBAAgB,CAAC,IAAuB;QACvC,wCAAwC;QACxC,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;YACpB,IAAI,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC;gBAC7C,OAAO,GAAG,CAAC;YACZ,CAAC;QACF,CAAC;QACD,OAAO,IAAI,CAAC;IACb,CAAC;CACD"}

package/dist/core/types/design-code.d.ts

@@ -0,0 +1,262 @@
+/**
+ * TypeScript types for Design-Code Parity Checker & Documentation Generator
+ */
+/** Code-side component specification provided by the AI after reading source code */
+export interface CodeSpec {
+    /** Path to the component source file */
+    filePath?: string;
+    /** Visual properties from code */
+    visual?: {
+        backgroundColor?: string;
+        borderColor?: string;
+        borderWidth?: number;
+        borderRadius?: number | string;
+        opacity?: number;
+        fills?: Array<{
+            color?: string;
+            opacity?: number;
+        }>;
+        strokes?: Array<{
+            color?: string;
+            width?: number;
+        }>;
+        effects?: Array<{
+            type: string;
+            color?: string;
+            offset?: {
+                x: number;
+                y: number;
+            };
+            blur?: number;
+        }>;
+    };
+    /** Spacing and layout properties from code */
+    spacing?: {
+        paddingTop?: number;
+        paddingRight?: number;
+        paddingBottom?: number;
+        paddingLeft?: number;
+        gap?: number;
+        width?: number | string;
+        height?: number | string;
+        minWidth?: number;
+        minHeight?: number;
+        maxWidth?: number;
+        maxHeight?: number;
+        layoutDirection?: "horizontal" | "vertical";
+    };
+    /** Typography properties from code */
+    typography?: {
+        fontFamily?: string;
+        fontSize?: number;
+        fontWeight?: number | string;
+        lineHeight?: number | string;
+        letterSpacing?: number;
+        textAlign?: string;
+        textDecoration?: string;
+        textTransform?: string;
+    };
+    /** Design token usage in code */
+    tokens?: {
+        usedTokens?: string[];
+        hardcodedValues?: Array<{
+            property: string;
+            value: string | number;
+        }>;
+        tokenPrefix?: string;
+    };
+    /** Component API (props/attributes) from code */
+    componentAPI?: {
+        props?: Array<{
+            name: string;
+            type: string;
+            required?: boolean;
+            defaultValue?: string | number | boolean;
+            description?: string;
+            values?: string[];
+        }>;
+        events?: string[];
+        slots?: string[];
+    };
+    /** Accessibility properties from code */
+    accessibility?: {
+        role?: string;
+        ariaLabel?: string;
+        ariaRequired?: boolean;
+        keyboardInteractions?: string[];
+        contrastRatio?: number;
+        focusVisible?: boolean;
+    };
+    /** Metadata from code */
+    metadata?: {
+        name?: string;
+        description?: string;
+        status?: string;
+        version?: string;
+        tags?: string[];
+    };
+}
+/** Severity levels for parity discrepancies */
+export type DiscrepancySeverity = "critical" | "major" | "minor" | "info";
+/** Categories of parity comparison */
+export type ParityCategory = "visual" | "spacing" | "typography" | "tokens" | "componentAPI" | "accessibility" | "naming" | "metadata";
+/** Individual property mismatch between design and code */
+export interface ParityDiscrepancy {
+    category: ParityCategory;
+    property: string;
+    severity: DiscrepancySeverity;
+    designValue: string | number | boolean | null;
+    codeValue: string | number | boolean | null;
+    message: string;
+    suggestion?: string;
+}
+/** Actionable fix for a discrepancy */
+export interface ParityActionItem {
+    discrepancyIndex: number;
+    side: "design" | "code";
+    /** For design-side fixes: which Figma MCP tool to call */
+    figmaTool?: string;
+    /** Ready-to-use parameters for the Figma tool call */
+    figmaToolParams?: Record<string, string | number | boolean | null | object>;
+    /** For code-side fixes */
+    codeChange?: {
+        filePath?: string;
+        property: string;
+        currentValue: string | number | boolean | null;
+        targetValue: string | number | boolean | null;
+        description: string;
+    };
+}
+/** Full parity check result */
+export interface ParityCheckResult {
+    summary: {
+        totalDiscrepancies: number;
+        parityScore: number;
+        byCritical: number;
+        byMajor: number;
+        byMinor: number;
+        byInfo: number;
+        categories: Partial<Record<ParityCategory, number>>;
+    };
+    discrepancies: ParityDiscrepancy[];
+    actionItems: ParityActionItem[];
+    ai_instruction: string;
+    designData: Record<string, unknown>;
+    codeData: CodeSpec;
+}
+/** Code-side documentation info provided by the AI */
+export interface CodeDocInfo {
+    /** Component props/API */
+    props?: Array<{
+        name: string;
+        type: string;
+        required?: boolean;
+        defaultValue?: string;
+        description?: string;
+    }>;
+    /** Events emitted */
+    events?: Array<{
+        name: string;
+        payload?: string;
+        description?: string;
+    }>;
+    /** Named slots (for web components / Vue) */
+    slots?: Array<{
+        name: string;
+        description?: string;
+    }>;
+    /** Import statement */
+    importStatement?: string;
+    /** Usage examples in code */
+    usageExamples?: Array<{
+        title: string;
+        code: string;
+        language?: string;
+    }>;
+    /** Changelog entries */
+    changelog?: Array<{
+        version: string;
+        date: string;
+        changes: string;
+    }>;
+    /** Component file path */
+    filePath?: string;
+    /** Package name */
+    packageName?: string;
+    /** CVA or variant definition code block */
+    variantDefinition?: string;
+    /** Sub-components that compose this component */
+    subComponents?: Array<{
+        name: string;
+        description?: string;
+        element?: string;
+        dataSlot?: string;
+        props?: Array<{
+            name: string;
+            type: string;
+            required?: boolean;
+            defaultValue?: string;
+            description?: string;
+        }>;
+    }>;
+    /** All source files related to this component */
+    sourceFiles?: Array<{
+        path: string;
+        role: string;
+        variants?: number;
+        description?: string;
+    }>;
+    /** Base component this extends */
+    baseComponent?: {
+        name: string;
+        url?: string;
+        description?: string;
+    };
+}
+/** Toggle which doc sections to include */
+export interface DocSections {
+    overview?: boolean;
+    anatomy?: boolean;
+    statesAndVariants?: boolean;
+    visualSpecs?: boolean;
+    typography?: boolean;
+    contentGuidelines?: boolean;
+    behavior?: boolean;
+    implementation?: boolean;
+    accessibility?: boolean;
+    relatedComponents?: boolean;
+    changelog?: boolean;
+    parity?: boolean;
+}
+/** Full documentation generation result */
+export interface DocGenerationResult {
+    componentName: string;
+    figmaNodeId: string;
+    fileKey: string;
+    timestamp: string;
+    markdown: string;
+    includedSections: string[];
+    canonicalSource: "figma" | "code" | "reconciled";
+    dataSourceSummary: {
+        figmaEnriched: boolean;
+        hasCodeInfo: boolean;
+        variablesIncluded: boolean;
+        stylesIncluded: boolean;
+    };
+    suggestedOutputPath: string;
+    ai_instruction: string;
+}
+/** CompanyDocsMCP-compatible content entry */
+export interface CompanyDocsContentEntry {
+    title: string;
+    content: string;
+    category: string;
+    tags: string[];
+    metadata: {
+        source: string;
+        figmaUrl: string;
+        systemName?: string;
+        generatedAt: string;
+    };
+}
+//# sourceMappingURL=design-code.d.ts.map