sonance-brand-mcp 1.3.87 → 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);
 
@@ -981,8 +1145,55 @@ export async function POST(request: Request) {
           const phase2aConfirmed = phase2aMatches.length > 0 && 
             focusedElementHints.some(h => phase2aMatches.includes(h.path) && h.score > 0);
 
+          // Helper: Find best Phase 2a match based on user prompt keywords
+          // e.g., "duplicate button" should prefer ProcessRow.tsx over ProcessCatalogueView.tsx
+          const findBestPhase2aMatch = (): string | null => {
+            if (phase2aMatches.length === 0) return null;
+            if (phase2aMatches.length === 1) return phase2aMatches[0];
+            
+            // Extract keywords from user prompt
+            const promptLower = userPrompt.toLowerCase();
+            const keywords = ['row', 'cell', 'item', 'button', 'action', 'duplicate', 'edit', 'delete'];
+            
+            // Prefer more specific files (Row > View, Cell > Table, etc.)
+            const specificity = ['row', 'cell', 'item', 'card', 'modal', 'panel', 'detail'];
+            
+            // Score each Phase 2a match
+            let bestMatch = phase2aMatches[0];
+            let bestScore = 0;
+            
+            for (const match of phase2aMatches) {
+              const matchLower = match.toLowerCase();
+              let score = 0;
+              
+              // Bonus for specificity (Row/Cell/Item components)
+              for (const spec of specificity) {
+                if (matchLower.includes(spec)) score += 10;
+              }
+              
+              // Bonus for keyword match (prompt mentions button → prefer file with button/action)
+              for (const kw of keywords) {
+                if (promptLower.includes(kw) && matchLower.includes(kw)) score += 20;
+              }
+              
+              // Penalty for generic view/container files
+              if (matchLower.includes('view.tsx') && !matchLower.includes('detail')) score -= 5;
+              
+              if (score > bestScore) {
+                bestScore = score;
+                bestMatch = match;
+              }
+            }
+            
+            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)
             );
@@ -990,21 +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);
-          } else if (smartSearchTopPath) {
-            // PRIORITY 3: Smart search top result - trusted baseline
+            debugLog("FALLBACK PRIORITY 2: Strong focused element match", recommendedFile);
+          } else if (phase2aMatches.length > 0) {
+            // FALLBACK PRIORITY 3: Phase 2a match WITHOUT focused element
+            // Use prompt-aware selection to pick the best match
+            const bestMatch = findBestPhase2aMatch()!;
             recommendedFile = {
-              path: smartSearchTopPath,
-              reason: `Smart search top result (score: ${smartSearchTopScore})`
+              path: bestMatch,
+              reason: `Phase 2a component-name match (prompt-aware selection from ${phase2aMatches.length} candidates)`
             };
-            debugLog("PRIORITY 3: Using smart search top result", recommendedFile);
+            debugLog("FALLBACK PRIORITY 3: Phase 2a match (no focused element)", { 
+              selectedPath: bestMatch,
+              allCandidates: phase2aMatches 
+            });
+          } 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);
 
@@ -950,8 +1114,55 @@ export async function POST(request: Request) {
           const phase2aConfirmed = phase2aMatches.length > 0 && 
             focusedElementHints.some(h => phase2aMatches.includes(h.path) && h.score > 0);
 
+          // Helper: Find best Phase 2a match based on user prompt keywords
+          // e.g., "duplicate button" should prefer ProcessRow.tsx over ProcessCatalogueView.tsx
+          const findBestPhase2aMatch = (): string | null => {
+            if (phase2aMatches.length === 0) return null;
+            if (phase2aMatches.length === 1) return phase2aMatches[0];
+            
+            // Extract keywords from user prompt
+            const promptLower = userPrompt.toLowerCase();
+            const keywords = ['row', 'cell', 'item', 'button', 'action', 'duplicate', 'edit', 'delete'];
+            
+            // Prefer more specific files (Row > View, Cell > Table, etc.)
+            const specificity = ['row', 'cell', 'item', 'card', 'modal', 'panel', 'detail'];
+            
+            // Score each Phase 2a match
+            let bestMatch = phase2aMatches[0];
+            let bestScore = 0;
+            
+            for (const match of phase2aMatches) {
+              const matchLower = match.toLowerCase();
+              let score = 0;
+              
+              // Bonus for specificity (Row/Cell/Item components)
+              for (const spec of specificity) {
+                if (matchLower.includes(spec)) score += 10;
+              }
+              
+              // Bonus for keyword match (prompt mentions button → prefer file with button/action)
+              for (const kw of keywords) {
+                if (promptLower.includes(kw) && matchLower.includes(kw)) score += 20;
+              }
+              
+              // Penalty for generic view/container files
+              if (matchLower.includes('view.tsx') && !matchLower.includes('detail')) score -= 5;
+              
+              if (score > bestScore) {
+                bestScore = score;
+                bestMatch = match;
+              }
+            }
+            
+            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)
             );
@@ -959,21 +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);
-          } else if (smartSearchTopPath) {
-            // PRIORITY 3: Smart search top result - trusted baseline
+            debugLog("FALLBACK PRIORITY 2: Strong focused element match", recommendedFile);
+          } else if (phase2aMatches.length > 0) {
+            // FALLBACK PRIORITY 3: Phase 2a match WITHOUT focused element
+            // Use prompt-aware selection to pick the best match
+            const bestMatch = findBestPhase2aMatch()!;
             recommendedFile = {
-              path: smartSearchTopPath,
-              reason: `Smart search top result (score: ${smartSearchTopScore})`
+              path: bestMatch,
+              reason: `Phase 2a component-name match (prompt-aware selection from ${phase2aMatches.length} candidates)`
             };
-            debugLog("PRIORITY 3: Using smart search top result", recommendedFile);
+            debugLog("FALLBACK PRIORITY 3: Phase 2a match (no focused element)", { 
+              selectedPath: bestMatch,
+              allCandidates: phase2aMatches 
+            });
+          } 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.87",
+  "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",