mcp-vector-search 0.4.12__py3-none-any.whl → 0.4.14__py3-none-any.whl

mcp_vector_search/cli/main.py

@@ -28,7 +28,9 @@ from .commands.search import (
 )
 from .commands.status import status_app
 from .commands.watch import app as watch_app
+from .commands.reset import reset_app, health_main
 from .didyoumean import create_enhanced_typer, add_common_suggestions
+from .suggestions import get_contextual_suggestions, ContextualSuggestionProvider
 from .output import print_error, setup_logging
 
 # Install rich traceback handler
@@ -45,9 +47,11 @@ app = create_enhanced_typer(
     rich_markup_mode="rich",
 )
 
-# Add install command directly (not as subcommand app)
+# Import command functions for direct registration and aliases
 from .commands.install import main as install_main, demo as install_demo
 from .commands.status import main as status_main
+from .commands.index import main as index_main
+# Note: config doesn't have a main function, it uses subcommands via config_app
 app.command("install", help="🚀 Install mcp-vector-search in projects")(install_main)
 app.command("demo", help="🎬 Run installation demo with sample project")(install_demo)
 app.command("status", help="📊 Show project status and statistics")(status_main)
@@ -62,6 +66,7 @@ app.add_typer(config_app, name="config", help="Manage project configuration")
 app.add_typer(watch_app, name="watch", help="Watch for file changes and update index")
 app.add_typer(auto_index_app, name="auto-index", help="Manage automatic indexing")
 app.add_typer(mcp_app, name="mcp", help="Manage Claude Code MCP integration")
+app.add_typer(reset_app, name="reset", help="Reset and recovery operations")
 
 # Add search command - simplified syntax as default
 app.command("search", help="Search code semantically")(search_main)
@@ -69,13 +74,34 @@ app.command("search", help="Search code semantically")(search_main)
 # Keep old nested structure for backward compatibility
 app.add_typer(search_app, name="search-legacy", help="Legacy search commands", hidden=True)
 app.add_typer(status_app, name="status-legacy", help="Legacy status commands", hidden=True)
+
+# Add command aliases for better user experience
 app.command("find", help="Search code semantically (alias for search)")(search_main)
+app.command("f", help="Search code semantically (short alias)", hidden=True)(search_main)  # Hidden short alias
+app.command("s", help="Search code semantically (short alias)", hidden=True)(search_main)  # Hidden short alias
+app.command("query", help="Search code semantically (alias for search)", hidden=True)(search_main)  # Hidden alias
+
+# Index aliases
+app.command("i", help="Index codebase (short alias)", hidden=True)(index_main)  # Hidden short alias
+app.command("build", help="Index codebase (alias for index)", hidden=True)(index_main)  # Hidden alias
+app.command("scan", help="Index codebase (alias for index)", hidden=True)(index_main)  # Hidden alias
+
+# Status aliases  
+app.command("st", help="Show status (short alias)", hidden=True)(status_main)  # Hidden short alias
+app.command("info", help="Show project information (alias for status)", hidden=True)(status_main)  # Hidden alias
+
+# Config aliases - Since config uses subcommands, these will be handled by the enhanced typer error resolution
+# app.command("c", help="Manage configuration (short alias)", hidden=True)  # Will be handled by typo resolution
+# app.command("cfg", help="Manage configuration (alias for config)", hidden=True)  # Will be handled by typo resolution
+
+# Specialized search commands
 app.command("search-similar", help="Find code similar to a specific file or function")(
     search_similar_cmd
 )
 app.command("search-context", help="Search for code based on contextual description")(
     search_context_cmd
 )
+app.command("health", help="Check index health and optionally repair")(health_main)
 
 
 # Add interactive search command
@@ -86,7 +112,15 @@ def interactive_search(
         None, "--project-root", "-p", help="Project root directory"
     ),
 ) -> None:
-    """Start an interactive search session with filtering and refinement."""
+    """Start an interactive search session with filtering and refinement.
+
+    The interactive mode provides a rich terminal interface for searching your codebase
+    with real-time filtering, query refinement, and result navigation.
+
+    Examples:
+        mcp-vector-search interactive
+        mcp-vector-search interactive --project-root /path/to/project
+    """
     import asyncio
 
     from .interactive import start_interactive_search
