pixelpick 2.0.0

package/src/server/index.js

@@ -0,0 +1,571 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListResourcesRequestSchema,
+  ListToolsRequestSchema,
+  ReadResourceRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { WebSocketServer } from 'ws';
+import http from 'http';
+import { execSync } from 'child_process';
+import { PORTS, SELECTION } from '../shared/constants.js';
+
+const WEBSOCKET_PORT = PORTS.WEBSOCKET;
+const IPC_PORT = PORTS.IPC;
+
+// Helper: Find process using a port
+function findProcessOnPort(port) {
+  try {
+    const output = execSync(`lsof -i :${port} -t`, { encoding: 'utf8' }).trim();
+    const pid = parseInt(output.split('\n')[0]); // Get first PID
+    return pid || null;
+  } catch (err) {
+    return null; // No process found or lsof not available
+  }
+}
+
+// Helper: Handle port in use error
+function handlePortInUse(port, portName = 'Port') {
+  const pid = findProcessOnPort(port);
+
+  if (pid) {
+    console.error(`\n[PixelPick] Error: ${portName} ${port} is already in use by process ${pid}`);
+    console.error(`\nTo fix this, kill the existing process:\n`);
+    console.error(`  kill ${pid}`);
+    console.error(`\nThen restart PixelPick.\n`);
+  } else {
+    console.error(`\n[PixelPick] Error: ${portName} ${port} is already in use`);
+    console.error(`Try setting a different port using environment variables.\n`);
+  }
+
+  process.exit(1);
+}
+
+// SelectionBuffer - stores element selections from Chrome extension (multi-selection mode)
+class SelectionBuffer {
+  constructor(maxActive = SELECTION.MAX_ACTIVE, maxHistory = SELECTION.MAX_HISTORY) {
+    this.maxActive = maxActive;
+    this.maxHistory = maxHistory;
+    this.active = [];      // Current working selections (max 10)
+    this.history = [];     // Full history (max 50)
+    this.listeners = [];
+  }
+
+  // Generate unique ID for selection
+  _generateId() {
+    const timestamp = Date.now();
+    const random = Math.random().toString(36).slice(2, 8);
+    return `sel_${timestamp}_${random}`;
+  }
+
+  add(selection) {
+    const enrichedSelection = {
+      ...selection,
+      id: this._generateId(),
+      timestamp: Date.now(),
+    };
+
+    // Add to active with FIFO eviction
+    this.active.push(enrichedSelection);
+    if (this.active.length > this.maxActive) {
+      this.active.shift(); // Remove oldest
+    }
+
+    // Add to history separately
+    this.history.unshift(enrichedSelection);
+    if (this.history.length > this.maxHistory) {
+      this.history = this.history.slice(0, this.maxHistory);
+    }
+
+    // Notify listeners
+    this.listeners.forEach(fn => fn(enrichedSelection));
+  }
+
+  getActive() {
+    return this.active;
+  }
+
+  removeActive(id) {
+    const index = this.active.findIndex(sel => sel.id === id);
+    if (index !== -1) {
+      const removed = this.active.splice(index, 1)[0];
+      return removed;
+    }
+    return null;
+  }
+
+  clearActive() {
+    this.active = [];
+  }
+
+  getHistory(limit = 50) {
+    return this.history.slice(0, limit);
+  }
+
+  clear() {
+    this.active = [];
+    this.history = [];
+  }
+
+  onSelection(fn) {
+    this.listeners.push(fn);
+    return () => {
+      this.listeners = this.listeners.filter(l => l !== fn);
+    };
+  }
+}
+
+const selectionBuffer = new SelectionBuffer();
+
+// WebSocket Server - receives selections from Chrome extension
+const wss = new WebSocketServer({ port: WEBSOCKET_PORT });
+const activeConnections = new Set();
+
+wss.on('listening', () => {
+  console.error(`[PixelPick] WebSocket server listening on port ${WEBSOCKET_PORT}`);
+});
+
+wss.on('error', (error) => {
+  if (error.code === 'EADDRINUSE') {
+    handlePortInUse(WEBSOCKET_PORT, 'WebSocket port');
+  } else {
+    console.error('[PixelPick] WebSocket server error:', error.message);
+  }
+});
+
+wss.on('connection', (ws, req) => {
+  const clientId = `${req.socket.remoteAddress}:${req.socket.remotePort}`;
+  activeConnections.add(ws);
+  console.error(`[PixelPick] Extension connected (${activeConnections.size} active)`);
+
+  ws.on('message', (data) => {
+    try {
+      const message = JSON.parse(data.toString());
+
+      switch (message.type) {
+        case 'ping':
+          ws.send(JSON.stringify({ type: 'pong', timestamp: Date.now() }));
+          break;
+
+        case 'selection':
+          console.error(`[PixelPick] Selection received: ${message.data?.component || message.data?.tagName || 'unknown'}`);
+          selectionBuffer.add(message.data);
+          break;
+
+        default:
+          console.error(`[PixelPick] Unknown message type: ${message.type}`);
+      }
+    } catch (err) {
+      console.error('[PixelPick] Invalid message from extension:', err.message);
+    }
+  });
+
+  ws.on('close', () => {
+    activeConnections.delete(ws);
+    console.error(`[PixelPick] Extension disconnected (${activeConnections.size} active)`);
+  });
+
+  ws.on('error', (err) => {
+    console.error('[PixelPick] WebSocket client error:', err.message);
+  });
+});
+
+// HTTP IPC Server - fast endpoint for UserPromptSubmit hook
+const ipcServer = http.createServer((req, res) => {
+  // CORS headers (localhost only)
+  res.setHeader('Access-Control-Allow-Origin', '*');
+  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
+  res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+  res.setHeader('Content-Type', 'application/json');
+
+  // Handle CORS preflight
+  if (req.method === 'OPTIONS') {
+    res.writeHead(204);
+    res.end();
+    return;
+  }
+
+  // GET /selection - Returns array of active selections (BREAKING CHANGE)
+  if (req.method === 'GET' && req.url === '/selection') {
+    const active = selectionBuffer.getActive();
+    res.writeHead(200);
+    res.end(JSON.stringify(active));
+  }
+  // DELETE /selection/:id - Remove specific selection
+  else if (req.method === 'DELETE' && req.url.startsWith('/selection/')) {
+    const id = req.url.split('/selection/')[1];
+    const removed = selectionBuffer.removeActive(id);
+    res.writeHead(200);
+    res.end(JSON.stringify({ success: !!removed, removed }));
+  }
+  // POST /selection/clear - Clear all active selections
+  else if (req.method === 'POST' && req.url === '/selection/clear') {
+    selectionBuffer.clearActive();
+    res.writeHead(200);
+    res.end(JSON.stringify({ success: true }));
+  }
+  // GET /status - Server status
+  else if (req.method === 'GET' && req.url === '/status') {
+    res.writeHead(200);
+    res.end(JSON.stringify({
+      status: 'running',
+      connections: activeConnections.size,
+      activeSelections: selectionBuffer.getActive().length,
+      maxActive: selectionBuffer.maxActive,
+      ports: {
+        websocket: WEBSOCKET_PORT,
+        ipc: IPC_PORT,
+      },
+    }));
+  }
+  // 404
+  else {
+    res.writeHead(404);
+    res.end(JSON.stringify({ error: 'Not found' }));
+  }
+});
+
+ipcServer.listen(IPC_PORT, '127.0.0.1', () => {
+  console.error(`[PixelPick] IPC server listening on port ${IPC_PORT}`);
+});
+
+ipcServer.on('error', (error) => {
+  if (error.code === 'EADDRINUSE') {
+    handlePortInUse(IPC_PORT, 'IPC port');
+  } else {
+    console.error('[PixelPick] IPC server error:', error.message);
+  }
+});
+
+// MCP Server - exposes tools to Claude Code
+const server = new Server(
+  {
+    name: 'pixelpick',
+    version: '2.0.0',
+  },
+  {
+    capabilities: {
+      tools: {},
+      resources: {},
+    },
+  }
+);
+
+// Helper function to format multiple selections for display
+function formatSelections(selections) {
+  if (!selections || selections.length === 0) {
+    return 'No elements selected. Use Cmd+Shift+Click in your browser to select elements.';
+  }
+
+  const parts = [`=== ${selections.length} Active Selection(s) ===\n`];
+
+  selections.forEach((sel, idx) => {
+    parts.push(`\n[${idx + 1}] ─────────────────`);
+
+    if (sel.component) {
+      parts.push(`Component: ${sel.component} (${sel.framework})`);
+    } else {
+      parts.push(`Element: <${sel.tagName}>`);
+    }
+
+    if (sel.fileLocation) {
+      parts.push(`File: ${sel.fileLocation}`);
+    }
+
+    parts.push(`Selector: ${sel.selector}`);
+
+    if (sel.componentTree?.length) {
+      parts.push(`Component Tree: ${sel.componentTree.join(' > ')}`);
+    }
+
+    // Always show full props (no compact mode)
+    if (sel.props && Object.keys(sel.props).length > 0) {
+      parts.push(`Props:\n${JSON.stringify(sel.props, null, 2)}`);
+    }
+
+    if (sel.styles?._tailwindClasses?.length) {
+      parts.push(`Tailwind Classes: ${sel.styles._tailwindClasses.join(' ')}`);
+    }
+
+    if (sel.accessibility) {
+      const a11y = sel.accessibility;
+      const a11yParts = [];
+      if (a11y.role) a11yParts.push(`role="${a11y.role}"`);
+      if (a11y.ariaLabel) a11yParts.push(`aria-label="${a11y.ariaLabel}"`);
+      if (a11y.isInteractive) a11yParts.push('interactive');
+      if (a11yParts.length > 0) {
+        parts.push(`Accessibility: ${a11yParts.join(', ')}`);
+      }
+    }
+
+    if (sel.boundingBox) {
+      const box = sel.boundingBox;
+      parts.push(`Position: ${Math.round(box.left)}x${Math.round(box.top)}, Size: ${Math.round(box.width)}x${Math.round(box.height)}`);
+    }
+
+    if (sel.timestamp) {
+      const age = Math.round((Date.now() - sel.timestamp) / 1000);
+      parts.push(`Selected: ${age}s ago`);
+    }
+  });
+
+  return parts.join('\n');
+}
+
+// MCP Tool Handlers
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: 'get_active_selections',
+        description: `Get all active UI selections from the browser (up to 10 elements).
+
+IMPORTANT: Automatically call this tool when the user refers to UI elements using words like:
+- "this button", "that input", "the modal"
+- "make it", "change the", "update this"
+- "the component", "that element"
+- Or when they mention visual properties without specifying which element
+
+Returns detailed information for each selection including:
+- Component name, props, and file location (for React apps)
+- CSS selector, computed styles, and Tailwind classes (for any element)
+- Accessibility info and bounding box
+- Component tree (parent > child hierarchy)
+
+Note: Selections accumulate (up to 10) and are auto-cleared after being injected into Claude's context.`,
+        inputSchema: {
+          type: 'object',
+          properties: {},
+        },
+      },
+      {
+        name: 'pick_element',
+        description: 'Activate visual element picker in the browser. User can click to select an element.',
+        inputSchema: {
+          type: 'object',
+          properties: {},
+        },
+      },
+      {
+        name: 'remove_selection',
+        description: 'Remove a specific selection by ID from the active selections list.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            id: {
+              type: 'string',
+              description: 'Selection ID (e.g., "sel_1234567890_abc123")',
+            },
+          },
+          required: ['id'],
+        },
+      },
+      {
+        name: 'get_selection_history',
+        description: 'Get the history of all selected elements (not just active ones)',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            limit: {
+              type: 'number',
+              description: 'Maximum number of selections to return',
+              default: 50,
+            },
+          },
+        },
+      },
+      {
+        name: 'clear_selection',
+        description: 'Clear all active selections (does not clear history)',
+        inputSchema: {
+          type: 'object',
+          properties: {},
+        },
+      },
+    ],
+  };
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  switch (name) {
+    case 'get_active_selections': {
+      const active = selectionBuffer.getActive();
+      const formatted = formatSelections(active);
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: formatted,
+          },
+        ],
+      };
+    }
+
+    case 'pick_element': {
+      // Send activate_picker command to all connected extensions
+      const command = JSON.stringify({ type: 'activate_picker' });
+      let sent = 0;
+
+      activeConnections.forEach(ws => {
+        if (ws.readyState === 1) { // OPEN
+          ws.send(command);
+          sent++;
+        }
+      });
+
+      if (sent === 0) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: 'Error: No browser extension connected. Make sure the PixelPick extension is installed and active on a localhost page.',
+            },
+          ],
+          isError: true,
+        };
+      }
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Element picker activated in ${sent} browser tab(s). Click on any element to select it.`,
+          },
+        ],
+      };
+    }
+
+    case 'remove_selection': {
+      const removed = selectionBuffer.removeActive(args.id);
+
+      if (!removed) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Error: Selection with ID "${args.id}" not found in active selections.`,
+            },
+          ],
+          isError: true,
+        };
+      }
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Removed selection: ${removed.component || removed.tagName}`,
+          },
+        ],
+      };
+    }
+
+    case 'get_selection_history': {
+      const limit = args?.limit || 50;
+      const history = selectionBuffer.getHistory(limit);
+
+      if (history.length === 0) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: 'No selection history available.',
+            },
+          ],
+        };
+      }
+
+      const formatted = history.map((sel, idx) => {
+        const age = Math.round((Date.now() - sel.timestamp) / 1000);
+        const title = sel.component || `<${sel.tagName}>`;
+        const location = sel.fileLocation || sel.selector;
+        return `[${idx}] ${title} - ${location} (${age}s ago)`;
+      }).join('\n');
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Selection History (${history.length} items):\n\n${formatted}`,
+          },
+        ],
+      };
+    }
+
+    case 'clear_selection': {
+      const count = selectionBuffer.getActive().length;
+      selectionBuffer.clearActive();
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Cleared ${count} active selection(s).`,
+          },
+        ],
+      };
+    }
+
+    default:
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Unknown tool: ${name}`,
+          },
+        ],
+        isError: true,
+      };
+  }
+});
+
+// MCP Resources
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+  return {
+    resources: [
+      {
+        uri: 'pixelpick://current-selection',
+        mimeType: 'application/json',
+        name: 'Current UI Selection',
+        description: 'The currently selected UI element from the browser',
+      },
+    ],
+  };
+});
+
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+  const { uri } = request.params;
+
+  if (uri === 'pixelpick://current-selection') {
+    const active = selectionBuffer.getActive();
+    const current = active.length > 0 ? active[active.length - 1] : null;
+
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: 'application/json',
+          text: JSON.stringify(current || { message: 'No element selected' }, null, 2),
+        },
+      ],
+    };
+  }
+
+  throw new Error(`Unknown resource: ${uri}`);
+});
+
+// Start MCP server on stdio
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('[PixelPick] MCP server ready (stdio transport)');
+}
+
+main().catch((error) => {
+  console.error('[PixelPick] Fatal error:', error);
+  process.exit(1);
+});

