claude-self-reflect 4.0.3 → 5.0.4

package/docker-compose.yaml

@@ -18,7 +18,9 @@ services:
       - "${QDRANT_PORT:-6333}:6333"
     volumes:
       - qdrant_data:/qdrant/storage
-      - ./config/qdrant-config.yaml:/qdrant/config/config.yaml:ro
+      # Note: Using CONFIG_PATH variable to support global npm installs (fixes #71)
+      # macOS Docker Desktop restricts mounts to /Users, /Volumes, /private, /tmp
+      - ${CONFIG_PATH:-~/.claude-self-reflect/config}/qdrant-config.yaml:/qdrant/config/config.yaml:ro
     environment:
       - QDRANT__LOG_LEVEL=INFO
       - QDRANT__SERVICE__HTTP_PORT=6333

package/installer/setup-wizard-docker.js

@@ -71,23 +71,64 @@ async function checkDocker() {
   try {
     safeExec('docker', ['info'], { stdio: 'ignore' });
     console.log('✅ Docker is installed and running');
-    
+
     // Check docker compose
     try {
       safeExec('docker', ['compose', 'version'], { stdio: 'ignore' });
-      console.log('✅ Docker Compose v2 is available');
+      console.log('✅ Docker Compose is available');
       return true;
     } catch {
-      console.log('❌ Docker Compose v2 not found');
-      console.log('   Please update Docker Desktop to the latest version');
+      console.log('❌ Docker Compose not found');
+      console.log('   Please update Docker Desktop to include Compose v2');
       return false;
     }
   } catch {
-    console.log('❌ Docker is not running or not installed');
-    console.log('\n📋 Please install Docker:');
-    console.log('   • macOS/Windows: https://docker.com/products/docker-desktop');
-    console.log('   • Linux: https://docs.docker.com/engine/install/');
-    console.log('\n   After installation, make sure Docker is running and try again.');
+    console.log('❌ Docker is not running or not installed\n');
+    console.log('📋 Claude Self-Reflect requires Docker Desktop');
+    console.log('   (Includes Docker Engine + Compose - everything you need)\n');
+
+    const platform = process.platform;
+    const arch = process.arch;
+
+    if (platform === 'darwin') {
+      const archType = arch === 'arm64' ? 'Apple Silicon (M1/M2/M3/M4)' : 'Intel';
+      console.log(`🍎 macOS (${archType}) Installation:\n`);
+
+      if (arch === 'arm64') {
+        console.log('   Download: https://desktop.docker.com/mac/main/arm64/Docker.dmg');
+      } else {
+        console.log('   Download: https://desktop.docker.com/mac/main/amd64/Docker.dmg');
+      }
+
+      console.log('   1. Open the downloaded Docker.dmg');
+      console.log('   2. Drag Docker.app to Applications folder');
+      console.log('   3. Launch Docker Desktop from Applications');
+      console.log('   4. Wait for Docker to start (whale icon in menu bar)');
+      console.log('   5. Re-run: claude-self-reflect setup\n');
+
+    } else if (platform === 'win32') {
+      console.log('🪟 Windows Installation:\n');
+      console.log('   Download: https://desktop.docker.com/win/main/amd64/Docker%20Desktop%20Installer.exe');
+      console.log('   1. Run the installer');
+      console.log('   2. Follow installation prompts');
+      console.log('   3. Restart computer if prompted');
+      console.log('   4. Launch Docker Desktop');
+      console.log('   5. Re-run: claude-self-reflect setup\n');
+
+    } else {
+      console.log('🐧 Linux Installation:\n');
+      console.log('   Install Docker Engine (includes Compose):');
+      console.log('   • Ubuntu/Debian: https://docs.docker.com/engine/install/ubuntu/');
+      console.log('   • Fedora: https://docs.docker.com/engine/install/fedora/');
+      console.log('   • Arch: https://wiki.archlinux.org/title/docker');
+      console.log('   • CentOS: https://docs.docker.com/engine/install/centos/\n');
+    }
+
+    console.log('ℹ️  Docker Desktop is free for:');
+    console.log('   • Personal use');
+    console.log('   • Small businesses (<250 employees, <$10M revenue)');
+    console.log('   • Education and open source projects\n');
+
     return false;
   }
 }
@@ -123,6 +164,20 @@ async function configureEnvironment() {
     } catch {
       // No old config directory, nothing to migrate
     }
