nucleus-mcp 1.0.7 → 1.2.0

package/src/mcp_server_nucleus/runtime/locking.py

@@ -1,228 +0,0 @@
-"""
-BrainLock: The Atomic Safety Layer for Nucleus.
-This module defines the locking primitives used to ensure data integrity across
-multiple Nucleus processes (Daemon, CLI, MCP Server).
-
-Strategic Role:
-- Ensures "Atomic State" (The Brain doesn't hallucinate due to race conditions).
-- Implements "Leased Locks" (Prevents deadlocks if a process crashes).
-- Future-Proofing: Abstract base class allows swapping 'fcntl' for 'Redis' later.
-"""
-
-import abc
-import fcntl
-import time
-import os
-import contextlib
-import logging
-import subprocess
-import shutil
-from pathlib import Path
-from typing import Optional, Dict, Any, List
-
-logger = logging.getLogger(__name__)
-
-class BrainLock(abc.ABC):
-    """
-    Abstract Base Class for Nucleus Locking.
-    Enforces the 'LockProvider' interface for Cloud/Local agnosticism.
-    """
-    
-    @abc.abstractmethod
-    def acquire(self, timeout: float = 5.0, metadata: Optional[Dict[str, str]] = None) -> bool:
-        """Attempt to acquire the lock. Returns True if successful."""
-        pass
-
-    @abc.abstractmethod
-    def release(self) -> None:
-        """Release the lock."""
-        pass
-
-    @abc.abstractmethod
-    def get_metadata(self) -> Dict[str, Any]:
-        """Retrieve metadata associated with the lock."""
-        pass
-
-    def check_stale_locks(self, max_age_seconds: float = 3600):
-        """Optional: Check for and cleanup stale locks."""
-        pass
-
-
-    @contextlib.contextmanager
-    def section(self, timeout: float = 5.0, metadata: Optional[Dict[str, str]] = None):
-        """Context manager for critical sections."""
-        acquired = self.acquire(timeout, metadata=metadata)
-        if not acquired:
-            raise TimeoutError(f"Could not acquire lock on {self} after {timeout}s")
-        try:
-            yield
-        finally:
-            self.release()
-
-class FileBrainLock(BrainLock):
-    """
-    Local Implementation using UNIX `fcntl` + `xattr` for metadata.
-    Used for the 'Local First' Sovereign OS.
-    """
-    
-    def __init__(self, lock_path: str):
-        self.lock_path = Path(lock_path)
-        self.lock_file = None
-        # Ensure directory exists
-        self.lock_path.parent.mkdir(parents=True, exist_ok=True)
-        self.xattr_available = shutil.which("xattr") is not None
-
-    def _set_xattr(self, key: str, value: str):
-        """Writes extended attribute if xattr is available."""
-        if not self.xattr_available:
-            return
-        
-        try:
-            subprocess.run(
-                ["xattr", "-w", key, str(value), str(self.lock_path)],
-                check=True,
-                capture_output=True
-            )
-        except subprocess.CalledProcessError as e:
-            logger.warning(f"Failed to set xattr {key}: {e}")
-
-    def _get_xattr(self, key: str) -> Optional[str]:
-        """Reads extended attribute if xattr is available."""
-        if not self.xattr_available:
-            return None
-            
-        try:
-            result = subprocess.run(
-                ["xattr", "-p", key, str(self.lock_path)],
-                check=True,
-                capture_output=True,
-                text=True
-            )
-            return result.stdout.strip()
-        except subprocess.CalledProcessError:
-            return None
-
-    def _list_xattrs(self) -> List[str]:
-        """Lists all xattrs on the file."""
-        if not self.xattr_available:
-            return []
-            
-        try:
-            result = subprocess.run(
-                ["xattr", str(self.lock_path)],
-                check=True,
-                capture_output=True,
-                text=True
-            )
-            return result.stdout.strip().split("\n")
-        except subprocess.CalledProcessError:
-            return []
-
-    def acquire(self, timeout: float = 5.0, metadata: Optional[Dict[str, str]] = None) -> bool:
-        start_time = time.time()
-        
-        # Open the file if not already open
-        if self.lock_file is None:
-            self.lock_file = open(self.lock_path, 'w+')
-
-        while True:
-            try:
-                # specific locking operation: LOCK_EX (Exclusive) | LOCK_NB (Non-Blocking)
-                fcntl.flock(self.lock_file.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
-                
-                # Write PID for debugging (knowing who holds the lock)
-                self.lock_file.seek(0)
-                self.lock_file.truncate()
-                self.lock_file.write(str(os.getpid()))
-                self.lock_file.flush()
-                
-                # --- METADATA INJECTION (Phase 28) ---
-                if metadata:
-                    # Always include timestamp if not present
-                    if "timestamp" not in metadata:
-                        metadata["timestamp"] = time.strftime("%Y-%m-%dT%H:%M:%S%z")
-                        
-                    for k, v in metadata.items():
-                        # Namespace keys with 'nucleus.lock.' if not already
-                        key = k if k.startswith("nucleus.lock.") else f"nucleus.lock.{k}"
-                        self._set_xattr(key, v)
-                
-                return True
-            except (IOError, OSError):
-                # Lock is held by another process
-                if time.time() - start_time > timeout:
-                    logger.warning(f"Timeout waiting for lock: {self.lock_path}")
-                    return False
-                time.sleep(0.1)
-
-    def release(self) -> None:
-        if self.lock_file:
-            try:
-                # Unlock
-                fcntl.flock(self.lock_file.fileno(), fcntl.LOCK_UN)
-                self.lock_file.close()
-            except ValueError:
-                # File might be closed already
-                pass
-            finally:
-                self.lock_file = None
-
-    def get_metadata(self) -> Dict[str, Any]:
-        """Retrieves all nucleus.lock.* metadata from the lock file."""
-        if not self.lock_path.exists():
-            return {}
-            
-        data = {}
-        # Get PID from file content
-        try:
-            with open(self.lock_path, 'r') as f:
-                data["pid"] = f.read().strip()
-        except Exception:
-            data["pid"] = "unknown"
-
-        # Get xattrs
-        if self.xattr_available:
-            attrs = self._list_xattrs()
-            for attr in attrs:
-                if attr.startswith("nucleus.lock."):
-                    clean_key = attr.replace("nucleus.lock.", "")
-                    data[clean_key] = self._get_xattr(attr)
-        
-        return data
-
-    def check_stale_locks(self, max_age_seconds: float = 86400):
-        """
-        Check for stale lock files.
-        Note: fcntl locks are released by OS on process death.
-        This simply cleans up old files to keep directory tidy.
-        """
-        try:
-            if self.lock_path.exists():
-                stat = self.lock_path.stat()
-                age = time.time() - stat.st_mtime
-                if age > max_age_seconds:
-                    # We could try to flock(LOCK_EX | LOCK_NB) to see if anyone holds it
-                    # If we can lock it, it was truly stale (or just unused), so we can theoretically delete it.
-                    # But dealing with race on deletion is tricky. 
-                    # For V1, we simply Log it.
-                    logger.info(f"Old lock file detected: {self.lock_path} (Age: {age}s)")
-        except Exception:
-            pass
-
-
-    def __repr__(self):
-        return f"<FileBrainLock: {self.lock_path}>"
-
-# Factory Function for easy usage
-def get_lock(resource_name: str, base_dir: Optional[Path] = None) -> BrainLock:
-    """
-    Factory to get the appropriate lock for a resource.
-    Currently defaults to FileBrainLock.
-    """
-    if base_dir is None:
-        # Default to a .locks directory in the user's home or project root
-        # For now, let's use the .brain/.locks directory if possible, or /tmp/nucleus
-        base_dir = Path(os.environ.get("NUCLEUS_LOCK_DIR", "/tmp/nucleus_locks"))
-    
-    lock_path = base_dir / f"{resource_name}.lock"
-    return FileBrainLock(str(lock_path))

package/src/mcp_server_nucleus/runtime/loops/fixer.py

@@ -1,110 +0,0 @@
-
-import subprocess
-import time
-import json
-from pathlib import Path
-from typing import Callable, Tuple, Dict, Any
-
-class FixerLoop:
-    """
-    Manages the 'Verify -> Diagnose -> Fix' cycle for autonomous code repair.
-    Phase 4: Self-Healing v2
-    """
-    
-    def __init__(
-        self, 
-        target_file: str, 
-        verification_command: str, 
-        fixer_func: Callable[[str, str], str],
-        max_retries: int = 3
-    ):
-        self.target_file = Path(target_file)
-        self.verification_command = verification_command
-        self.fixer_func = fixer_func
-        self.max_retries = max_retries
-        self.logs = []
-
-    def _log(self, message: str):
-        timestamp = time.strftime("%H:%M:%S")
-        entry = f"[{timestamp}] {message}"
-        print(entry)
-        self.logs.append(entry)
-
-    def _run_verification(self) -> Tuple[bool, str]:
-        """Runs the verification command and returns (success, output)."""
-        self._log(f"Running verification: {self.verification_command}")
-        try:
-            result = subprocess.run(
-                self.verification_command,
-                shell=True,
-                capture_output=True,
-                text=True,
-                timeout=60
-            )
-            output = result.stdout + "\n" + result.stderr
-            return (result.returncode == 0, output)
-        except subprocess.TimeoutExpired:
-            return (False, "Verification timed out after 60s")
-        except Exception as e:
-            return (False, f"Verification failed to run: {e}")
-
-    def run(self) -> Dict[str, Any]:
-        """Execute the repair loop."""
-        
-        if not self.target_file.exists():
-            return {
-                "status": "error", 
-                "message": f"Target file {self.target_file} not found"
-            }
-
-        self._log(f"Starting Fixer Loop for {self.target_file.name}")
-        
-        # Initial Verification
-        success, output = self._run_verification()
-        if success:
-            self._log("Initial verification PASSED. No fix needed.")
-            return {
-                "status": "success",
-                "message": "File passed verification initially.",
-                "logs": self.logs
-            }
-
-        self._log("Initial verification FAILED. Starting repair cycles.")
-        
-        for attempt in range(1, self.max_retries + 1):
-            self._log(f"--- Attempt {attempt}/{self.max_retries} ---")
-            
-            # Diagnose & Fix
-            issues_context = f"Verification Command: {self.verification_command}\n\nOutput:\n{output[-2000:]}" # Truncate output
-            
-            self._log("Invoking Fixer Agent...")
-            try:
-                # Calls brain_fix_code(path, context)
-                fix_result_json = self.fixer_func(str(self.target_file), issues_context)
-                fix_result = json.loads(fix_result_json)
-                
-                if fix_result.get("status") == "error":
-                    self._log(f"Fixer Agent Error: {fix_result.get('message')}")
-                    # Continue anyway? No, probably fatal.
-                    # But maybe transient.
-            except Exception as e:
-                self._log(f"Exception calling fixer: {e}")
-            
-            # Verify Again
-            success, output = self._run_verification()
-            if success:
-                self._log("✅ Verification PASSED after fix.")
-                return {
-                    "status": "success",
-                    "message": f"Fixed in {attempt} attempts.",
-                    "logs": self.logs
-                }
-            else:
-                self._log("❌ Verification FAILED. Retrying...")
-
-        return {
-            "status": "failure",
-            "message": f"Failed to fix after {self.max_retries} attempts.",
-            "last_output": output,
-            "logs": self.logs
-        }

package/src/mcp_server_nucleus/runtime/memory.py

@@ -1,158 +0,0 @@
-
-import os
-import subprocess
-from pathlib import Path
-from typing import Dict
-import logging
-import time
-
-# Configure logger
-logger = logging.getLogger("nucleus.memory")
-
-def get_brain_path() -> Path:
-    """Get the brain path from environment variable."""
-    brain_path = os.environ.get("NUCLEAR_BRAIN_PATH")
-    if not brain_path:
-        # Fallback for dev environment
-        cwd = Path.cwd()
-        if (cwd / ".brain").exists():
-            return cwd / ".brain"
-        for parent in cwd.parents:
-            if (parent / ".brain").exists():
-                return parent / ".brain"
-        raise ValueError("NUCLEAR_BRAIN_PATH environment variable not set")
-    return Path(brain_path)
-
-def _search_memory(query: str) -> Dict:
-    """
-    Search the 'Long-term Memory' (artifacts/memory and ledger/decisions.md) using ripgrep.
-    """
-    try:
-        brain = get_brain_path()
-        memory_dir = brain / "memory"
-        ledger_dir = brain / "ledger"
-        
-        # Paths to search
-        search_paths = [str(memory_dir)]
-        if (ledger_dir / "decisions.md").exists():
-            search_paths.append(str(ledger_dir / "decisions.md"))
-            
-        # Run ripgrep
-        # -i: case insensitive
-        # -C 2: 2 lines of context
-        # --json: output as json
-        
-        # V1: Simple Text Search
-        cmd_text = ["rg", "-i", "-n", "--no-heading", query] + search_paths
-        try:
-            result_text = subprocess.run(cmd_text, capture_output=True, text=True)
-            snippets = []
-            if result_text.stdout:
-                snippets = result_text.stdout.strip().splitlines()
-        except FileNotFoundError:
-            # Fallback when ripgrep is not available
-            snippets = []
-            lowered = query.lower()
-            for path_str in search_paths:
-                path = Path(path_str)
-                if path.is_file():
-                    files = [path]
-                else:
-                    files = list(path.glob("*.md")) + list(path.glob("*.txt"))
-                for file_path in files:
-                    try:
-                        for line in file_path.read_text().splitlines():
-                            if lowered in line.lower():
-                                snippets.append(f"{file_path}:{line}")
-                    except Exception:
-                        continue
-
-        return {
-            "query": query,
-            "count": len(snippets),
-            "results": snippets[:20] # Limit to 20 results
-        }
-
-    except Exception as e:
-        logger.error(f"Memory search failed: {e}")
-        return {"error": str(e)}
-
-def _read_memory(category: str) -> Dict:
-    """
-    Read specific memory categories (context, patterns, learnings).
-    """
-    try:
-        brain = get_brain_path()
-        memory_dir = brain / "memory"
-        
-        allowed_files = {
-            "context": "context.md",
-            "patterns": "patterns.md",
-            "learnings": "learnings.md",
-            "decisions": "decisions.md" # Actually in ledger, but handled here
-        }
-        
-        if category not in allowed_files:
-            return {"error": f"Invalid category. Allowed: {list(allowed_files.keys())}"}
-            
-        filename = allowed_files[category]
-        file_path = memory_dir / filename
-        
-        if category == "decisions":
-            file_path = brain / "ledger" / "decisions.md"
-            
-        if not file_path.exists():
-             return {"error": f"Memory file {filename} not found."}
-             
-        content = file_path.read_text()
-        return {
-            "category": category,
-            "path": str(file_path),
-            "content": content
-        }
-
-    except Exception as e:
-        logger.error(f"Read memory failed: {e}")
-        return {"error": str(e)}
-
-def _write_memory(content: str, category: str = "learnings") -> str:
-    """
-    Write a memory engram to a specific category file in Markdown format.
-    """
-    try:
-        brain = get_brain_path()
-        memory_dir = brain / "memory"
-        memory_dir.mkdir(parents=True, exist_ok=True)
-        
-        allowed_files = {
-            "context": "context.md",
-            "patterns": "patterns.md",
-            "learnings": "learnings.md",
-            "decisions": "decisions.md" 
-        }
-        
-        # Default to learnings if unknown category, or map "memory" to learnings
-        if category == "memory":
-            category = "learnings"
-            
-        target_file = allowed_files.get(category, "learnings.md")
-        
-        # Special case for decisions (in ledger)
-        if category == "decisions":
-            file_path = brain / "ledger" / "decisions.md"
-            file_path.parent.mkdir(parents=True, exist_ok=True)
-        else:
-            file_path = memory_dir / target_file
-            
-        timestamp = time.strftime("%Y-%m-%d %H:%M:%S")
-        entry = f"\n\n## [{timestamp}] Engram\n{content}"
-        
-        mode = "a" if file_path.exists() else "w"
-        with open(file_path, mode) as f:
-            f.write(entry)
-            
-        return f"Memory written to {target_file}"
-
-    except Exception as e:
-        logger.error(f"Write memory failed: {e}")
-        return f"Error writing memory: {str(e)}"