@@ -111,7 +145,15 @@ def show_history(
         None, "--project-root", "-p", help="Project root directory"
     ),
 ) -> None:
-    """Show search history."""
+    """Show search history.
+
+    Displays your recent search queries with timestamps and result counts.
+    Use this to revisit previous searches or track your search patterns.
+
+    Examples:
+        mcp-vector-search history
+        mcp-vector-search history --limit 50
+    """
     from .history import show_search_history
 
     root = project_root or ctx.obj.get("project_root") or Path.cwd()
@@ -125,7 +167,14 @@ def show_favorites_cmd(
         None, "--project-root", "-p", help="Project root directory"
     ),
 ) -> None:
-    """Show favorite queries."""
+    """Show favorite queries.
+
+    Displays your saved favorite search queries. Favorites allow you to quickly
+    access frequently used searches without typing them again.
+
+    Examples:
+        mcp-vector-search favorites
+    """
     from .history import show_favorites
 
     root = project_root or ctx.obj.get("project_root") or Path.cwd()
@@ -141,7 +190,15 @@ def add_favorite(
         None, "--project-root", "-p", help="Project root directory"
     ),
 ) -> None:
-    """Add a query to favorites."""
+    """Add a query to favorites.
+
+    Save a search query to your favorites list for quick access later.
+    Optionally include a description to help remember what the query is for.
+
+    Examples:
+        mcp-vector-search add-favorite "authentication functions"
+        mcp-vector-search add-favorite "error handling" --desc "Error handling patterns"
+    """
     from .history import SearchHistory
 
     root = project_root or ctx.obj.get("project_root") or Path.cwd()
@@ -157,7 +214,13 @@ def remove_favorite(
         None, "--project-root", "-p", help="Project root directory"
     ),
 ) -> None:
-    """Remove a query from favorites."""
+    """Remove a query from favorites.
+
+    Remove a previously saved favorite query from your favorites list.
+
+    Examples:
+        mcp-vector-search remove-favorite "authentication functions"
+    """
     from .history import SearchHistory
 
     root = project_root or ctx.obj.get("project_root") or Path.cwd()