+
+    // Copy qdrant-config.yaml from npm package to user config directory
+    // This is critical for global npm installs where Docker cannot mount from /opt/homebrew
+    const sourceQdrantConfig = join(projectRoot, 'config', 'qdrant-config.yaml');
+    const targetQdrantConfig = join(userConfigDir, 'qdrant-config.yaml');
+    try {
+      await fs.copyFile(sourceQdrantConfig, targetQdrantConfig);
+      console.log('✅ Qdrant config copied to user directory');
+    } catch (err) {
+      if (err.code !== 'ENOENT') {
+        console.log('⚠️  Could not copy qdrant-config.yaml:', err.message);
+        console.log('   Docker may have issues starting Qdrant service');
+      }
+    }
   } catch (error) {
     console.log(`❌ Could not create config directory: ${error.message}`);
     console.log('   This may cause Docker mount issues. Please check permissions.');

package/mcp-server/src/code_reload_tool.py

@@ -5,11 +5,22 @@ import sys
 import importlib
 import logging
 from pathlib import Path
-from typing import Dict, List, Optional, Literal
+from typing import Dict, List, Optional
 from fastmcp import Context
 from pydantic import Field
 import hashlib
 import json
+import asyncio
+
+# Import security module - handle both relative and absolute imports
+try:
+    from .security_patches import ModuleWhitelist
+except ImportError:
+    try:
+        from security_patches import ModuleWhitelist
+    except ImportError:
+        # Security module is required - fail closed, not open
+        raise RuntimeError("Security module 'security_patches' is required for code reload functionality")
 
 logger = logging.getLogger(__name__)
 
@@ -19,20 +30,36 @@ class CodeReloader:
 
     def __init__(self):
         """Initialize the code reloader."""
-        self.module_hashes: Dict[str, str] = {}
-        self.reload_history: List[Dict] = []
         self.cache_dir = Path.home() / '.claude-self-reflect' / 'reload_cache'
         self.cache_dir.mkdir(parents=True, exist_ok=True)
-        # Test comment: Hot reload test at 2025-09-15
-        logger.info("CodeReloader initialized with hot reload support")
+        self.hash_file = self.cache_dir / 'module_hashes.json'
+        self._lock = asyncio.Lock()  # Thread safety for async operations
+
+        # Load persisted hashes from disk with error handling
+        if self.hash_file.exists():
+            try:
+                with open(self.hash_file, 'r') as f:
+                    self.module_hashes: Dict[str, str] = json.load(f)
+            except (json.JSONDecodeError, IOError) as e:
+                logger.error(f"Failed to load module hashes: {e}. Starting fresh.")
+                self.module_hashes: Dict[str, str] = {}
+        else:
+            self.module_hashes: Dict[str, str] = {}
+
+        self.reload_history: List[Dict] = []
+        logger.info(f"CodeReloader initialized with {len(self.module_hashes)} cached hashes")
 
     def _get_file_hash(self, filepath: Path) -> str:
         """Get SHA256 hash of a file."""
         with open(filepath, 'rb') as f:
             return hashlib.sha256(f.read()).hexdigest()
 
-    def _get_changed_modules(self) -> List[str]:
-        """Detect which modules have changed since last check."""
+    def _detect_changed_modules(self) -> List[str]:
+        """Detect which modules have changed since last check.
+        
+        This method ONLY detects changes, it does NOT update the stored hashes.
+        Use _update_module_hashes() to update hashes after successful reload.
+        """
         changed = []
         src_dir = Path(__file__).parent
 
@@ -43,13 +70,61 @@ class CodeReloader:
             module_name = f"src.{py_file.stem}"
             current_hash = self._get_file_hash(py_file)
 
+            # Only detect changes, DO NOT update hashes here
             if module_name in self.module_hashes:
                 if self.module_hashes[module_name] != current_hash:
                     changed.append(module_name)
+                    logger.debug(f"Change detected in {module_name}: {self.module_hashes[module_name][:8]} -> {current_hash[:8]}")
+            else:
+                # New module not seen before
+                changed.append(module_name)
+                logger.debug(f"New module detected: {module_name}")
+
+        return changed
+
+    def _update_module_hashes(self, modules: Optional[List[str]] = None) -> None:
+        """Update the stored hashes for specified modules or all modules.
+        
+        This should be called AFTER successful reload to mark modules as up-to-date.
+        
+        Args:
+            modules: List of module names to update. If None, updates all modules.
+        """
+        src_dir = Path(__file__).parent
+        updated = []
+
+        for py_file in src_dir.glob("*.py"):
+            if py_file.name == "__pycache__":
+                continue
 
+            module_name = f"src.{py_file.stem}"
+            
+            # If specific modules provided, only update those
+            if modules is not None and module_name not in modules:
+                continue
+            
+            current_hash = self._get_file_hash(py_file)
+            old_hash = self.module_hashes.get(module_name, "new")
             self.module_hashes[module_name] = current_hash
+            
+            if old_hash != current_hash:
+                updated.append(module_name)
+                logger.debug(f"Updated hash for {module_name}: {old_hash[:8] if old_hash != 'new' else 'new'} -> {current_hash[:8]}")
 
-        return changed
+        # Persist the updated hashes to disk using atomic write
+        temp_file = Path(str(self.hash_file) + '.tmp')
+        try:
+            with open(temp_file, 'w') as f:
+                json.dump(self.module_hashes, f, indent=2)
+            # Atomic rename on POSIX systems
+            temp_file.replace(self.hash_file)
+        except Exception as e:
+            logger.error(f"Failed to persist module hashes: {e}")
+            if temp_file.exists():
+                temp_file.unlink()  # Clean up temp file on failure
+        
+        if updated:
+            logger.info(f"Updated hashes for {len(updated)} modules: {', '.join(updated)}")
 
     async def reload_modules(
         self,
@@ -61,93 +136,98 @@ class CodeReloader:
 
         await ctx.debug("Starting code reload process...")
 
-        try:
-            # Track what we're reloading
-            reload_targets = []
-
-            if auto_detect:
-                # Detect changed modules
-                changed = self._get_changed_modules()
-                if changed:
-                    reload_targets.extend(changed)
-                    await ctx.debug(f"Auto-detected changes in: {changed}")
-
-            if modules:
-                # Add explicitly requested modules
-                reload_targets.extend(modules)
-
-            if not reload_targets:
-                return "📊 No modules to reload. All code is up to date!"
-
-            # Perform the reload
-            reloaded = []
-            failed = []
-
-            for module_name in reload_targets:
-                try:
-                    # SECURITY FIX: Validate module is in whitelist
-                    from .security_patches import ModuleWhitelist
-                    if not ModuleWhitelist.is_allowed_module(module_name):
-                        logger.warning(f"Module not in whitelist, skipping: {module_name}")
-                        failed.append((module_name, "Module not in whitelist"))
-                        continue
-
-                    if module_name in sys.modules:
-                        # Store old module reference for rollback
-                        old_module = sys.modules[module_name]
-
-                        # Reload the module
-                        logger.info(f"Reloading module: {module_name}")
-                        reloaded_module = importlib.reload(sys.modules[module_name])
-
-                        # Update any global references if needed
-                        self._update_global_references(module_name, reloaded_module)
-
-                        reloaded.append(module_name)
-                        await ctx.debug(f"✅ Reloaded: {module_name}")
-                    else:
-                        # Module not loaded yet, import it
-                        importlib.import_module(module_name)
-                        reloaded.append(module_name)
-                        await ctx.debug(f"✅ Imported: {module_name}")
-
-                except Exception as e:
-                    logger.error(f"Failed to reload {module_name}: {e}", exc_info=True)
-                    failed.append((module_name, str(e)))
-                    await ctx.debug(f"❌ Failed: {module_name} - {e}")
-
-            # Record reload history
-            self.reload_history.append({
-                "timestamp": os.environ.get('MCP_REQUEST_ID', 'unknown'),
-                "reloaded": reloaded,
-                "failed": failed
-            })
-
-            # Build response
-            response = "🔄 **Code Reload Results**\n\n"
-
-            if reloaded:
-                response += f"**Successfully Reloaded ({len(reloaded)}):**\n"
-                for module in reloaded:
-                    response += f"- ✅ {module}\n"
-                response += "\n"
-
-            if failed:
-                response += f"**Failed to Reload ({len(failed)}):**\n"
-                for module, error in failed:
-                    response += f"- ❌ {module}: {error}\n"
-                response += "\n"
-
-            response += "**Important Notes:**\n"
-            response += "- Class instances created before reload keep old code\n"
-            response += "- New requests will use the reloaded code\n"
-            response += "- Some changes may require full restart (e.g., new tools)\n"
-
-            return response
-
-        except Exception as e:
-            logger.error(f"Code reload failed: {e}", exc_info=True)
-            return f"❌ Code reload failed: {str(e)}"
+        async with self._lock:  # Ensure thread safety for reload operations
+            try:
+                # Track what we're reloading
+                reload_targets = []
+
+                if auto_detect:
+                    # Detect changed modules (without updating hashes)
+                    changed = self._detect_changed_modules()
+                    if changed:
+                        reload_targets.extend(changed)
+                        await ctx.debug(f"Auto-detected changes in: {changed}")
+
+                if modules:
+                    # Add explicitly requested modules
+                    reload_targets.extend(modules)
+
+                if not reload_targets:
+                    return "📊 No modules to reload. All code is up to date!"
+
+                # Perform the reload
+                reloaded = []
+                failed = []
+
+                for module_name in reload_targets:
+                    try:
+                        # SECURITY FIX: Validate module is in whitelist
+                        if not ModuleWhitelist.is_allowed_module(module_name):
+                            logger.warning(f"Module not in whitelist, skipping: {module_name}")
+                            failed.append((module_name, "Module not in whitelist"))
+                            continue
+
+                        if module_name in sys.modules:
+                            # Store old module reference for rollback
+                            old_module = sys.modules[module_name]
+
+                            # Reload the module
+                            logger.info(f"Reloading module: {module_name}")
+                            reloaded_module = importlib.reload(sys.modules[module_name])
+
+                            # Update any global references if needed
+                            self._update_global_references(module_name, reloaded_module)
+
+                            reloaded.append(module_name)
+                            await ctx.debug(f"✅ Reloaded: {module_name}")
+                        else:
+                            # Module not loaded yet, import it
+                            importlib.import_module(module_name)
+                            reloaded.append(module_name)
+                            await ctx.debug(f"✅ Imported: {module_name}")
+
+                    except Exception as e:
+                        logger.error(f"Failed to reload {module_name}: {e}", exc_info=True)
+                        failed.append((module_name, str(e)))
+                        await ctx.debug(f"❌ Failed: {module_name} - {e}")
+
+                # Update hashes ONLY for successfully reloaded modules
+                if reloaded:
+                    self._update_module_hashes(reloaded)
+                    await ctx.debug(f"Updated hashes for {len(reloaded)} successfully reloaded modules")
+
+                # Record reload history
+                self.reload_history.append({
+                    "timestamp": os.environ.get('MCP_REQUEST_ID', 'unknown'),
+                    "reloaded": reloaded,
+                    "failed": failed
+                })
+
+                # Build response
+                response = "🔄 **Code Reload Results**\n\n"
+
+                if reloaded:
+                    response += f"**Successfully Reloaded ({len(reloaded)}):**\n"
+                    for module in reloaded:
+                        response += f"- ✅ {module}\n"
+                    response += "\n"
+
+                if failed:
+                    response += f"**Failed to Reload ({len(failed)}):**\n"
+                    for module, error in failed:
+                        response += f"- ❌ {module}: {error}\n"
+                    response += "\n"
+
+                response += "**Important Notes:**\n"
+                response += "- Class instances created before reload keep old code\n"
+                response += "- New requests will use the reloaded code\n"
+                response += "- Some changes may require full restart (e.g., new tools)\n"
+
+                return response
+
+            except Exception as e:
+                logger.error(f"Code reload failed: {e}", exc_info=True)
+                return f"❌ Code reload failed: {str(e)}"
 
     def _update_global_references(self, module_name: str, new_module):
         """Update global references after module reload."""
@@ -171,8 +251,8 @@ class CodeReloader:
         """Get the current reload status and history."""
 
         try:
-            # Check for changed files
-            changed = self._get_changed_modules()
+            # Check for changed files (WITHOUT updating hashes)
+            changed = self._detect_changed_modules()
 
             response = "📊 **Code Reload Status**\n\n"
 
@@ -224,6 +304,24 @@ class CodeReloader:
             logger.error(f"Failed to clear cache: {e}", exc_info=True)
             return f"❌ Failed to clear cache: {str(e)}"
 
+    async def force_update_hashes(self, ctx: Context) -> str:
+        """Force update all module hashes to current state.
+        
+        This is useful when you want to mark all current code as 'baseline'
+        without actually reloading anything.
+        """
+        try:
+            await ctx.debug("Force updating all module hashes...")
+            
+            # Update all module hashes
+            self._update_module_hashes(modules=None)
+            
+            return f"✅ Force updated hashes for all {len(self.module_hashes)} tracked modules"
+        
+        except Exception as e:
+            logger.error(f"Failed to force update hashes: {e}", exc_info=True)
+            return f"❌ Failed to force update hashes: {str(e)}"
+
 
 def register_code_reload_tool(mcp, get_embedding_manager):
     """Register the code reloading tool with the MCP server."""
@@ -257,6 +355,8 @@ def register_code_reload_tool(mcp, get_embedding_manager):
 
         Shows which files have been modified since last reload and
         the history of recent reload operations.
+        
+        Note: This only checks for changes, it does not update the stored hashes.
         """
         return await reloader.get_reload_status(ctx)
 
@@ -267,5 +367,14 @@ def register_code_reload_tool(mcp, get_embedding_manager):
         Useful when reload isn't working due to cached bytecode.
         """
         return await reloader.clear_python_cache(ctx)
+    
+    @mcp.tool()
+    async def force_update_module_hashes(ctx: Context) -> str:
+        """Force update all module hashes to mark current code as baseline.
+        
+        Use this when you want to ignore current changes and treat
+        the current state as the new baseline without reloading.
+        """
+        return await reloader.force_update_hashes(ctx)
 
-    logger.info("Code reload tools registered successfully")
+    logger.info("Code reload tools registered successfully")

package/mcp-server/src/parallel_search.py

@@ -8,6 +8,7 @@ import time
 from typing import List, Dict, Any, Optional, Tuple
 from datetime import datetime
 import logging
+from .safe_getters import safe_get_list, safe_get_str
 
 logger = logging.getLogger(__name__)
 
@@ -176,9 +177,9 @@ async def search_single_collection(
                         'collection_name': collection_name,
                         'raw_payload': point.payload,  # Renamed from 'payload' for consistency
                         'code_patterns': point.payload.get('code_patterns'),
-                        'files_analyzed': point.payload.get('files_analyzed'),
-                        'tools_used': list(point.payload.get('tools_used', [])) if isinstance(point.payload.get('tools_used'), set) else point.payload.get('tools_used'),
-                        'concepts': point.payload.get('concepts')
+                        'files_analyzed': safe_get_list(point.payload, 'files_analyzed'),
+                        'tools_used': safe_get_list(point.payload, 'tools_used'),
+                        'concepts': safe_get_list(point.payload, 'concepts')
                     }
                     results.append(search_result)
             else:
@@ -219,9 +220,9 @@ async def search_single_collection(
                         'collection_name': collection_name,
                         'raw_payload': point.payload,
                         'code_patterns': point.payload.get('code_patterns'),
-                        'files_analyzed': point.payload.get('files_analyzed'),
-                        'tools_used': list(point.payload.get('tools_used', [])) if isinstance(point.payload.get('tools_used'), set) else point.payload.get('tools_used'),
-                        'concepts': point.payload.get('concepts')
+                        'files_analyzed': safe_get_list(point.payload, 'files_analyzed'),
+                        'tools_used': safe_get_list(point.payload, 'tools_used'),
+                        'concepts': safe_get_list(point.payload, 'concepts')
                     }
                     results.append(search_result)
     

package/mcp-server/src/rich_formatting.py

@@ -5,6 +5,7 @@ import time
 from datetime import datetime, timezone
 from typing import List, Dict, Any, Optional
 import logging
+from .safe_getters import safe_get_list, safe_get_str
 
 logger = logging.getLogger(__name__)
 
@@ -114,16 +115,19 @@ def format_search_results_rich(
         concept_frequency = {}
 
         for result in results:
-            # Count file modifications
-            for file in result.get('files_analyzed', []):
+            # Count file modifications - using safe_get_list for consistency
+            files = safe_get_list(result, 'files_analyzed')
+            for file in files:
                 file_frequency[file] = file_frequency.get(file, 0) + 1
 
-            # Count tool usage
-            for tool in result.get('tools_used', []):
+            # Count tool usage - using safe_get_list for consistency
+            tools = safe_get_list(result, 'tools_used')
+            for tool in tools:
                 tool_frequency[tool] = tool_frequency.get(tool, 0) + 1
 
-            # Count concepts
-            for concept in result.get('concepts', []):
+            # Count concepts - using safe_get_list for consistency
+            concepts = safe_get_list(result, 'concepts')
+            for concept in concepts:
                 concept_frequency[concept] = concept_frequency.get(concept, 0) + 1
 
         # Show most frequently modified files