roadmap-cli 0.1.1__py3-none-any.whl

roadmap/adapters/persistence/file_locking.py

@@ -0,0 +1,348 @@
+"""File locking mechanism for roadmap YAML files."""
+
+import errno
+import fcntl
+import json
+import os
+import tempfile
+import time
+from contextlib import AbstractContextManager
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from threading import Lock
+from typing import Any
+
+from structlog import get_logger
+
+from roadmap.common.utils.file_utils import ensure_directory_exists
+
+logger = get_logger()
+
+
+class FileLockError(Exception):
+    """Exception raised for file locking errors."""
+
+    pass
+
+
+class FileLockTimeout(FileLockError):
+    """Exception raised when file lock times out."""
+
+    pass
+
+
+class FileLock:
+    """File lock implementation using fcntl (Unix/Linux/macOS) or msvcrt (Windows)."""
+
+    def __init__(
+        self, file_path: Path, timeout: float = 30.0, check_interval: float = 0.1
+    ):
+        """Initialize FileLock.
+
+        Args:
+            file_path: Path to file to lock.
+            timeout: Lock acquisition timeout in seconds.
+            check_interval: Interval in seconds between lock checks.
+        """
+        self.file_path = file_path
+        self.lock_path = file_path.with_suffix(file_path.suffix + ".lock")
+        self.timeout = timeout
+        self.check_interval = check_interval
+        self.lock_file = None
+        self.acquired = False
+
+        # Lock metadata
+        self.lock_info = {
+            "pid": os.getpid(),
+            "timestamp": datetime.now(UTC).isoformat(),
+            "file": str(file_path),
+            "host": os.uname().nodename if hasattr(os, "uname") else "unknown",
+        }
+
+    def __enter__(self):
+        """Context manager entry."""
+        self.acquire()
+        return self
+
+    def __exit__(self, _exc_type, _exc_val, _exc_tb):
+        """Context manager exit."""
+        self.release()
+
+    def acquire(self) -> bool:
+        """Acquire the file lock."""
+        if self.acquired:
+            return True
+
+        start_time = time.time()
+
+        while time.time() - start_time < self.timeout:
+            try:
+                # Create lock file
+                self.lock_file = open(self.lock_path, "w")
+
+                # Try to acquire exclusive lock
+                fcntl.flock(self.lock_file.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+
+                # Write lock metadata
+                json.dump(self.lock_info, self.lock_file, indent=2)
+                self.lock_file.flush()
+
+                self.acquired = True
+                return True
+
+            except OSError as e:
+                if e.errno in (errno.EAGAIN, errno.EACCES):
+                    # Lock is already held, wait and retry
+                    if self.lock_file:
+                        self.lock_file.close()
+                        self.lock_file = None
+                    time.sleep(self.check_interval)
+                    continue
+                else:
+                    # Other error
+                    if self.lock_file:
+                        self.lock_file.close()
+                        self.lock_file = None
+                    raise FileLockError(f"Failed to acquire lock: {e}") from e
+
+        # Timeout reached
+        if self.lock_file:
+            self.lock_file.close()
+            self.lock_file = None
+        raise FileLockTimeout(f"Failed to acquire lock within {self.timeout} seconds")
+
+    def release(self) -> bool:
+        """Release the file lock."""
+        if not self.acquired:
+            return True
+
+        try:
+            if self.lock_file:
+                fcntl.flock(self.lock_file.fileno(), fcntl.LOCK_UN)
+                self.lock_file.close()
+                self.lock_file = None
+
+            # Remove lock file
+            if self.lock_path.exists():
+                self.lock_path.unlink()
+
+            self.acquired = False
+            return True
+
+        except Exception as e:
+            raise FileLockError(f"Failed to release lock: {e}") from e
+
+    def is_locked(self) -> bool:
+        """Check if the file is currently locked."""
+        if not self.lock_path.exists():
+            return False
+
+        try:
+            # Try to open and lock the file
+            with open(self.lock_path) as f:
+                fcntl.flock(f.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+                fcntl.flock(f.fileno(), fcntl.LOCK_UN)
+            return False  # No lock held
+        except OSError as e:
+            logger.debug("lock_check_failed", error=str(e))
+            return True  # Lock is held
+
+    def get_lock_info(self) -> dict[str, Any] | None:
+        """Get information about the current lock holder."""
+        if not self.lock_path.exists():
+            return None
+
+        try:
+            with open(self.lock_path) as f:
+                return json.load(f)
+        except (OSError, json.JSONDecodeError):
+            return None
+
+    def force_unlock(self) -> bool:
+        """Force unlock by removing the lock file (use with caution)."""
+        try:
+            if self.lock_path.exists():
+                self.lock_path.unlink()
+            return True
+        except Exception as e:
+            logger.error("force_unlock_failed", error=str(e), severity="system_error")
+            return False
+
+
+class LockManager:
+    """Manager for handling multiple file locks and lock policies."""
+
+    def __init__(self, default_timeout: float = 30.0):
+        """Initialize LockManager.
+
+        Args:
+            default_timeout: Default timeout for lock acquisition in seconds.
+        """
+        self.default_timeout = default_timeout
+        self.active_locks: dict[str, FileLock] = {}
+        self._global_lock = Lock()  # Thread safety
+
+    def lock_file(
+        self, file_path: Path, timeout: float | None = None
+    ) -> AbstractContextManager[FileLock]:
+        """Get a context manager for file locking."""
+        timeout = timeout or self.default_timeout
+        file_str = str(file_path)
+
+        with self._global_lock:
+            if file_str in self.active_locks:
+                # Reuse existing lock
+                return self.active_locks[file_str]
+
+            # Create new lock
+            lock = FileLock(file_path, timeout)
+            self.active_locks[file_str] = lock
+            return lock
+
+    def is_file_locked(self, file_path: Path) -> bool:
+        """Check if a file is currently locked."""
+        lock = FileLock(file_path)
+        return lock.is_locked()
+
+    def get_lock_info(self, file_path: Path) -> dict[str, Any] | None:
+        """Get lock information for a file."""
+        lock = FileLock(file_path)
+        return lock.get_lock_info()
+
+    def force_unlock_file(self, file_path: Path) -> bool:
+        """Force unlock a file (use with extreme caution)."""
+        lock = FileLock(file_path)
+        return lock.force_unlock()
+
+    def cleanup_stale_locks(self, max_age_hours: float = 24.0) -> int:
+        """Clean up stale lock files older than max_age_hours."""
+        cleaned = 0
+        max_age = timedelta(hours=max_age_hours)
+        current_time = datetime.now(UTC)
+
+        # Find all .lock files
+        for lock_file in Path(".").rglob("*.lock"):
+            try:
+                # Check file age
+                file_time = datetime.fromtimestamp(lock_file.stat().st_mtime)
+                if current_time - file_time > max_age:
+                    # Check if the lock is actually stale
+                    lock = FileLock(lock_file.with_suffix(""))
+                    if not lock.is_locked():
+                        lock_file.unlink()
+                        cleaned += 1
+            except Exception as e:
+                logger.debug(
+                    "stale_lock_cleanup_failed", lock_file=str(lock_file), error=str(e)
+                )
+                continue
+
+        return cleaned
+
+    def get_all_locks(
+        self, search_dir: Path | None = None
+    ) -> dict[str, dict[str, Any]]:
+        """Get information about all current locks."""
+        locks = {}
+        search_path = search_dir or Path(".")
+
+        for lock_file in search_path.rglob("*.lock"):
+            try:
+                original_file = lock_file.with_suffix("")
+                lock = FileLock(original_file)
+                lock_info = lock.get_lock_info()
+                if lock_info:
+                    locks[str(original_file)] = lock_info
+            except Exception as e:
+                logger.debug(
+                    "lock_info_retrieval_failed", lock_file=str(lock_file), error=str(e)
+                )
+                continue
+
+        return locks
+
+
+class LockedFileOperations:
+    """File operations with automatic locking."""
+
+    def __init__(self, lock_manager: LockManager | None = None):
+        """Initialize LockedFileOperations.
+
+        Args:
+            lock_manager: LockManager instance. Defaults to new LockManager.
+        """
+        self.lock_manager = lock_manager or LockManager()
+
+    def read_file_locked(self, file_path: Path, timeout: float | None = None) -> str:
+        """Read a file with locking."""
+        with self.lock_manager.lock_file(file_path, timeout):
+            return file_path.read_text(encoding="utf-8")
+
+    def write_file_locked(
+        self,
+        file_path: Path,
+        content: str,
+        timeout: float | None = None,
+        backup: bool = True,
+    ) -> bool:
+        """Write a file with locking and optional backup."""
+        with self.lock_manager.lock_file(file_path, timeout):
+            try:
+                # Create backup if requested and file exists
+                if backup and file_path.exists():
+                    backup_path = file_path.with_suffix(f".backup.{int(time.time())}")
+                    backup_path.write_text(
+                        file_path.read_text(encoding="utf-8"), encoding="utf-8"
+                    )
+
+                # Ensure directory exists
+                ensure_directory_exists(file_path.parent)
+
+                # Write to temporary file first for atomic operation
+                with tempfile.NamedTemporaryFile(
+                    mode="w",
+                    encoding="utf-8",
+                    dir=file_path.parent,
+                    prefix=f".{file_path.name}.",
+                    suffix=".tmp",
+                    delete=False,
+                ) as tmp_file:
+                    tmp_file.write(content)
+                    tmp_path = Path(tmp_file.name)
+
+                # Atomic move
+                tmp_path.replace(file_path)
+                return True
+
+            except Exception as e:
+                # Clean up temp file if it exists
+                if "tmp_path" in locals() and tmp_path.exists():
+                    tmp_path.unlink()
+                raise FileLockError(f"Failed to write file: {e}") from e
+
+    def update_file_locked(
+        self, file_path: Path, updater_func, timeout: float | None = None
+    ) -> Any:
+        """Update a file using an updater function with locking."""
+        with self.lock_manager.lock_file(file_path, timeout):
+            # Read current content
+            if file_path.exists():
+                content = file_path.read_text(encoding="utf-8")
+            else:
+                content = ""
+
+            # Apply updater function
+            new_content = updater_func(content)
+
+            # Write back if changed
+            if new_content != content:
+                self.write_file_locked(
+                    file_path, new_content, timeout=None, backup=True
+                )
+
+            return new_content
+
+
+# Global instances
+lock_manager = LockManager()
+locked_file_ops = LockedFileOperations(lock_manager)

roadmap/adapters/persistence/file_parser.py

@@ -0,0 +1,92 @@
+"""YAML file parsing for .roadmap markdown files."""
+
+import hashlib
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from roadmap.common.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class FileParser:
+    """Handles parsing and hashing of markdown files with YAML frontmatter."""
+
+    @staticmethod
+    def calculate_file_hash(file_path: Path) -> str:
+        """Calculate SHA-256 hash of file content."""
+        try:
+            with open(file_path, "rb") as f:
+                return hashlib.sha256(f.read()).hexdigest()
+        except Exception as e:
+            logger.warning(
+                "failed_to_calculate_hash",
+                file_path=str(file_path),
+                error=str(e),
+                severity="operational",
+            )
+            return ""
+
+    @staticmethod
+    def parse_yaml_frontmatter(file_path: Path) -> dict[str, Any]:
+        """Parse YAML frontmatter from markdown file.
+
+        Expects format:
+            ---
+            key: value
+            ---
+            # Markdown content
+        """
+        try:
+            with open(file_path, encoding="utf-8") as f:
+                content = f.read()
+
+            # Check for frontmatter delimiters
+            if not content.startswith("---\n"):
+                return {}
+
+            # Find the end of frontmatter
+            try:
+                end_marker = content.index("\n---\n", 4)
+                frontmatter = content[4:end_marker]
+                loaded = yaml.safe_load(frontmatter)
+                return loaded if isinstance(loaded, dict) else {}
+            except ValueError:
+                # No end marker found, treat entire file as YAML
+                loaded = yaml.safe_load(content)
+                return loaded if isinstance(loaded, dict) else {}
+
+        except Exception as e:
+            logger.error(
+                "failed_to_parse_yaml",
+                file_path=str(file_path),
+                error=str(e),
+                severity="data_error",
+            )
+            return {}
+
+    @staticmethod
+    def extract_file_metadata(file_path: Path) -> dict[str, Any]:
+        """Extract file metadata without parsing YAML.
+
+        Returns:
+            Dictionary with 'hash', 'size', and 'modified_time' keys
+        """
+        try:
+            file_stat = file_path.stat()
+            return {
+                "hash": FileParser.calculate_file_hash(file_path),
+                "size": file_stat.st_size,
+                "modified_time": datetime.fromtimestamp(file_stat.st_mtime),
+            }
+        except Exception as e:
+            logger.error(
+                "failed_to_extract_metadata",
+                file_path=str(file_path),
+                error=str(e),
+                severity="data_error",
+            )
+            return {}

roadmap/adapters/persistence/file_synchronizer.py

@@ -0,0 +1,107 @@
+"""File synchronization manager for syncing .roadmap files to database.
+
+This module coordinates synchronization of markdown files in the .roadmap directory
+with the SQLite database. It delegates to focused managers for parsing, sync state,
+and entity-specific coordination.
+"""
+
+from pathlib import Path
+from typing import Any
+
+from roadmap.adapters.persistence.file_parser import FileParser
+from roadmap.adapters.persistence.sync_orchestrator import SyncOrchestrator
+from roadmap.common.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class FileSynchronizer:
+    """Manages synchronization of .roadmap files to the database.
+
+    Delegates to specialized managers for parsing, sync state tracking,
+    and entity-specific synchronization coordination.
+    """
+
+    def __init__(self, get_connection, transaction_context):
+        """Initialize the file synchronizer.
+
+        Args:
+            get_connection: Callable that returns a database connection
+            transaction_context: Context manager for transactions
+        """
+        self._orchestrator = SyncOrchestrator(get_connection, transaction_context)
+        self._parser = FileParser()
+        self._get_connection = get_connection
+        self._transaction = transaction_context
+
+    def get_file_sync_status(self, file_path: str) -> dict[str, Any] | None:
+        """Get sync status for a file."""
+        conn = self._get_connection()
+        row = conn.execute(
+            """
+            SELECT file_path, content_hash, file_size, last_modified
+            FROM file_sync_state WHERE file_path = ?
+        """,
+            (file_path,),
+        ).fetchone()
+        return dict(row) if row else None
+
+    def update_file_sync_status(
+        self, file_path: str, content_hash: str, file_size: int, last_modified: Any
+    ) -> None:
+        """Update sync status for a file."""
+        with self._transaction() as conn:
+            conn.execute(
+                """
+                INSERT OR REPLACE INTO file_sync_state
+                (file_path, content_hash, file_size, last_modified)
+                VALUES (?, ?, ?, ?)
+            """,
+                (file_path, content_hash, file_size, last_modified),
+            )
+
+    def has_file_changed(self, file_path: Path) -> bool:
+        """Check if file has changed since last sync."""
+        try:
+            if not file_path.exists():
+                return True
+
+            current_hash = self._parser.calculate_file_hash(file_path)
+            sync_status = self.get_file_sync_status(str(file_path))
+
+            if not sync_status:
+                return True
+
+            return current_hash != sync_status["content_hash"]
+
+        except Exception as e:
+            logger.error(
+                "failed_to_check_file_changes",
+                file_path=str(file_path),
+                error=str(e),
+                severity="operational",
+            )
+            return True
+
+    def sync_directory_incremental(self, roadmap_dir: Path) -> dict[str, Any]:
+        """Incrementally sync .roadmap directory to database.
+
+        Only syncs files that have changed since last sync.
+        """
+        return self._orchestrator.sync_directory_incremental(roadmap_dir)
+
+    def full_rebuild_from_git(self, roadmap_dir: Path) -> dict[str, Any]:
+        """Full rebuild of database from git files.
+
+        Clears all data and rebuilds from scratch.
+        """
+        return self._orchestrator.full_rebuild_from_git(roadmap_dir)
+
+    def should_do_full_rebuild(self, roadmap_dir: Path, threshold: int = 50) -> bool:
+        """Determine if full rebuild is needed vs incremental sync.
+
+        Args:
+            roadmap_dir: Path to .roadmap directory
+            threshold: Percentage of files changed before triggering rebuild (default 50%)
+        """
+        return self._orchestrator.should_do_full_rebuild(roadmap_dir, threshold)

roadmap/adapters/persistence/focused_managers.py

@@ -0,0 +1,140 @@
+"""Focused state manager adapters for StateManager.
+
+These adapters wrap StateManager to provide focused, single-responsibility
+interfaces. This allows code to depend on focused protocols instead of the
+monolithic StateManager.
+"""
+
+from typing import Any
+
+from roadmap.core.interfaces import (
+    IssueStateManager,
+    MilestoneStateManager,
+    ProjectStateManager,
+    QueryStateManager,
+    SyncStateManager,
+)
+
+
+class FocusedProjectStateManager(ProjectStateManager):
+    """Project-focused view of StateManager."""
+
+    def __init__(self, state_manager):
+        """Initialize with StateManager instance."""
+        self._state_manager = state_manager
+
+    def create_project(self, project_data: dict[str, Any]) -> str:
+        """Create a new project."""
+        return self._state_manager.create_project(project_data)
+
+    def get_project(self, project_id: str) -> dict[str, Any] | None:
+        """Get project by ID."""
+        return self._state_manager.get_project(project_id)
+
+    def list_projects(self) -> list[dict[str, Any]]:
+        """List all projects."""
+        return self._state_manager.list_projects()
+
+    def update_project(self, project_id: str, updates: dict[str, Any]) -> bool:
+        """Update project."""
+        return self._state_manager.update_project(project_id, updates)
+
+    def delete_project(self, project_id: str) -> bool:
+        """Delete project."""
+        return self._state_manager.delete_project(project_id)
+
+    def mark_project_archived(self, project_id: str, archived: bool = True) -> bool:
+        """Mark a project as archived or unarchived."""
+        return self._state_manager.mark_project_archived(project_id, archived)
+
+
+class FocusedMilestoneStateManager(MilestoneStateManager):
+    """Milestone-focused view of StateManager."""
+
+    def __init__(self, state_manager):
+        """Initialize with StateManager instance."""
+        self._state_manager = state_manager
+
+    def create_milestone(self, milestone_data: dict[str, Any]) -> str:
+        """Create a new milestone."""
+        return self._state_manager.create_milestone(milestone_data)
+
+    def get_milestone(self, milestone_id: str) -> dict[str, Any] | None:
+        """Get milestone by ID."""
+        return self._state_manager.get_milestone(milestone_id)
+
+    def update_milestone(self, milestone_id: str, updates: dict[str, Any]) -> bool:
+        """Update milestone."""
+        return self._state_manager.update_milestone(milestone_id, updates)
+
+    def mark_milestone_archived(self, milestone_id: str, archived: bool = True) -> bool:
+        """Mark a milestone as archived or unarchived."""
+        return self._state_manager.mark_milestone_archived(milestone_id, archived)
+
+
+class FocusedIssueStateManager(IssueStateManager):
+    """Issue-focused view of StateManager."""
+
+    def __init__(self, state_manager):
+        """Initialize with StateManager instance."""
+        self._state_manager = state_manager
+
+    def create_issue(self, issue_data: dict[str, Any]) -> str:
+        """Create a new issue."""
+        return self._state_manager.create_issue(issue_data)
+
+    def get_issue(self, issue_id: str) -> dict[str, Any] | None:
+        """Get issue by ID."""
+        return self._state_manager.get_issue(issue_id)
+
+    def update_issue(self, issue_id: str, updates: dict[str, Any]) -> bool:
+        """Update issue."""
+        return self._state_manager.update_issue(issue_id, updates)
+
+    def delete_issue(self, issue_id: str) -> bool:
+        """Delete issue."""
+        return self._state_manager.delete_issue(issue_id)
+
+    def mark_issue_archived(self, issue_id: str, archived: bool = True) -> bool:
+        """Mark an issue as archived or unarchived."""
+        return self._state_manager.mark_issue_archived(issue_id, archived)
+
+
+class FocusedSyncStateManager(SyncStateManager):
+    """Sync state-focused view of StateManager."""
+
+    def __init__(self, state_manager):
+        """Initialize with StateManager instance."""
+        self._state_manager = state_manager
+
+    def get_sync_state(self, key: str) -> str | None:
+        """Get sync state value."""
+        return self._state_manager.get_sync_state(key)
+
+    def set_sync_state(self, key: str, value: str):
+        """Set sync state value."""
+        self._state_manager.set_sync_state(key, value)
+
+
+class FocusedQueryStateManager(QueryStateManager):
+    """Query-focused view of StateManager."""
+
+    def __init__(self, state_manager):
+        """Initialize with StateManager instance."""
+        self._state_manager = state_manager
+
+    def get_all_issues(self) -> list[dict[str, Any]]:
+        """Get all issues from database."""
+        return self._state_manager.get_all_issues()
+
+    def get_all_milestones(self) -> list[dict[str, Any]]:
+        """Get all milestones from database."""
+        return self._state_manager.get_all_milestones()
+
+    def get_milestone_progress(self, milestone_name: str) -> dict[str, int]:
+        """Get progress stats for a milestone."""
+        return self._state_manager.get_milestone_progress(milestone_name)
+
+    def get_issues_by_status(self) -> dict[str, int]:
+        """Get issue counts by status."""
+        return self._state_manager.get_issues_by_status()