agent-react-devtools 0.0.0 → 0.1.0

package/src/daemon.ts

@@ -0,0 +1,275 @@
+import net from 'node:net';
+import fs from 'node:fs';
+import path from 'node:path';
+import { DevToolsBridge } from './devtools-bridge.js';
+import { ComponentTree } from './component-tree.js';
+import { Profiler } from './profiler.js';
+import type { IpcCommand, IpcResponse, DaemonInfo, StatusInfo } from './types.js';
+
+const DEFAULT_STATE_DIR = path.join(
+  process.env.HOME || process.env.USERPROFILE || '/tmp',
+  '.agent-react-devtools',
+);
+
+let STATE_DIR = DEFAULT_STATE_DIR;
+
+function getSocketPath(): string {
+  return path.join(STATE_DIR, 'daemon.sock');
+}
+
+function getDaemonInfoPath(): string {
+  return path.join(STATE_DIR, 'daemon.json');
+}
+
+class Daemon {
+  private ipcServer: net.Server | null = null;
+  private bridge: DevToolsBridge;
+  private tree: ComponentTree;
+  private profiler: Profiler;
+  private port: number;
+  private startedAt = Date.now();
+
+  constructor(port: number) {
+    this.port = port;
+    this.tree = new ComponentTree();
+    this.profiler = new Profiler();
+    this.bridge = new DevToolsBridge(port, this.tree, this.profiler);
+  }
+
+  async start(): Promise<void> {
+    // Ensure state directory exists
+    fs.mkdirSync(STATE_DIR, { recursive: true });
+
+    // Clean up stale socket
+    const socketPath = getSocketPath();
+    if (fs.existsSync(socketPath)) {
+      try {
+        fs.unlinkSync(socketPath);
+      } catch {
+        // ignore
+      }
+    }
+
+    // Start WebSocket bridge
+    await this.bridge.start();
+
+    // Start IPC server
+    await this.startIpc(socketPath);
+
+    // Write daemon info
+    const info: DaemonInfo = {
+      pid: process.pid,
+      port: this.port,
+      socketPath,
+      startedAt: this.startedAt,
+    };
+    fs.writeFileSync(getDaemonInfoPath(), JSON.stringify(info, null, 2));
+
+    console.log(`Daemon started (pid=${process.pid}, port=${this.port})`);
+
+    // Handle shutdown
+    const shutdown = () => {
+      this.stop();
+      process.exit(0);
+    };
+    process.on('SIGTERM', shutdown);
+    process.on('SIGINT', shutdown);
+  }
+
+  private startIpc(socketPath: string): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.ipcServer = net.createServer((conn) => {
+        let buffer = '';
+
+        conn.on('data', (chunk) => {
+          buffer += chunk.toString();
+
+          // Process complete messages (newline-delimited JSON)
+          let newlineIdx: number;
+          while ((newlineIdx = buffer.indexOf('\n')) !== -1) {
+            const line = buffer.slice(0, newlineIdx);
+            buffer = buffer.slice(newlineIdx + 1);
+
+            try {
+              const cmd: IpcCommand = JSON.parse(line);
+              this.handleCommand(cmd).then((response) => {
+                conn.write(JSON.stringify(response) + '\n');
+              });
+            } catch {
+              const response: IpcResponse = {
+                ok: false,
+                error: 'Invalid JSON',
+              };
+              conn.write(JSON.stringify(response) + '\n');
+            }
+          }
+        });
+      });
+
+      this.ipcServer.on('error', reject);
+
+      this.ipcServer.listen(socketPath, () => {
+        resolve();
+      });
+    });
+  }
+
+  private async handleCommand(cmd: IpcCommand): Promise<IpcResponse> {
+    try {
+      switch (cmd.type) {
+        case 'ping':
+          return { ok: true, data: 'pong' };
+
+        case 'status':
+          return {
+            ok: true,
+            data: {
+              daemonRunning: true,
+              port: this.port,
+              connectedApps: this.bridge.getConnectedAppCount(),
+              componentCount: this.tree.getComponentCount(),
+              profilingActive: this.profiler.isActive(),
+              uptime: Date.now() - this.startedAt,
+            } satisfies StatusInfo,
+          };
+
+        case 'get-tree':
+          return {
+            ok: true,
+            data: this.tree.getTree(cmd.depth),
+          };
+
+        case 'get-component': {
+          const resolvedId = this.tree.resolveId(cmd.id);
+          if (resolvedId === undefined) {
+            return { ok: false, error: `Component ${cmd.id} not found` };
+          }
+          const element = await this.bridge.inspectElement(resolvedId);
+          if (!element) {
+            return { ok: false, error: `Component ${cmd.id} not found` };
+          }
+          // Include the label if the request used one
+          const label = typeof cmd.id === 'string' ? cmd.id : undefined;
+          return { ok: true, data: element, label };
+        }
+
+        case 'find':
+          return {
+            ok: true,
+            data: this.tree.findByName(cmd.name, cmd.exact),
+          };
+
+        case 'count':
+          return {
+            ok: true,
+            data: this.tree.getCountByType(),
+          };
+
+        case 'profile-start':
+          this.profiler.start(cmd.name);
+          // Snapshot existing component names so they survive unmounts
+          for (const id of this.tree.getAllNodeIds()) {
+            const node = this.tree.getNode(id);
+            if (node) this.profiler.trackComponent(id, node.displayName);
+          }
+          this.bridge.startProfiling();
+          return { ok: true, data: 'Profiling started' };
+
+        case 'profile-stop': {
+          await this.bridge.stopProfilingAndCollect();
+          const session = this.profiler.stop(this.tree);
+          if (!session) {
+            return { ok: false, error: 'No active profiling session' };
+          }
+          return { ok: true, data: session };
+        }
+
+        case 'profile-report': {
+          const resolvedCompId = this.tree.resolveId(cmd.componentId);
+          if (resolvedCompId === undefined) {
+            return { ok: false, error: `Component ${cmd.componentId} not found` };
+          }
+          const report = this.profiler.getReport(resolvedCompId, this.tree);
+          if (!report) {
+            return {
+              ok: false,
+              error: `No profiling data for component ${cmd.componentId}`,
+            };
+          }
+          const compLabel = typeof cmd.componentId === 'string' ? cmd.componentId : undefined;
+          return { ok: true, data: report, label: compLabel };
+        }
+
+        case 'profile-slow':
+          return {
+            ok: true,
+            data: this.profiler.getSlowest(this.tree, cmd.limit),
+          };
+
+        case 'profile-rerenders':
+          return {
+            ok: true,
+            data: this.profiler.getMostRerenders(this.tree, cmd.limit),
+          };
+
+        case 'profile-timeline':
+          return {
+            ok: true,
+            data: this.profiler.getTimeline(cmd.limit),
+          };
+
+        case 'profile-commit': {
+          const detail = this.profiler.getCommitDetails(cmd.index, this.tree, cmd.limit);
+          if (!detail) {
+            return { ok: false, error: `Commit #${cmd.index} not found` };
+          }
+          return { ok: true, data: detail };
+        }
+
+        default:
+          return { ok: false, error: `Unknown command: ${(cmd as any).type}` };
+      }
+    } catch (err) {
+      return {
+        ok: false,
+        error: err instanceof Error ? err.message : String(err),
+      };
+    }
+  }
+
+  stop(): void {
+    this.bridge.stop();
+    if (this.ipcServer) {
+      this.ipcServer.close();
+      this.ipcServer = null;
+    }
+    // Clean up files
+    try {
+      fs.unlinkSync(getSocketPath());
+    } catch {
+      // ignore
+    }
+    try {
+      fs.unlinkSync(getDaemonInfoPath());
+    } catch {
+      // ignore
+    }
+    console.log('Daemon stopped');
+  }
+}
+
+// ── Main ──
+
+const portArg = process.argv.find((a) => a.startsWith('--port='));
+const port = portArg ? parseInt(portArg.split('=')[1], 10) : 8097;
+
+const stateDirArg = process.argv.find((a) => a.startsWith('--state-dir='));
+if (stateDirArg) {
+  STATE_DIR = stateDirArg.split('=')[1];
+}
+
+const daemon = new Daemon(port);
+daemon.start().catch((err) => {
+  console.error('Failed to start daemon:', err);
+  process.exit(1);
+});

