sonance-brand-mcp 1.3.88 → 1.3.89

package/dist/assets/api/sonance-vision-apply/route.ts

@@ -229,6 +229,109 @@ function findElementIdInFile(
   return null;
 }
 
+/**
+ * PHASE 0: Deterministic Element ID Search (Cursor-style)
+ * Grep entire codebase for the element ID. If found in multiple files,
+ * use the current route to disambiguate (prioritize page file for route).
+ * 
+ * This is the most reliable signal - like Cursor knowing which file you're in.
+ * Element IDs should be unique, so if we find one, that's THE file.
+ */
+function findFilesByElementId(
+  projectRoot: string,
+  elementId: string,
+  currentRoute: string,
+  discoverPageFileFn: (route: string, projectRoot: string) => string | null
+): { path: string; lineNumber: number; isRouteMatch: boolean }[] {
+  const pattern = new RegExp(`id=["'\`]${elementId}["'\`]`);
+  const matches: { path: string; lineNumber: number; isRouteMatch: boolean }[] = [];
+  
+  // Determine expected page file from route
+  const routePageFile = discoverPageFileFn(currentRoute, projectRoot);
+  
+  // Search all common project directories that exist
+  // This supports: src/app, app/, pages/, components/, lib/ structures
+  const commonDirs = ['src', 'app', 'pages', 'components', 'lib'];
+  const searchDirs = commonDirs
+    .map(dir => path.join(projectRoot, dir))
+    .filter(dir => {
+      try {
+        return fs.existsSync(dir) && fs.statSync(dir).isDirectory();
+      } catch {
+        return false;
+      }
+    });
+  
+  // If no standard dirs found, search project root (excluding node_modules)
+  if (searchDirs.length === 0) {
+    searchDirs.push(projectRoot);
+  }
+  
+  debugLog("PHASE 0: Searching for element ID", { 
+    elementId, 
+    currentRoute, 
+    routePageFile,
+    searchDirs: searchDirs.map(d => d.replace(projectRoot + '/', ''))
+  });
+  
+  function searchDirRecursive(dir: string): void {
+    try {
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        
+        // Skip node_modules, hidden directories, and build outputs
+        if (entry.isDirectory()) {
+          if (
+            entry.name.includes('node_modules') || 
+            entry.name.startsWith('.') ||
+            entry.name === 'dist' ||
+            entry.name === 'build' ||
+            entry.name === '.next'
+          ) {
+            continue;
+          }
+          searchDirRecursive(fullPath);
+        } else if (entry.isFile() && /\.(tsx?|jsx?)$/.test(entry.name)) {
+          try {
+            const content = fs.readFileSync(fullPath, 'utf-8');
+            const lines = content.split('\n');
+            for (let i = 0; i < lines.length; i++) {
+              if (pattern.test(lines[i])) {
+                const relativePath = fullPath.replace(projectRoot + '/', '');
+                const isRouteMatch = relativePath === routePageFile;
+                matches.push({
+                  path: relativePath,
+                  lineNumber: i + 1,
+                  isRouteMatch
+                });
+                debugLog("PHASE 0: Found ID match", { 
+                  file: relativePath, 
+                  line: i + 1, 
+                  isRouteMatch 
+                });
+                break; // One match per file is enough
+              }
+            }
+          } catch {
+            // Skip files that can't be read
+          }
+        }
+      }
+    } catch {
+      // Skip directories that can't be read
+    }
+  }
+  
+  // Search all directories
+  for (const searchDir of searchDirs) {
+    searchDirRecursive(searchDir);
+  }
+  
+  // Sort: route matches first
+  return matches.sort((a, b) => (b.isRouteMatch ? 1 : 0) - (a.isRouteMatch ? 1 : 0));
+}
+
 /**
  * Result of LLM screenshot analysis for smart file discovery
  */