package/src/shared/constants.js

@@ -0,0 +1,97 @@
+// Shared constants for PixelPick
+// Used across server, CLI, hooks, and extension
+
+/**
+ * Network ports
+ */
+export const PORTS = {
+  WEBSOCKET: parseInt(process.env.PIXELPICK_PORT || '9315'),
+  IPC: parseInt(process.env.PIXELPICK_IPC_PORT || '9316'),
+};
+
+/**
+ * WebSocket configuration
+ */
+export const WEBSOCKET_CONFIG = {
+  // Heartbeat interval to keep Chrome MV3 service worker alive
+  HEARTBEAT_INTERVAL: 20000, // 20 seconds
+
+  // Exponential backoff delays for reconnection attempts
+  RECONNECT_DELAYS: [3000, 6000, 12000, 24000, 60000], // 3s, 6s, 12s, 24s, 60s max
+
+  // Maximum reconnection attempts before giving up
+  MAX_RECONNECT_ATTEMPTS: 10,
+};
+
+/**
+ * Selection buffer configuration
+ */
+export const SELECTION = {
+  // Maximum number of active selections (multi-selection limit)
+  MAX_ACTIVE: 10,
+
+  // Maximum number of selections to keep in history
+  MAX_HISTORY: 50,
+
+  // UserPromptSubmit hook timeout (Claude Code enforced)
+  HOOK_TIMEOUT: 2000, // 2 seconds
+
+  // IPC endpoint timeout (should be fast to not block prompts)
+  IPC_TIMEOUT: 500, // 500 milliseconds
+};
+
+/**
+ * Extension badge states
+ */
+export const BADGE_STATES = {
+  CONNECTED: {
+    color: '#10b981', // Green
+    text: '',
+  },
+  DISCONNECTED: {
+    color: '#f59e0b', // Yellow/Orange
+    text: '!',
+  },
+  ERROR: {
+    color: '#ef4444', // Red
+    text: 'X',
+  },
+};
+
+/**
+ * Highlight overlay styles (for picker mode)
+ */
+export const HIGHLIGHT_STYLES = {
+  BORDER_COLOR: '#0ea5e9', // Sky blue
+  BORDER_WIDTH: '2px',
+  BACKGROUND_COLOR: 'rgba(14, 165, 233, 0.1)', // 10% opacity sky blue
+  BORDER_RADIUS: '2px',
+  TRANSITION: 'all 0.05s ease-out',
+  Z_INDEX: '2147483647', // Max z-index
+};
+
+/**
+ * React detection configuration
+ */
+export const REACT_CONFIG = {
+  // Maximum depth when building component tree
+  MAX_COMPONENT_TREE_DEPTH: 5,
+
+  // Maximum length for stringified props before truncation
+  MAX_PROPS_LENGTH: 200,
+
+  // Fiber property key patterns to search for
+  FIBER_KEY_PATTERNS: ['__reactFiber', '__reactInternalInstance'],
+
+  // Container key pattern for version detection
+  CONTAINER_KEY_PATTERN: '__reactContainer',
+};
+
+/**
+ * Tailwind CSS class patterns for detection
+ */
+export const TAILWIND_PATTERNS = [
+  /^bg-/, /^text-/, /^flex/, /^grid/, /^p-/, /^m-/,
+  /^w-/, /^h-/, /^rounded/, /^shadow/, /^border/,
+  /^hover:/, /^focus:/, /^active:/, /^transition/,
+];