package/src/devtools-bridge.ts

@@ -0,0 +1,391 @@
+import { WebSocketServer, WebSocket } from 'ws';
+import type { ComponentTree } from './component-tree.js';
+import type { Profiler } from './profiler.js';
+import type { InspectedElement } from './types.js';
+
+/**
+ * React DevTools protocol bridge.
+ *
+ * Implements the "Wall" messaging pattern that React DevTools uses:
+ * - The backend (inside React app) sends operations, profiling data, etc.
+ * - The frontend (us) can request element inspection, start/stop profiling, etc.
+ *
+ * Message format over WebSocket:
+ *   { event: string, payload: any }
+ */
+
+interface DevToolsMessage {
+  event: string;
+  payload: unknown;
+}
+
+interface PendingInspection {
+  resolve: (value: InspectedElement | null) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+interface PendingProfilingCollect {
+  resolve: () => void;
+  timer: ReturnType<typeof setTimeout>;
+  remaining: number;
+}
+
+export class DevToolsBridge {
+  private wss: WebSocketServer | null = null;
+  private connections = new Set<WebSocket>();
+  private port: number;
+  private tree: ComponentTree;
+  private profiler: Profiler;
+  private pendingInspections = new Map<number, PendingInspection>();
+  private pendingProfilingCollect: PendingProfilingCollect | null = null;
+  private rendererIds = new Set<number>();
+  /** Track which root fiber IDs belong to each WebSocket connection */
+  private connectionRoots = new Map<WebSocket, Set<number>>();
+
+  constructor(port: number, tree: ComponentTree, profiler: Profiler) {
+    this.port = port;
+    this.tree = tree;
+    this.profiler = profiler;
+  }
+
+  async start(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.wss = new WebSocketServer({ port: this.port }, () => {
+        resolve();
+      });
+
+      this.wss.on('error', (err) => {
+        reject(err);
+      });
+
+      this.wss.on('connection', (ws) => {
+        this.connections.add(ws);
+
+        ws.on('message', (data) => {
+          try {
+            const msg: DevToolsMessage = JSON.parse(data.toString());
+            this.handleMessage(ws, msg);
+          } catch {
+            // ignore parse errors
+          }
+        });
+
+        ws.on('close', () => {
+          this.cleanupConnection(ws);
+        });
+
+        ws.on('error', () => {
+          this.cleanupConnection(ws);
+        });
+      });
+    });
+  }
+
+  stop(): void {
+    for (const conn of this.connections) {
+      conn.close();
+    }
+    this.connections.clear();
+    if (this.wss) {
+      this.wss.close();
+      this.wss = null;
+    }
+  }
+
+  getConnectedAppCount(): number {
+    return this.connections.size;
+  }
+
+  /**
+   * Request detailed inspection of a specific element.
+   * Sends a request to the React app and waits for the response.
+   */
+  inspectElement(id: number): Promise<InspectedElement | null> {
+    const node = this.tree.getNode(id);
+    if (!node) return Promise.resolve(null);
+
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        this.pendingInspections.delete(id);
+        resolve(null);
+      }, 5000);
+
+      this.pendingInspections.set(id, { resolve, timer });
+
+      this.sendToAll({
+        event: 'inspectElement',
+        payload: {
+          id,
+          rendererID: node.rendererId,
+          forceFullData: true,
+          requestID: id,
+          path: null,
+        },
+      });
+    });
+  }
+
+  startProfiling(): void {
+    this.sendToAll({
+      event: 'startProfiling',
+      payload: { recordChangeDescriptions: true },
+    });
+  }
+
+  /**
+   * Stop profiling and request data from each renderer.
+   * Returns a promise that resolves when profilingData arrives (or 5s timeout).
+   */
+  stopProfilingAndCollect(): Promise<void> {
+    this.sendToAll({
+      event: 'stopProfiling',
+      payload: undefined,
+    });
+
+    // If no renderers known, resolve immediately
+    if (this.rendererIds.size === 0) {
+      return Promise.resolve();
+    }
+
+    // Request profiling data from each renderer
+    for (const rendererID of this.rendererIds) {
+      this.sendToAll({
+        event: 'getProfilingData',
+        payload: { rendererID },
+      });
+    }
+
+    const expected = this.rendererIds.size;
+    return new Promise<void>((resolve) => {
+      const timer = setTimeout(() => {
+        this.pendingProfilingCollect = null;
+        resolve();
+      }, 5000);
+
+      this.pendingProfilingCollect = { resolve, timer, remaining: expected };
+    });
+  }
+
+  private handleMessage(ws: WebSocket, msg: DevToolsMessage): void {
+    switch (msg.event) {
+      case 'backendInitialized':
+        // Send the full frontend handshake sequence
+        this.sendTo(ws, { event: 'getBridgeProtocol', payload: undefined });
+        this.sendTo(ws, { event: 'getBackendVersion', payload: undefined });
+        this.sendTo(ws, { event: 'getIfHasUnsupportedRendererVersion', payload: undefined });
+        this.sendTo(ws, { event: 'getHookSettings', payload: undefined });
+        this.sendTo(ws, { event: 'getProfilingStatus', payload: undefined });
+        break;
+
+      case 'bridgeProtocol':
+      case 'backendVersion':
+      case 'profilingStatus':
+      case 'overrideComponentFilters':
+        break;
+
+      case 'operations':
+        this.handleOperations(ws, msg.payload as number[]);
+        break;
+
+      case 'inspectedElement':
+        this.handleInspectedElement(msg.payload);
+        break;
+
+      case 'profilingData':
+        this.handleProfilingData(msg.payload);
+        break;
+
+      case 'renderer': {
+        const payload = msg.payload as { id: number };
+        this.rendererIds.add(payload.id);
+        break;
+      }
+
+      case 'rendererAttached': {
+        const payload = msg.payload as { id: number };
+        this.rendererIds.add(payload.id);
+        break;
+      }
+
+      case 'shutdown':
+        ws.close();
+        break;
+
+      // Silently ignore known but unhandled events
+      case 'hookSettings':
+      case 'isBackendStorageAPISupported':
+      case 'isReactNativeEnvironment':
+      case 'isReloadAndProfileSupportedByBackend':
+      case 'isSynchronousXHRSupported':
+      case 'syncSelectionFromNativeElementsPanel':
+      case 'unsupportedRendererVersion':
+        break;
+
+      default:
+        break;
+    }
+  }
+
+  private handleOperations(ws: WebSocket, operations: number[]): void {
+    if (operations.length >= 2) {
+      // Track renderer ID (first element of every operations array)
+      this.rendererIds.add(operations[0]);
+
+      // Track which root fiber IDs belong to this connection
+      const rootFiberId = operations[1];
+      let roots = this.connectionRoots.get(ws);
+      if (!roots) {
+        roots = new Set();
+        this.connectionRoots.set(ws, roots);
+      }
+      roots.add(rootFiberId);
+    }
+    const added = this.tree.applyOperations(operations);
+
+    // Cache display names during profiling so unmounted components are still identifiable
+    if (this.profiler.isActive()) {
+      for (const node of added) {
+        this.profiler.trackComponent(node.id, node.displayName);
+      }
+    }
+  }
+
+  private cleanupConnection(ws: WebSocket): void {
+    this.connections.delete(ws);
+    // Remove all root trees that belonged to this connection
+    const roots = this.connectionRoots.get(ws);
+    if (roots) {
+      for (const rootId of roots) {
+        this.tree.removeRoot(rootId);
+      }
+      this.connectionRoots.delete(ws);
+    }
+  }
+
+  private handleInspectedElement(payload: unknown): void {
+    const data = payload as {
+      type: string;
+      id: number;
+      value?: {
+        id: number;
+        displayName: string;
+        type: number;
+        key: string | null;
+        props: Record<string, unknown>;
+        state: Record<string, unknown> | null;
+        hooks: unknown[] | null;
+      };
+    };
+
+    if (data.type !== 'full-data' && data.type !== 'hydrated-path') {
+      // No data available
+      const pending = this.pendingInspections.get(data.id);
+      if (pending) {
+        clearTimeout(pending.timer);
+        this.pendingInspections.delete(data.id);
+        pending.resolve(null);
+      }
+      return;
+    }
+
+    const pending = this.pendingInspections.get(data.id);
+    if (!pending || !data.value) return;
+
+    clearTimeout(pending.timer);
+    this.pendingInspections.delete(data.id);
+
+    const node = this.tree.getNode(data.id);
+    const inspected: InspectedElement = {
+      id: data.id,
+      displayName: data.value.displayName || node?.displayName || 'Unknown',
+      type: node?.type || 'other',
+      key: data.value.key,
+      props: cleanDehydrated(data.value.props) as Record<string, unknown>,
+      state: data.value.state
+        ? (cleanDehydrated(data.value.state) as Record<string, unknown>)
+        : null,
+      hooks: data.value.hooks
+        ? parseHooks(data.value.hooks)
+        : null,
+      renderedAt: null,
+    };
+
+    pending.resolve(inspected);
+  }
+
+  private handleProfilingData(payload: unknown): void {
+    // React DevTools sends profiling data as a complex nested structure.
+    // We forward it to the profiler for processing.
+    this.profiler.processProfilingData(payload);
+
+    // Resolve once all expected renderer responses have arrived
+    if (this.pendingProfilingCollect) {
+      this.pendingProfilingCollect.remaining--;
+      if (this.pendingProfilingCollect.remaining <= 0) {
+        clearTimeout(this.pendingProfilingCollect.timer);
+        const pending = this.pendingProfilingCollect;
+        this.pendingProfilingCollect = null;
+        pending.resolve();
+      }
+    }
+  }
+
+  private sendTo(ws: WebSocket, msg: DevToolsMessage): void {
+    if (ws.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify(msg));
+    }
+  }
+
+  private sendToAll(msg: DevToolsMessage): void {
+    const raw = JSON.stringify(msg);
+    for (const conn of this.connections) {
+      if (conn.readyState === WebSocket.OPEN) {
+        conn.send(raw);
+      }
+    }
+  }
+}
+
+/**
+ * React DevTools uses "dehydrated" values for complex objects.
+ * These appear as objects with `type: 'string'` and other metadata.
+ * We simplify them for display.
+ */
+function cleanDehydrated(obj: unknown): unknown {
+  if (obj === null || obj === undefined) return obj;
+  if (typeof obj !== 'object') return obj;
+  if (Array.isArray(obj)) return obj.map(cleanDehydrated);
+
+  const record = obj as Record<string, unknown>;
+
+  // Dehydrated value markers from React DevTools
+  if ('type' in record && 'preview_short' in record) {
+    return record['preview_short'];
+  }
+
+  const cleaned: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(record)) {
+    cleaned[key] = cleanDehydrated(value);
+  }
+  return cleaned;
+}
+
+function parseHooks(hooks: unknown[]): { name: string; value: unknown; subHooks?: { name: string; value: unknown }[] }[] {
+  return hooks.map((hook) => {
+    const h = hook as {
+      id: number | null;
+      isStateEditable: boolean;
+      name: string;
+      value: unknown;
+      subHooks?: unknown[];
+    };
+    const result: { name: string; value: unknown; subHooks?: { name: string; value: unknown }[] } = {
+      name: h.name,
+      value: cleanDehydrated(h.value),
+    };
+    if (h.subHooks && h.subHooks.length > 0) {
+      result.subHooks = parseHooks(h.subHooks) as { name: string; value: unknown }[];
+    }
+    return result;
+  });
+}