@@ -927,12 +1030,73 @@ export async function POST(request: Request) {
       // Generate a unique session ID
       const newSessionId = randomUUID().slice(0, 8);
 
-      // PHASE 1+2: LLM-driven smart file discovery
-      // The LLM analyzes the screenshot and deduces component names, code patterns, and visible text
+      // Initialize file discovery variables
       let smartSearchFiles: { path: string; content: string }[] = [];
       let recommendedFile: { path: string; reason: string } | null = null;
-      
-      if (screenshot) {
+      let deterministicMatch: { path: string; lineNumber: number } | null = null;
+
+      // ========================================================================
+      // PHASE 0: Deterministic Element ID Search (Cursor-style explicit selection)
+      // If we have an element ID, find it directly - no scoring, no heuristics
+      // This is the most reliable signal, like Cursor knowing which file you're in
+      // ========================================================================
+      if (focusedElements?.some(el => el.elementId)) {
+        const elementWithId = focusedElements.find(el => el.elementId)!;
+        debugLog("PHASE 0: Element has ID, starting deterministic search", {
+          elementId: elementWithId.elementId,
+          route: pageRoute
+        });
+        
+        const matches = findFilesByElementId(
+          projectRoot, 
+          elementWithId.elementId!, 
+          pageRoute || "/",
+          discoverPageFile
+        );
+        
+        if (matches.length === 1) {
+          // Single match - 100% confidence
+          deterministicMatch = matches[0];
+          recommendedFile = {
+            path: matches[0].path,
+            reason: `Deterministic ID match: id="${elementWithId.elementId}" (unique in codebase)`
+          };
+          debugLog("PHASE 0 SUCCESS: Single ID match - skipping smart search", deterministicMatch);
+        } else if (matches.length > 1) {
+          // Multiple matches - use route to disambiguate
+          const routeMatch = matches.find(m => m.isRouteMatch);
+          if (routeMatch) {
+            deterministicMatch = routeMatch;
+            recommendedFile = {
+              path: routeMatch.path,
+              reason: `Deterministic ID match: id="${elementWithId.elementId}" (route "${pageRoute}" disambiguated from ${matches.length} files)`
+            };
+            debugLog("PHASE 0 SUCCESS: ID found in multiple files, using route match", {
+              match: deterministicMatch,
+              otherFiles: matches.filter(m => !m.isRouteMatch).map(m => m.path)
+            });
+          } else {
+            debugLog("PHASE 0 FALLBACK: ID found in multiple files, no route match", {
+              elementId: elementWithId.elementId,
+              matchCount: matches.length,
+              files: matches.map(m => m.path),
+              route: pageRoute
+            });
+            // Fall through to smart search
+          }
+        } else {
+          debugLog("PHASE 0 FALLBACK: Element ID not found in codebase", {
+            elementId: elementWithId.elementId
+          });
+          // Fall through to smart search
+        }
+      }
+
+      // ========================================================================
+      // PHASE 1+2: LLM-driven smart file discovery (only if Phase 0 didn't match)
+      // The LLM analyzes the screenshot and deduces component names, code patterns, and visible text
+      // ========================================================================
+      if (!deterministicMatch && screenshot) {
         debugLog("Starting Phase 1: LLM screenshot analysis");
         const analysis = await analyzeScreenshotForSearch(screenshot, userPrompt, apiKey);
 
@@ -1024,8 +1188,12 @@ export async function POST(request: Request) {
             return bestMatch;
           };
 
+          // ====================================================================
+          // FALLBACK PRIORITY LOGIC (only reached when Phase 0 didn't find a match)
+          // This handles cases: no element ID, dynamic IDs, or ambiguous ID matches
+          // ====================================================================
           if (phase2aConfirmed) {
-            // PRIORITY 1: Phase 2a match confirmed by element search - highest confidence
+            // FALLBACK PRIORITY 1: Phase 2a match confirmed by element search
             const confirmedPath = phase2aMatches.find(p => 
               focusedElementHints.some(h => h.path === p && h.score > 0)
             );
@@ -1033,33 +1201,47 @@ export async function POST(request: Request) {
               path: confirmedPath!,
               reason: `Phase 2a component-name match confirmed by element search`
             };
-            debugLog("PRIORITY 1: Phase 2a confirmed by element search", recommendedFile);
+            debugLog("FALLBACK PRIORITY 1: Phase 2a confirmed by element search", recommendedFile);
           } else if (focusedTopScore > smartSearchTopScore * 0.5 && focusedTopScore >= 400) {
-            // PRIORITY 2: Focused element has strong absolute score AND relative to smart search
+            // FALLBACK PRIORITY 2: Focused element has strong score
             recommendedFile = {
               path: focusedTopPath!,
               reason: `Focused element match (score: ${focusedTopScore}, exceeds threshold)`
             };
-            debugLog("PRIORITY 2: Strong focused element match", recommendedFile);
+            debugLog("FALLBACK PRIORITY 2: Strong focused element match", recommendedFile);
           } else if (phase2aMatches.length > 0) {
-            // PRIORITY 2.5: Phase 2a match WITHOUT focused element - still strong signal
+            // FALLBACK PRIORITY 3: Phase 2a match WITHOUT focused element
             // Use prompt-aware selection to pick the best match
             const bestMatch = findBestPhase2aMatch()!;
             recommendedFile = {
               path: bestMatch,
               reason: `Phase 2a component-name match (prompt-aware selection from ${phase2aMatches.length} candidates)`
             };
-            debugLog("PRIORITY 2.5: Phase 2a match (no focused element)", { 
+            debugLog("FALLBACK PRIORITY 3: Phase 2a match (no focused element)", { 
               selectedPath: bestMatch,
               allCandidates: phase2aMatches 
             });
-          } else if (smartSearchTopPath) {
-            // PRIORITY 3: Smart search top result - trusted baseline
-            recommendedFile = {
-              path: smartSearchTopPath,
-              reason: `Smart search top result (score: ${smartSearchTopScore})`
-            };
-            debugLog("PRIORITY 3: Using smart search top result", recommendedFile);
+          } else {
+            // FALLBACK PRIORITY 4: Use the page file from the current route
+            const routePageFile = discoverPageFile(pageRoute || "/", projectRoot);
+            
+            if (routePageFile && fs.existsSync(path.join(projectRoot, routePageFile))) {
+              recommendedFile = {
+                path: routePageFile,
+                reason: `Page file from route "${pageRoute || "/"}"`
+              };
+              debugLog("FALLBACK PRIORITY 4: Using page file from route", { 
+                route: pageRoute || "/",
+                pageFile: routePageFile 
+              });
+            } else if (smartSearchTopPath) {
+              // FALLBACK PRIORITY 5: Smart search top result - last resort
+              recommendedFile = {
+                path: smartSearchTopPath,
+                reason: `Smart search top result (score: ${smartSearchTopScore})`
+              };
+              debugLog("FALLBACK PRIORITY 5: Using smart search top result", recommendedFile);
+            }
           }
           
           debugLog("Phase 1+2 complete", {

package/dist/assets/api/sonance-vision-edit/route.ts

@@ -225,6 +225,109 @@ function findElementIdInFile(
   return null;
 }
 
+/**
+ * PHASE 0: Deterministic Element ID Search (Cursor-style)
+ * Grep entire codebase for the element ID. If found in multiple files,
+ * use the current route to disambiguate (prioritize page file for route).
+ * 
+ * This is the most reliable signal - like Cursor knowing which file you're in.
+ * Element IDs should be unique, so if we find one, that's THE file.
+ */
+function findFilesByElementId(
+  projectRoot: string,
+  elementId: string,
+  currentRoute: string,
+  discoverPageFileFn: (route: string, projectRoot: string) => string | null
+): { path: string; lineNumber: number; isRouteMatch: boolean }[] {
+  const pattern = new RegExp(`id=["'\`]${elementId}["'\`]`);
+  const matches: { path: string; lineNumber: number; isRouteMatch: boolean }[] = [];
+  
+  // Determine expected page file from route
+  const routePageFile = discoverPageFileFn(currentRoute, projectRoot);
+  
+  // Search all common project directories that exist
+  // This supports: src/app, app/, pages/, components/, lib/ structures
+  const commonDirs = ['src', 'app', 'pages', 'components', 'lib'];
+  const searchDirs = commonDirs
+    .map(dir => path.join(projectRoot, dir))
+    .filter(dir => {
+      try {
+        return fs.existsSync(dir) && fs.statSync(dir).isDirectory();
+      } catch {
+        return false;
+      }
+    });
+  
+  // If no standard dirs found, search project root (excluding node_modules)
+  if (searchDirs.length === 0) {
+    searchDirs.push(projectRoot);
+  }
+  
+  debugLog("PHASE 0: Searching for element ID", { 
+    elementId, 
+    currentRoute, 
+    routePageFile,
+    searchDirs: searchDirs.map(d => d.replace(projectRoot + '/', ''))
+  });
+  
+  function searchDirRecursive(dir: string): void {
+    try {
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        
+        // Skip node_modules, hidden directories, and build outputs
+        if (entry.isDirectory()) {
+          if (
+            entry.name.includes('node_modules') || 
+            entry.name.startsWith('.') ||
+            entry.name === 'dist' ||
+            entry.name === 'build' ||
+            entry.name === '.next'
+          ) {
+            continue;
+          }
+          searchDirRecursive(fullPath);
+        } else if (entry.isFile() && /\.(tsx?|jsx?)$/.test(entry.name)) {
+          try {
+            const content = fs.readFileSync(fullPath, 'utf-8');
+            const lines = content.split('\n');
+            for (let i = 0; i < lines.length; i++) {
+              if (pattern.test(lines[i])) {
+                const relativePath = fullPath.replace(projectRoot + '/', '');
+                const isRouteMatch = relativePath === routePageFile;
+                matches.push({
+                  path: relativePath,
+                  lineNumber: i + 1,
+                  isRouteMatch
+                });
+                debugLog("PHASE 0: Found ID match", { 
+                  file: relativePath, 
+                  line: i + 1, 
+                  isRouteMatch 
+                });
+                break; // One match per file is enough
+              }
+            }
+          } catch {
+            // Skip files that can't be read
+          }
+        }
+      }
+    } catch {
+      // Skip directories that can't be read
+    }
+  }
+  
+  // Search all directories
+  for (const searchDir of searchDirs) {
+    searchDirRecursive(searchDir);
+  }
+  
+  // Sort: route matches first
+  return matches.sort((a, b) => (b.isRouteMatch ? 1 : 0) - (a.isRouteMatch ? 1 : 0));
+}
+
 /**
  * Result of LLM screenshot analysis for smart file discovery
  */
@@ -896,12 +999,73 @@ export async function POST(request: Request) {
         );
       }
 
-      // PHASE 1+2: LLM-driven smart file discovery
-      // The LLM analyzes the screenshot and deduces component names, code patterns, and visible text
+      // Initialize file discovery variables
       let smartSearchFiles: { path: string; content: string }[] = [];
       let recommendedFile: { path: string; reason: string } | null = null;
-      
-      if (screenshot) {
+      let deterministicMatch: { path: string; lineNumber: number } | null = null;
+
+      // ========================================================================
+      // PHASE 0: Deterministic Element ID Search (Cursor-style explicit selection)
+      // If we have an element ID, find it directly - no scoring, no heuristics
+      // This is the most reliable signal, like Cursor knowing which file you're in
+      // ========================================================================
+      if (focusedElements?.some(el => el.elementId)) {
+        const elementWithId = focusedElements.find(el => el.elementId)!;
+        debugLog("PHASE 0: Element has ID, starting deterministic search", {
+          elementId: elementWithId.elementId,
+          route: pageRoute
+        });
+        
+        const matches = findFilesByElementId(
+          projectRoot, 
+          elementWithId.elementId!, 
+          pageRoute || "/",
+          discoverPageFile
+        );
+        
+        if (matches.length === 1) {
+          // Single match - 100% confidence
+          deterministicMatch = matches[0];
+          recommendedFile = {
+            path: matches[0].path,
+            reason: `Deterministic ID match: id="${elementWithId.elementId}" (unique in codebase)`
+          };
+          debugLog("PHASE 0 SUCCESS: Single ID match - skipping smart search", deterministicMatch);
+        } else if (matches.length > 1) {
+          // Multiple matches - use route to disambiguate
+          const routeMatch = matches.find(m => m.isRouteMatch);
+          if (routeMatch) {
+            deterministicMatch = routeMatch;
+            recommendedFile = {
+              path: routeMatch.path,
+              reason: `Deterministic ID match: id="${elementWithId.elementId}" (route "${pageRoute}" disambiguated from ${matches.length} files)`
+            };
+            debugLog("PHASE 0 SUCCESS: ID found in multiple files, using route match", {
+              match: deterministicMatch,
+              otherFiles: matches.filter(m => !m.isRouteMatch).map(m => m.path)
+            });
+          } else {
+            debugLog("PHASE 0 FALLBACK: ID found in multiple files, no route match", {
+              elementId: elementWithId.elementId,
+              matchCount: matches.length,
+              files: matches.map(m => m.path),
+              route: pageRoute
+            });
+            // Fall through to smart search
+          }
+        } else {
+          debugLog("PHASE 0 FALLBACK: Element ID not found in codebase", {
+            elementId: elementWithId.elementId
+          });
+          // Fall through to smart search
+        }
+      }
+
+      // ========================================================================
+      // PHASE 1+2: LLM-driven smart file discovery (only if Phase 0 didn't match)
+      // The LLM analyzes the screenshot and deduces component names, code patterns, and visible text
+      // ========================================================================
+      if (!deterministicMatch && screenshot) {
         debugLog("Starting Phase 1: LLM screenshot analysis");
         const analysis = await analyzeScreenshotForSearch(screenshot, userPrompt, apiKey);
 
@@ -993,8 +1157,12 @@ export async function POST(request: Request) {
             return bestMatch;
           };
 
+          // ====================================================================
+          // FALLBACK PRIORITY LOGIC (only reached when Phase 0 didn't find a match)
+          // This handles cases: no element ID, dynamic IDs, or ambiguous ID matches
+          // ====================================================================
           if (phase2aConfirmed) {
-            // PRIORITY 1: Phase 2a match confirmed by element search - highest confidence
+            // FALLBACK PRIORITY 1: Phase 2a match confirmed by element search
             const confirmedPath = phase2aMatches.find(p => 
               focusedElementHints.some(h => h.path === p && h.score > 0)
             );
@@ -1002,33 +1170,47 @@ export async function POST(request: Request) {
               path: confirmedPath!,
               reason: `Phase 2a component-name match confirmed by element search`
             };
-            debugLog("PRIORITY 1: Phase 2a confirmed by element search", recommendedFile);
+            debugLog("FALLBACK PRIORITY 1: Phase 2a confirmed by element search", recommendedFile);
           } else if (focusedTopScore > smartSearchTopScore * 0.5 && focusedTopScore >= 400) {
-            // PRIORITY 2: Focused element has strong absolute score AND relative to smart search
+            // FALLBACK PRIORITY 2: Focused element has strong score
             recommendedFile = {
               path: focusedTopPath!,
               reason: `Focused element match (score: ${focusedTopScore}, exceeds threshold)`
             };
-            debugLog("PRIORITY 2: Strong focused element match", recommendedFile);
+            debugLog("FALLBACK PRIORITY 2: Strong focused element match", recommendedFile);
           } else if (phase2aMatches.length > 0) {
-            // PRIORITY 2.5: Phase 2a match WITHOUT focused element - still strong signal
+            // FALLBACK PRIORITY 3: Phase 2a match WITHOUT focused element
             // Use prompt-aware selection to pick the best match
             const bestMatch = findBestPhase2aMatch()!;
             recommendedFile = {
               path: bestMatch,
               reason: `Phase 2a component-name match (prompt-aware selection from ${phase2aMatches.length} candidates)`
             };
-            debugLog("PRIORITY 2.5: Phase 2a match (no focused element)", { 
+            debugLog("FALLBACK PRIORITY 3: Phase 2a match (no focused element)", { 
               selectedPath: bestMatch,
               allCandidates: phase2aMatches 
             });
-          } else if (smartSearchTopPath) {
-            // PRIORITY 3: Smart search top result - trusted baseline
-            recommendedFile = {
-              path: smartSearchTopPath,
-              reason: `Smart search top result (score: ${smartSearchTopScore})`
-            };
-            debugLog("PRIORITY 3: Using smart search top result", recommendedFile);
+          } else {
+            // FALLBACK PRIORITY 4: Use the page file from the current route
+            const routePageFile = discoverPageFile(pageRoute || "/", projectRoot);
+            
+            if (routePageFile && fs.existsSync(path.join(projectRoot, routePageFile))) {
+              recommendedFile = {
+                path: routePageFile,
+                reason: `Page file from route "${pageRoute || "/"}"`
+              };
+              debugLog("FALLBACK PRIORITY 4: Using page file from route", { 
+                route: pageRoute || "/",
+                pageFile: routePageFile 
+              });
+            } else if (smartSearchTopPath) {
+              // FALLBACK PRIORITY 5: Smart search top result - last resort
+              recommendedFile = {
+                path: smartSearchTopPath,
+                reason: `Smart search top result (score: ${smartSearchTopScore})`
+              };
+              debugLog("FALLBACK PRIORITY 5: Using smart search top result", recommendedFile);
+            }
           }
           
           debugLog("Phase 1+2 complete", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sonance-brand-mcp",
-  "version": "1.3.88",
+  "version": "1.3.89",
   "description": "MCP Server for Sonance Brand Guidelines and Component Library - gives Claude instant access to brand colors, typography, and UI components.",
   "main": "dist/index.js",
   "type": "module",