devlens-mcp 0.3.0

package/src/config/devlens-config.ts

@@ -0,0 +1,76 @@
+import { z } from "zod";
+import { readFile } from "fs/promises";
+import { resolve } from "path";
+
+/**
+ * DevLens configuration file support.
+ *
+ * Loaded from (in priority order):
+ *   1. Path pointed to by DEVLENS_CONFIG env var
+ *   2. ./devlens.config.json in CWD
+ *
+ * Place devlens.config.json in your consumer app root and point to it
+ * via the MCP env block:
+ *
+ *   "env": {
+ *     "METRO_PORT": "8081",
+ *     "FIGMA_TOKEN": "figd_xxx",
+ *     "DEVLENS_CONFIG": "/path/to/your-app/devlens.config.json"
+ *   }
+ */
+
+export const DesignSystemConfigSchema = z.object({
+  /** Design system identifier, e.g. "jds3" */
+  name: z.string(),
+  /** Absolute or CWD-relative path to the consumer app root */
+  projectRoot: z.string(),
+  /** Relative path from projectRoot to the tokens file, e.g. "src/constants/figmaTokens.ts" */
+  tokensFile: z.string(),
+  /** Relative path from projectRoot to the generated component interface directory */
+  componentsDir: z.string().optional(),
+  /** Glob pattern for component source files (default: "src/**\/*.tsx") */
+  componentsGlob: z.string().default("src/**/*.tsx"),
+});
+
+export const DevLensConfigSchema = z.object({
+  designSystem: DesignSystemConfigSchema.optional(),
+});
+
+export type DevLensConfig = z.infer<typeof DevLensConfigSchema>;
+export type DesignSystemConfig = z.infer<typeof DesignSystemConfigSchema>;
+
+/**
+ * Load DevLens config from DEVLENS_CONFIG env var path, or ./devlens.config.json in CWD.
+ * Returns empty config {} if neither is found or both are invalid.
+ * Never throws — invalid config is logged and skipped.
+ */
+export async function loadDevLensConfig(): Promise<DevLensConfig> {
+  const candidates: string[] = [];
+
+  const envPath = process.env.DEVLENS_CONFIG;
+  if (envPath) {
+    candidates.push(resolve(envPath));
+  }
+  candidates.push(resolve(process.cwd(), "devlens.config.json"));
+
+  for (const candidate of candidates) {
+    try {
+      const raw = await readFile(candidate, "utf-8");
+      const parsed = JSON.parse(raw);
+      const result = DevLensConfigSchema.safeParse(parsed);
+      if (result.success) {
+        console.error(`[devlens] Config loaded from: ${candidate}`);
+        return result.data;
+      } else {
+        console.error(
+          `[devlens] Config at ${candidate} is invalid:`,
+          JSON.stringify(result.error.format(), null, 2)
+        );
+      }
+    } catch {
+      // File not found or JSON parse error — try next candidate
+    }
+  }
+
+  return {};
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+import { startServer } from "./server.js";
+
+export async function createServer() {
+  return startServer();
+}

package/src/metro/cdp-client.ts

@@ -0,0 +1,160 @@
+import WebSocket from "ws";
+
+/**
+ * Chrome DevTools Protocol (CDP) client for communicating with the
+ * Metro/Hermes debugger. Connects via WebSocket and sends JSON-RPC messages.
+ *
+ * Metro exposes the debugger endpoint at:
+ *   ws://localhost:{METRO_PORT}/inspector/device?device=0&page=-1
+ *
+ * Through CDP we can:
+ * - Get console logs (Console.enable → Console.messageAdded)
+ * - Intercept network requests (Network.enable → Network.requestWillBeSent)
+ * - Execute JavaScript in the RN context (Runtime.evaluate)
+ * - Trigger hot reload (via Runtime.evaluate)
+ */
+
+export interface CdpMessage {
+  id?: number;
+  method?: string;
+  params?: any;
+  result?: any;
+  error?: { message: string; code?: number };
+}
+
+type MessageHandler = (message: CdpMessage) => void;
+
+export class CdpClient {
+  private ws: WebSocket | null = null;
+  private messageId: number = 0;
+  private pendingRequests: Map<
+    number,
+    { resolve: (value: any) => void; reject: (error: Error) => void }
+  > = new Map();
+  private eventHandlers: Map<string, MessageHandler[]> = new Map();
+  private connected: boolean = false;
+
+  constructor(private endpoint: string) {}
+
+  /** Connect to the CDP endpoint */
+  async connect(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.ws = new WebSocket(this.endpoint);
+
+      const timeout = setTimeout(() => {
+        reject(new Error(`CDP connection timeout to ${this.endpoint}`));
+      }, 5000);
+
+      this.ws.on("open", () => {
+        clearTimeout(timeout);
+        this.connected = true;
+        resolve();
+      });
+
+      this.ws.on("message", (data: WebSocket.Data) => {
+        try {
+          const message: CdpMessage = JSON.parse(data.toString());
+          this.handleMessage(message);
+        } catch {
+          // Ignore malformed messages
+        }
+      });
+
+      this.ws.on("close", () => {
+        this.connected = false;
+        // Reject all pending requests
+        for (const [, { reject }] of this.pendingRequests) {
+          reject(new Error("CDP connection closed"));
+        }
+        this.pendingRequests.clear();
+      });
+
+      this.ws.on("error", (err) => {
+        clearTimeout(timeout);
+        if (!this.connected) {
+          reject(err);
+        }
+      });
+    });
+  }
+
+  /** Send a CDP command and wait for the response */
+  async send(method: string, params?: any): Promise<any> {
+    if (!this.ws || !this.connected) {
+      throw new Error("CDP client not connected");
+    }
+
+    const id = ++this.messageId;
+    const message = JSON.stringify({ id, method, params });
+
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pendingRequests.delete(id);
+        reject(new Error(`CDP request timeout: ${method}`));
+      }, 10000);
+
+      this.pendingRequests.set(id, {
+        resolve: (result) => {
+          clearTimeout(timeout);
+          resolve(result);
+        },
+        reject: (error) => {
+          clearTimeout(timeout);
+          reject(error);
+        },
+      });
+
+      this.ws!.send(message);
+    });
+  }
+
+  /** Register an event handler for CDP events */
+  on(method: string, handler: MessageHandler): void {
+    const handlers = this.eventHandlers.get(method) || [];
+    handlers.push(handler);
+    this.eventHandlers.set(method, handlers);
+  }
+
+  /** Remove event handlers for a method */
+  off(method: string): void {
+    this.eventHandlers.delete(method);
+  }
+
+  /** Check if connected */
+  isConnected(): boolean {
+    return this.connected;
+  }
+
+  /** Close the connection */
+  close(): void {
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+      this.connected = false;
+    }
+  }
+
+  private handleMessage(message: CdpMessage): void {
+    // Response to a request
+    if (message.id !== undefined) {
+      const pending = this.pendingRequests.get(message.id);
+      if (pending) {
+        this.pendingRequests.delete(message.id);
+        if (message.error) {
+          pending.reject(new Error(message.error.message));
+        } else {
+          pending.resolve(message.result);
+        }
+      }
+      return;
+    }
+
+    // Event notification
+    if (message.method) {
+      const handlers = this.eventHandlers.get(message.method) || [];
+      for (const handler of handlers) {
+        handler(message);
+      }
+    }
+  }
+}