@@ -208,6 +271,8 @@ def main(
         if project_root:
             logger.info(f"Using project root: {project_root}")
 
+    # Note: Contextual help moved to a separate command to avoid interfering with didyoumean
+
 
 @app.command()
 def version() -> None:
@@ -220,7 +285,7 @@ def version() -> None:
 
 
 def handle_command_error(ctx, param, value):
-    """Handle command errors with suggestions."""
+    """Handle command errors with enhanced suggestions."""
     if ctx.resilient_parsing:
         return
 
@@ -235,13 +300,44 @@ def handle_command_error(ctx, param, value):
             match = re.search(r"No such command '([^']+)'", str(e))
             if match:
                 command_name = match.group(1)
+                
+                # Use both the original suggestions and contextual suggestions
                 add_common_suggestions(ctx, command_name)
+                
+                # Add contextual suggestions based on project state
+                try:
+                    project_root = ctx.obj.get("project_root") if ctx.obj else None
+                    get_contextual_suggestions(project_root, command_name)
+                except Exception:
+                    # If contextual suggestions fail, don't break the error flow
+                    pass
         raise
 
 
+
+
+@app.command()
+def help_contextual() -> None:
+    """Show contextual help and suggestions based on project state."""
+    try:
+        project_root = Path.cwd()
+        console.print(f"[bold blue]mcp-vector-search[/bold blue] version [green]{__version__}[/green]")
+        console.print("[dim]CLI-first semantic code search with MCP integration[/dim]")
+        get_contextual_suggestions(project_root)
+    except Exception as e:
+        console.print("\n[dim]Use [bold]mcp-vector-search --help[/bold] for more information.[/dim]")
+
+
 @app.command()
 def doctor() -> None:
-    """Check system dependencies and configuration."""
+    """Check system dependencies and configuration.
+
+    Runs diagnostic checks to ensure all required dependencies are installed
+    and properly configured. Use this command to troubleshoot installation issues.
+
+    Examples:
+        mcp-vector-search doctor
+    """
     from .commands.status import check_dependencies
 
     console.print("[bold blue]MCP Vector Search - System Check[/bold blue]\n")
@@ -261,5 +357,58 @@ def doctor() -> None:
 
 
 
+def cli_with_suggestions():
+    """CLI wrapper that catches errors and provides suggestions."""
+    import sys
+    import click
+    
+    try:
+        # Call the app with standalone_mode=False to get exceptions instead of sys.exit
+        app(standalone_mode=False)
+    except click.UsageError as e:
+        # Check if it's a "No such command" error
+        if "No such command" in str(e):
+            # Extract the command name from the error
+            import re
+            match = re.search(r"No such command '([^']+)'", str(e))
+            if match:
+                command_name = match.group(1)
+                
+                # Show enhanced suggestions
+                from rich.console import Console
+                console = Console(stderr=True)
+                console.print(f"\\n[red]Error:[/red] {e}")
+                
+                # Show enhanced suggestions
+                add_common_suggestions(None, command_name)
+                
+                # Show contextual suggestions too
+                try:
+                    project_root = Path.cwd()
+                    get_contextual_suggestions(project_root, command_name)
+                except Exception:
+                    pass
+                
+                sys.exit(2)  # Exit with error code
+        
+        # For other usage errors, show the default message and exit
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(2)
+    except click.Abort:
+        # User interrupted (Ctrl+C)
+        sys.exit(1)
+    except SystemExit as e:
+        # Re-raise system exits
+        raise
+    except Exception as e:
+        # For other exceptions, show error and exit if verbose logging is enabled
+        # Suppress internal framework errors in normal operation
+        if "--verbose" in sys.argv or "-v" in sys.argv:
+            click.echo(f"Unexpected error: {e}", err=True)
+            sys.exit(1)
+        # Otherwise, just exit silently to avoid confusing error messages
+        pass
+
+
 if __name__ == "__main__":
-    app()
+    cli_with_suggestions()

mcp_vector_search/cli/suggestions.py

@@ -0,0 +1,325 @@
+"""Contextual suggestion system for better user experience."""
+
+import json
+from pathlib import Path
+from typing import Dict, List, Optional, Set, Tuple
+from rich.console import Console
+
+from ..core.project import ProjectManager
+from ..core.exceptions import ProjectNotFoundError
+
+
+class ContextualSuggestionProvider:
+    """Provides context-aware suggestions based on project state and user workflow."""
+    
+    def __init__(self, project_root: Optional[Path] = None):
+        """Initialize the suggestion provider.
+        
+        Args:
+            project_root: Root directory of the project (defaults to current directory)
+        """
+        self.project_root = project_root or Path.cwd()
+        self.console = Console(stderr=True)
+        
+    def get_project_state(self) -> Dict[str, bool]:
+        """Analyze the current project state.
+        
+        Returns:
+            Dictionary with boolean flags indicating project state
+        """
+        state = {
+            'is_initialized': False,
+            'has_index': False,
+            'has_config': False,
+            'has_recent_changes': False,
+            'is_git_repo': False,
+            'has_mcp_config': False
+        }
+        
+        try:
+            # Check if project is initialized
+            config_dir = self.project_root / '.mcp-vector-search'
+            state['is_initialized'] = config_dir.exists()
+            
+            if state['is_initialized']:
+                # Check for config
+                config_file = config_dir / 'config.json'
+                state['has_config'] = config_file.exists()
+                
+                # Check for index
+                index_dir = config_dir / 'chroma_db'
+                state['has_index'] = index_dir.exists() and any(index_dir.iterdir())
+                
+            # Check if it's a git repo
+            git_dir = self.project_root / '.git'
+            state['is_git_repo'] = git_dir.exists()
+            
+            # Check for MCP configuration (Claude Desktop config)
+            home = Path.home()
+            claude_config = home / 'Library' / 'Application Support' / 'Claude' / 'claude_desktop_config.json'
+            if claude_config.exists():
+                try:
+                    with open(claude_config) as f:
+                        config_data = json.load(f)
+                        mcp_servers = config_data.get('mcpServers', {})
+                        state['has_mcp_config'] = 'mcp-vector-search' in mcp_servers
+                except (json.JSONDecodeError, IOError):
+                    pass
+            
+            # TODO: Check for recent file changes (would need file system monitoring)
+            # For now, we'll assume false
+            state['has_recent_changes'] = False
+            
+        except Exception:
+            # If we can't determine state, provide conservative defaults
+            pass
+            
+        return state
+    
+    def get_workflow_suggestions(self, failed_command: str) -> List[Dict[str, str]]:
+        """Get workflow-based suggestions for a failed command.
+        
+        Args:
+            failed_command: The command that failed
+            
+        Returns:
+            List of suggestion dictionaries with 'command', 'reason', and 'priority'
+        """
+        suggestions = []
+        state = self.get_project_state()
+        
+        # High priority suggestions based on project state
+        if not state['is_initialized']:
+            suggestions.append({
+                'command': 'init',
+                'reason': 'Project is not initialized for vector search',
+                'priority': 'high',
+                'description': 'Set up the project configuration and create necessary directories'
+            })
+        elif not state['has_index']:
+            suggestions.append({
+                'command': 'index',
+                'reason': 'No search index found - create one to enable searching',
+                'priority': 'high',
+                'description': 'Build the vector index for your codebase'
+            })
+        
+        # Context-specific suggestions based on the failed command
+        if failed_command.lower() in ['search', 'find', 'query', 's', 'f']:
+            if not state['has_index']:
+                suggestions.append({
+                    'command': 'index',
+                    'reason': 'Cannot search without an index',
+                    'priority': 'high',
+                    'description': 'Build the search index first'
+                })
+            else:
+                suggestions.extend([
+                    {
+                        'command': 'search',
+                        'reason': 'Correct command for semantic code search',
+                        'priority': 'high',
+                        'description': 'Search your codebase semantically'
+                    },
+                    {
+                        'command': 'interactive',
+                        'reason': 'Try interactive search for better experience',
+                        'priority': 'medium',
+                        'description': 'Start an interactive search session'
+                    }
+                ])
+        
+        elif failed_command.lower() in ['index', 'build', 'scan', 'i', 'b']:
+            suggestions.append({
+                'command': 'index',
+                'reason': 'Correct command for building search index',
+                'priority': 'high',
+                'description': 'Index your codebase for semantic search'
+            })
+            
+        elif failed_command.lower() in ['status', 'info', 'stat', 'st']:
+            suggestions.append({
+                'command': 'status',
+                'reason': 'Show project status and statistics',
+                'priority': 'high',
+                'description': 'Display current project information'
+            })
+            
+        elif failed_command.lower() in ['config', 'configure', 'settings', 'c']:
+            suggestions.append({
+                'command': 'config',
+                'reason': 'Manage project configuration',
+                'priority': 'high',
+                'description': 'View or modify project settings'
+            })
+        
+        # MCP-related suggestions
+        if not state['has_mcp_config'] and failed_command.lower() in ['mcp', 'claude', 'server']:
+            suggestions.append({
+                'command': 'init-mcp',
+                'reason': 'Set up Claude Code MCP integration',
+                'priority': 'medium',
+                'description': 'Configure MCP server for Claude Code integration'
+            })
+        
+        # Remove duplicates while preserving order
+        seen = set()
+        unique_suggestions = []
+        for suggestion in suggestions:
+            key = suggestion['command']
+            if key not in seen:
+                seen.add(key)
+                unique_suggestions.append(suggestion)
+        
+        return unique_suggestions
+    
+    def get_next_steps(self) -> List[Dict[str, str]]:
+        """Get suggested next steps based on current project state.
+        
+        Returns:
+            List of suggested next step dictionaries
+        """
+        state = self.get_project_state()
+        next_steps = []
+        
+        if not state['is_initialized']:
+            next_steps.append({
+                'command': 'init',
+                'description': 'Initialize the project for semantic search',
+                'priority': 'high'
+            })
+        elif not state['has_index']:
+            next_steps.append({
+                'command': 'index',
+                'description': 'Build the search index for your codebase',
+                'priority': 'high'
+            })
+        else:
+            # Project is ready for use
+            next_steps.extend([
+                {
+                    'command': 'search "your query here"',
+                    'description': 'Search your codebase semantically',
+                    'priority': 'high'
+                },
+                {
+                    'command': 'status',
+                    'description': 'Check project statistics and index health',
+                    'priority': 'medium'
+                }
+            ])
+            
+            if state['has_recent_changes']:
+                next_steps.insert(0, {
+                    'command': 'index --force',
+                    'description': 'Update the index with recent changes',
+                    'priority': 'high'
+                })
+        
+        if not state['has_mcp_config'] and state['is_initialized']:
+            next_steps.append({
+                'command': 'init-mcp',
+                'description': 'Set up Claude Code integration',
+                'priority': 'low'
+            })
+        
+        return next_steps
+    
+    def show_contextual_help(self, failed_command: Optional[str] = None) -> None:
+        """Show contextual help and suggestions.
+        
+        Args:
+            failed_command: The command that failed (if any)
+        """
+        if failed_command:
+            self.console.print(f"\n[yellow]Command '{failed_command}' not recognized.[/yellow]")
+            
+            suggestions = self.get_workflow_suggestions(failed_command)
+            if suggestions:
+                self.console.print("\n[bold]Based on your project state, you might want to try:[/bold]")
+                
+                for i, suggestion in enumerate(suggestions[:3], 1):  # Show top 3
+                    priority_color = {
+                        'high': 'red',
+                        'medium': 'yellow', 
+                        'low': 'dim'
+                    }.get(suggestion['priority'], 'white')
+                    
+                    self.console.print(
+                        f"  [{priority_color}]{i}.[/{priority_color}] "
+                        f"[bold cyan]mcp-vector-search {suggestion['command']}[/bold cyan]"
+                    )
+                    self.console.print(f"     {suggestion['description']}")
+                    if suggestion.get('reason'):
+                        self.console.print(f"     [dim]({suggestion['reason']})[/dim]")
+        else:
+            # Show general next steps
+            next_steps = self.get_next_steps()
+            if next_steps:
+                self.console.print("\n[bold]Suggested next steps:[/bold]")
+                
+                for i, step in enumerate(next_steps[:3], 1):
+                    priority_color = {
+                        'high': 'green',
+                        'medium': 'yellow',
+                        'low': 'dim'
+                    }.get(step['priority'], 'white')
+                    
+                    self.console.print(
+                        f"  [{priority_color}]{i}.[/{priority_color}] "
+                        f"[bold cyan]mcp-vector-search {step['command']}[/bold cyan]"
+                    )
+                    self.console.print(f"     {step['description']}")
+    
+    def get_command_completion_suggestions(self, partial_command: str) -> List[str]:
+        """Get command completion suggestions for a partial command.
+        
+        Args:
+            partial_command: Partial command string
+            
+        Returns:
+            List of possible command completions
+        """
+        all_commands = [
+            'search', 'index', 'status', 'config', 'init', 'mcp', 
+            'doctor', 'version', 'watch', 'auto-index', 'history',
+            'interactive', 'demo', 'install', 'reset', 'health'
+        ]
+        
+        # Add common aliases and shortcuts
+        all_commands.extend(['s', 'i', 'st', 'c', 'f', 'find'])
+        
+        partial_lower = partial_command.lower()
+        matches = [
+            cmd for cmd in all_commands 
+            if cmd.startswith(partial_lower)
+        ]
+        
+        return sorted(matches)
+
+
+def get_contextual_suggestions(project_root: Optional[Path] = None, 
+                             failed_command: Optional[str] = None) -> None:
+    """Get and display contextual suggestions.
+    
+    Args:
+        project_root: Root directory of the project
+        failed_command: The command that failed
+    """
+    provider = ContextualSuggestionProvider(project_root)
+    provider.show_contextual_help(failed_command)
+
+
+def suggest_workflow_commands(project_root: Optional[Path] = None) -> List[str]:
+    """Get workflow command suggestions for the current project state.
+    
+    Args:
+        project_root: Root directory of the project
+        
+    Returns:
+        List of suggested commands in priority order
+    """
+    provider = ContextualSuggestionProvider(project_root)
+    next_steps = provider.get_next_steps()
+    
+    return [step['command'] for step in next_steps]