package/src/metro/log-collector.ts

@@ -0,0 +1,137 @@
+import type { CdpClient, CdpMessage } from "./cdp-client.js";
+
+/**
+ * Collects console.log/warn/error messages from the React Native app
+ * via the CDP Console and Runtime domains.
+ */
+
+export interface LogEntry {
+  level: "log" | "info" | "warn" | "error" | "debug";
+  message: string;
+  timestamp: number;
+  source?: string;
+}
+
+export class LogCollector {
+  private logs: LogEntry[] = [];
+  private maxLogs: number = 500;
+
+  constructor(private cdp: CdpClient) {}
+
+  /** Start listening for console messages */
+  start(): void {
+    // Listen for Console.messageAdded (older CDP)
+    this.cdp.on("Console.messageAdded", (msg: CdpMessage) => {
+      const entry = msg.params?.message;
+      if (entry) {
+        this.addLog({
+          level: this.normalizeLevel(entry.level),
+          message: entry.text || "",
+          timestamp: Date.now(),
+          source: entry.source,
+        });
+      }
+    });
+
+    // Listen for Runtime.consoleAPICalled (newer CDP)
+    this.cdp.on("Runtime.consoleAPICalled", (msg: CdpMessage) => {
+      const params = msg.params;
+      if (params) {
+        const args = params.args || [];
+        const message = args
+          .map((arg: any) => {
+            if (arg.type === "string") return arg.value;
+            if (arg.type === "number") return String(arg.value);
+            if (arg.type === "boolean") return String(arg.value);
+            if (arg.type === "undefined") return "undefined";
+            if (arg.type === "object" && arg.value)
+              return JSON.stringify(arg.value);
+            if (arg.description) return arg.description;
+            return String(arg.value ?? "");
+          })
+          .join(" ");
+
+        this.addLog({
+          level: this.normalizeLevel(params.type),
+          message,
+          timestamp: params.timestamp || Date.now(),
+        });
+      }
+    });
+
+    // Listen for Runtime.exceptionThrown
+    this.cdp.on("Runtime.exceptionThrown", (msg: CdpMessage) => {
+      const details = msg.params?.exceptionDetails;
+      if (details) {
+        this.addLog({
+          level: "error",
+          message:
+            details.text ||
+            details.exception?.description ||
+            "Unknown exception",
+          timestamp: Date.now(),
+          source: "exception",
+        });
+      }
+    });
+  }
+
+  /** Get collected logs, optionally filtered by level and time */
+  getLogs(options?: {
+    level?: "log" | "info" | "warn" | "error" | "debug";
+    since?: number;
+    limit?: number;
+  }): LogEntry[] {
+    let filtered = this.logs;
+
+    if (options?.level) {
+      const levelOrder = { debug: 0, log: 1, info: 2, warn: 3, error: 4 };
+      const minLevel = levelOrder[options.level] ?? 0;
+      filtered = filtered.filter(
+        (log) => (levelOrder[log.level] ?? 0) >= minLevel
+      );
+    }
+
+    if (options?.since) {
+      filtered = filtered.filter((log) => log.timestamp >= options.since!);
+    }
+
+    if (options?.limit) {
+      filtered = filtered.slice(-options.limit);
+    }
+
+    return filtered;
+  }
+
+  /** Clear all collected logs */
+  clear(): void {
+    this.logs = [];
+  }
+
+  private addLog(entry: LogEntry): void {
+    this.logs.push(entry);
+    // Keep buffer bounded
+    if (this.logs.length > this.maxLogs) {
+      this.logs = this.logs.slice(-Math.floor(this.maxLogs * 0.8));
+    }
+  }
+
+  private normalizeLevel(
+    level: string
+  ): "log" | "info" | "warn" | "error" | "debug" {
+    switch (level?.toLowerCase()) {
+      case "warning":
+      case "warn":
+        return "warn";
+      case "error":
+        return "error";
+      case "debug":
+      case "verbose":
+        return "debug";
+      case "info":
+        return "info";
+      default:
+        return "log";
+    }
+  }
+}

package/src/metro/metro-bridge.ts

@@ -0,0 +1,307 @@
+import { CdpClient } from "./cdp-client.js";
+import { LogCollector } from "./log-collector.js";
+import { NetworkInspector } from "./network-inspector.js";
+
+/**
+ * Metro Bridge — manages the connection to Metro bundler's debugger
+ * and provides access to console logs, network requests, and JS execution.
+ *
+ * Metro/Hermes exposes CDP endpoints. To discover available pages:
+ *   GET http://localhost:{port}/json
+ *
+ * The main debugger endpoint is typically:
+ *   ws://localhost:{port}/inspector/device?device=0&page=-1
+ *
+ * For newer React Native (0.76+) with the new debugger:
+ *   ws://localhost:{port}/inspector/device?device=0&page=1
+ */
+
+export interface MetroStatus {
+  /** Whether the Metro packager process is running and responding */
+  running: boolean;
+  /** The port being checked */
+  port: number;
+  /** Raw response from /status endpoint (e.g., "packager-status:running") */
+  packagerStatus: string | null;
+  /** Whether a CDP WebSocket connection is currently active */
+  cdpConnected: boolean;
+  /** Error message if Metro is unreachable */
+  error?: string;
+}
+
+export class MetroBridge {
+  private cdp: CdpClient | null = null;
+  private _logCollector: LogCollector | null = null;
+  private _networkInspector: NetworkInspector | null = null;
+  private _connected: boolean = false;
+
+  constructor(private port: number = 8081) {}
+
+  /** Connect to Metro bundler's debugger */
+  async connect(): Promise<void> {
+    if (this._connected) return;
+
+    // Try to discover the debugger endpoint
+    const endpoint = await this.discoverEndpoint();
+    this.cdp = new CdpClient(endpoint);
+    await this.cdp.connect();
+
+    // Initialize collectors
+    this._logCollector = new LogCollector(this.cdp);
+    this._networkInspector = new NetworkInspector(this.cdp);
+
+    // Enable CDP domains
+    await this.cdp.send("Runtime.enable");
+    await this.cdp.send("Console.enable").catch(() => {
+      // Console domain might not be available in all environments
+    });
+
+    // Start collecting
+    this._logCollector.start();
+    this._networkInspector.start();
+
+    this._connected = true;
+  }
+
+  /** Disconnect from Metro */
+  disconnect(): void {
+    if (this.cdp) {
+      this.cdp.close();
+      this.cdp = null;
+    }
+    this._logCollector = null;
+    this._networkInspector = null;
+    this._connected = false;
+  }
+
+  /** Check if connected to Metro */
+  get connected(): boolean {
+    return this._connected && (this.cdp?.isConnected() ?? false);
+  }
+
+  /** Get the log collector */
+  get logCollector(): LogCollector {
+    if (!this._logCollector) {
+      throw new Error("Not connected to Metro. Call connect() first.");
+    }
+    return this._logCollector;
+  }
+
+  /** Get the network inspector */
+  get networkInspector(): NetworkInspector {
+    if (!this._networkInspector) {
+      throw new Error("Not connected to Metro. Call connect() first.");
+    }
+    return this._networkInspector;
+  }
+
+  /** Execute JavaScript in the React Native context */
+  async evaluate(expression: string): Promise<any> {
+    if (!this.cdp || !this._connected) {
+      throw new Error("Not connected to Metro.");
+    }
+
+    const result = await this.cdp.send("Runtime.evaluate", {
+      expression,
+      returnByValue: true,
+      awaitPromise: true,
+    });
+
+    if (result?.exceptionDetails) {
+      throw new Error(
+        `JS Error: ${result.exceptionDetails.text || result.exceptionDetails.exception?.description}`
+      );
+    }
+
+    return result?.result?.value;
+  }
+
+  /** Trigger a hot reload / fast refresh */
+  async hotReload(): Promise<void> {
+    try {
+      // Method 1: Use the Metro reload endpoint
+      const http = await import("http");
+      await new Promise<void>((resolve, reject) => {
+        const req = http.request(
+          {
+            hostname: "localhost",
+            port: this.port,
+            path: "/reload",
+            method: "POST",
+          },
+          (res) => {
+            res.resume();
+            resolve();
+          }
+        );
+        req.on("error", reject);
+        req.setTimeout(5000, () => {
+          req.destroy();
+          reject(new Error("Reload request timeout"));
+        });
+        req.end();
+      });
+    } catch {
+      // Method 2: Fallback - evaluate reload command via CDP
+      if (this.cdp && this._connected) {
+        await this.cdp.send("Runtime.evaluate", {
+          expression:
+            'if (typeof __DEV__ !== "undefined" && __DEV__) { const DevSettings = require("react-native/Libraries/Utilities/DevSettings"); DevSettings.reload(); }',
+        });
+      }
+    }
+  }
+
+  /** Get the React component tree by evaluating JS in the RN context */
+  async getComponentTree(maxDepth: number = 10): Promise<string> {
+    if (!this.cdp || !this._connected) {
+      throw new Error("Not connected to Metro.");
+    }
+
+    // Inject a helper that traverses the React fiber tree
+    const script = `
+      (function() {
+        try {
+          // Find the root fiber
+          const roots = [];
+          const fiberRoots = document?.querySelectorAll?.('[data-reactroot]') || [];
+
+          // For React Native, we need to find the fiber root differently
+          // The __REACT_DEVTOOLS_GLOBAL_HOOK__ is available when DevTools is enabled
+          const hook = globalThis.__REACT_DEVTOOLS_GLOBAL_HOOK__;
+          if (!hook || !hook.renderers) {
+            return "React DevTools hook not available. Ensure the app is running in __DEV__ mode.";
+          }
+
+          const renderers = Array.from(hook.renderers.values());
+          if (renderers.length === 0) {
+            return "No React renderers found.";
+          }
+
+          // Get fiber roots from the hook
+          const fiberRootSet = hook.getFiberRoots?.(renderers[0].rendererID || 1);
+          if (!fiberRootSet || fiberRootSet.size === 0) {
+            return "No fiber roots found. Is a React Native app running?";
+          }
+
+          function traverseFiber(fiber, depth, maxDepth) {
+            if (!fiber || depth > maxDepth) return null;
+
+            const name = fiber.type?.displayName || fiber.type?.name || fiber.type || 'Unknown';
+            const props = {};
+
+            if (fiber.memoizedProps) {
+              for (const [key, value] of Object.entries(fiber.memoizedProps)) {
+                if (key === 'children') continue;
+                if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+                  props[key] = value;
+                } else if (typeof value === 'function') {
+                  props[key] = '[function]';
+                }
+              }
+            }
+
+            const children = [];
+            let child = fiber.child;
+            while (child) {
+              const result = traverseFiber(child, depth + 1, maxDepth);
+              if (result) children.push(result);
+              child = child.sibling;
+            }
+
+            // Skip internal React types
+            if (typeof name === 'number' || name === 'Unknown') {
+              return children.length === 1 ? children[0] : children.length > 0 ? { type: 'Fragment', children } : null;
+            }
+
+            return {
+              type: String(name),
+              props: Object.keys(props).length > 0 ? props : undefined,
+              children: children.length > 0 ? children : undefined,
+            };
+          }
+
+          const root = Array.from(fiberRootSet)[0];
+          const tree = traverseFiber(root.current, 0, ${maxDepth});
+          return JSON.stringify(tree, null, 2);
+        } catch (e) {
+          return "Error getting component tree: " + e.message;
+        }
+      })()
+    `;
+
+    const result = await this.cdp.send("Runtime.evaluate", {
+      expression: script,
+      returnByValue: true,
+    });
+
+    return result?.result?.value || "Could not retrieve component tree";
+  }
+
+  /** Proactively check if Metro bundler is running and healthy */
+  async getStatus(): Promise<MetroStatus> {
+    const status: MetroStatus = {
+      running: false,
+      port: this.port,
+      packagerStatus: null,
+      cdpConnected: this.connected,
+    };
+
+    try {
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), 3000);
+      const response = await fetch(`http://localhost:${this.port}/status`, {
+        signal: controller.signal,
+      });
+      clearTimeout(timeout);
+      const body = await response.text();
+      status.packagerStatus = body.trim();
+      status.running = body.includes("packager-status:running");
+    } catch (err: any) {
+      status.error = `Cannot reach Metro on port ${this.port}: ${err.message}`;
+    }
+
+    return status;
+  }
+
+  /** Discover the debugger WebSocket endpoint */
+  private async discoverEndpoint(): Promise<string> {
+    const http = await import("http");
+
+    try {
+      // Query Metro's page list
+      const pages = await new Promise<any[]>((resolve, reject) => {
+        http
+          .get(`http://localhost:${this.port}/json`, (res) => {
+            let data = "";
+            res.on("data", (chunk) => (data += chunk));
+            res.on("end", () => {
+              try {
+                resolve(JSON.parse(data));
+              } catch {
+                resolve([]);
+              }
+            });
+          })
+          .on("error", reject);
+      });
+
+      // Find the best debugger page
+      const debuggerPage = pages.find(
+        (p) =>
+          p.title?.includes("Hermes") ||
+          p.title?.includes("React Native") ||
+          p.webSocketDebuggerUrl
+      );
+
+      if (debuggerPage?.webSocketDebuggerUrl) {
+        return debuggerPage.webSocketDebuggerUrl;
+      }
+    } catch {
+      // Metro might not support /json endpoint
+    }
+
+    // Fallback to default endpoint
+    return `ws://localhost:${this.port}/inspector/device?device=0&page=-1`;
+  }
+}