roadmap-cli 0.1.1__py3-none-any.whl

roadmap/adapters/sync/backends/services/github_milestone_fetch_service.py

@@ -0,0 +1,204 @@
+"""Service for fetching milestones from GitHub API."""
+
+from datetime import datetime
+
+from structlog import get_logger
+
+from roadmap.adapters.sync.backends.github_client import GitHubClientWrapper
+from roadmap.common.logging import log_error_with_context
+from roadmap.core.models.sync_models import SyncMilestone
+
+logger = get_logger()
+
+
+class GitHubMilestoneFetchService:
+    """Handles fetching milestones from GitHub API."""
+
+    def __init__(
+        self,
+        github_client: GitHubClientWrapper,
+        config: dict,
+    ):
+        """Initialize milestone fetch service.
+
+        Args:
+            github_client: GitHubClientWrapper for API access
+            config: Configuration dict with 'owner', 'repo'
+        """
+        self.github_client = github_client
+        self.config = config
+
+    def get_milestones(self, state: str = "all") -> dict[str, SyncMilestone]:
+        """Fetch all milestones from GitHub.
+
+        Args:
+            state: Milestone state filter ('open', 'closed', 'all')
+
+        Returns:
+            Dict mapping milestone numbers (as strings) to SyncMilestone objects,
+            or empty dict if fetch fails.
+        """
+        if not self.github_client:
+            logger.warning("github_milestone_fetch_no_client")
+            return {}
+
+        owner = self.config.get("owner")
+        repo = self.config.get("repo")
+
+        if not owner or not repo:
+            logger.warning(
+                "github_milestone_fetch_missing_config", owner=owner, repo=repo
+            )
+            return {}
+
+        try:
+            logger.debug(
+                "github_milestone_fetch_start",
+                owner=owner,
+                repo=repo,
+                state=state,
+            )
+
+            # Get milestones using GitHub API
+            # Import handler and create with proper session
+            import requests
+
+            from roadmap.adapters.github.handlers.milestones import MilestoneHandler
+
+            # Create a requests session with authentication
+            session = requests.Session()
+            token = self.config.get("token")
+            if token:
+                session.headers.update(
+                    {
+                        "Authorization": f"token {token}",
+                        "Accept": "application/vnd.github.v3+json",
+                        "User-Agent": "roadmap-cli/1.0",
+                    }
+                )
+
+            milestone_handler = MilestoneHandler(
+                session=session,
+                owner=owner,
+                repo=repo,
+            )
+
+            milestones_data = milestone_handler.get_milestones(state=state)
+
+            logger.info(
+                "github_milestones_fetched",
+                owner=owner,
+                repo=repo,
+                count=len(milestones_data),
+            )
+
+            # Convert each GitHub milestone to SyncMilestone
+            result = {}
+            failed_conversions = 0
+            for milestone_dict in milestones_data:
+                try:
+                    sync_milestone = self._dict_to_sync_milestone(milestone_dict)
+                    milestone_number = str(milestone_dict.get("number", ""))
+                    result[milestone_number] = sync_milestone
+                except Exception as e:
+                    failed_conversions += 1
+                    milestone_number = (
+                        milestone_dict.get("number")
+                        if isinstance(milestone_dict, dict)
+                        else "unknown"
+                    )
+                    log_error_with_context(
+                        e,
+                        operation="convert_github_milestone_to_sync",
+                        entity_type="Milestone",
+                        entity_id=str(milestone_number),
+                        additional_context={
+                            "owner": owner,
+                            "repo": repo,
+                            "total_milestones": len(milestones_data),
+                        },
+                        include_traceback=False,
+                    )
+
+            if failed_conversions > 0:
+                logger.warning(
+                    "github_milestone_conversions_failed",
+                    owner=owner,
+                    repo=repo,
+                    total=len(milestones_data),
+                    failed=failed_conversions,
+                    successful=len(result),
+                )
+
+            return result
+
+        except Exception as e:
+            log_error_with_context(
+                e,
+                operation="fetch_github_milestones",
+                entity_type="Milestone",
+                additional_context={"owner": owner, "repo": repo, "state": state},
+                include_traceback=True,
+            )
+            return {}
+
+    def _dict_to_sync_milestone(self, milestone_dict: dict) -> SyncMilestone:
+        """Convert GitHub milestone dict to SyncMilestone.
+
+        Args:
+            milestone_dict: GitHub API milestone response
+
+        Returns:
+            SyncMilestone instance
+
+        Raises:
+            ValueError: If required fields are missing
+        """
+        milestone_number = milestone_dict.get("number")
+        if not milestone_number:
+            raise ValueError("GitHub milestone missing 'number' field")
+
+        title = milestone_dict.get("title")
+        if not title:
+            raise ValueError(f"GitHub milestone {milestone_number} missing 'title'")
+
+        # Parse state (GitHub uses "open", "closed")
+        state = milestone_dict.get("state", "open")
+
+        # Parse due date
+        due_date = None
+        due_on_str = milestone_dict.get("due_on")
+        if due_on_str:
+            try:
+                # GitHub returns ISO 8601 format with Z suffix
+                due_date = datetime.fromisoformat(due_on_str.replace("Z", "+00:00"))
+            except (ValueError, AttributeError) as e:
+                logger.debug(
+                    "github_milestone_due_date_parse_failed",
+                    milestone_number=milestone_number,
+                    due_on_str=due_on_str,
+                    error=str(e),
+                )
+
+        # Create SyncMilestone
+        sync_milestone = SyncMilestone(
+            id=f"gh_milestone_{milestone_number}",
+            name=title,
+            status=state,
+            headline=milestone_dict.get("description", "")[:100]
+            if milestone_dict.get("description")
+            else None,
+            due_date=due_date,
+            backend_name="github",
+            backend_id=milestone_number,
+            remote_ids={"github": milestone_number},
+            raw_response=milestone_dict,
+            metadata={
+                "open_issues": milestone_dict.get("open_issues", 0),
+                "closed_issues": milestone_dict.get("closed_issues", 0),
+                "created_at": milestone_dict.get("created_at"),
+                "updated_at": milestone_dict.get("updated_at"),
+            },
+        )
+
+        return sync_milestone

roadmap/adapters/sync/backends/vanilla_git_sync_backend.py

@@ -0,0 +1,198 @@
+"""Vanilla Git backend for self-hosting scenarios.
+
+For self-hosted deployments (no remote database), this backend is a no-op.
+The sync workflow is:
+1. User runs 'roadmap sync' to sync with GitHub API (via github_sync_backend)
+2. Sync creates/modifies .roadmap/issues/*.md files
+3. User manually runs 'git add' and 'git commit' to persist changes
+4. User manually runs 'git push' to push to git remote
+
+This backend does not perform git operations - that's the user's responsibility.
+
+Updated to use Result<T, SyncError> pattern for explicit error handling.
+"""
+
+from typing import Any
+
+from roadmap.common.result import Ok, Result
+from roadmap.core.domain.issue import Issue
+from roadmap.core.interfaces import (
+    SyncConflict,
+    SyncReport,
+)
+from roadmap.core.models.sync_models import (
+    SyncIssue,
+    SyncMilestone,
+    SyncProject,
+)
+from roadmap.core.services.sync.sync_errors import SyncError
+from roadmap.infrastructure.coordination.core import RoadmapCore
+
+
+class VanillaGitSyncBackend:
+    """No-op backend for self-hosting scenarios.
+
+    For self-hosted deployments without a remote database, this backend
+    delegates all operations to the user. The user is responsible for:
+    1. Git add/commit of modified .roadmap/issues/ files
+    2. Git push to sync with remote
+
+    This backend exists for interface compatibility but does not perform
+    any git operations.
+
+    Attributes:
+        core: RoadmapCore instance with access to local issues
+        config: Configuration dict (unused, kept for interface compatibility)
+    """
+
+    def __init__(self, core: RoadmapCore, config: dict[str, Any]):
+        """Initialize vanilla git sync backend.
+
+        Args:
+            core: RoadmapCore instance
+            config: Configuration dict (unused)
+        """
+        self.core = core
+        self.config = config
+
+    def get_backend_name(self) -> str:
+        """Get the canonical name of this backend.
+
+        Returns:
+            'git' - used as key in Issue.remote_ids dict
+        """
+        return "git"
+
+    def authenticate(self) -> Result[bool, SyncError]:
+        """No-op authentication for self-hosting.
+
+        For self-hosted scenarios without a remote database, authentication
+        always succeeds - the user is responsible for git operations.
+
+        Returns:
+            Ok(True) - always succeeds for self-hosted scenario
+        """
+        return Ok(True)
+
+    def get_issues(self) -> Result[dict[str, SyncIssue], SyncError]:
+        """No-op: Get issues from remote.
+
+        For self-hosting without a remote database, always returns empty dict.
+        The user is responsible for syncing via git operations.
+
+        Returns:
+            Ok with empty dict (no remote issues in self-hosted scenario)
+        """
+        return Ok({})
+
+    def push_issues(self, local_issues: list[Issue]) -> Result[SyncReport, SyncError]:
+        """No-op: Push multiple issues.
+
+        For self-hosting, the user is responsible for git operations.
+
+        Args:
+            local_issues: List of Issue objects (unused)
+
+        Returns:
+            Ok with empty SyncReport (no-op)
+        """
+        return Ok(SyncReport())
+
+    def push_issue(self, local_issue: Issue) -> Result[bool, SyncError]:
+        """No-op: Push a single issue.
+
+        For self-hosting, the user is responsible for git operations.
+        Delegates to push_issues for consistency.
+
+        Args:
+            local_issue: The Issue object (unused)
+
+        Returns:
+            Ok(True) - no-op succeeds
+        """
+        report_result = self.push_issues([local_issue])
+        if report_result.is_err():
+            return report_result  # type: ignore[return-value]
+
+        report = report_result.unwrap()
+        if len(report.pushed) > 0 or len(report.errors) == 0:
+            return Ok(True)
+        return Ok(True)  # No-op always succeeds
+
+    def pull_issues(self, issue_ids: list[str]) -> Result[SyncReport, SyncError]:
+        """No-op: Pull specified remote issues.
+
+        For self-hosting, the user is responsible for git operations.
+
+        Args:
+            issue_ids: List of issue IDs to pull (unused)
+
+        Returns:
+            Ok with empty SyncReport (no-op)
+        """
+        return Ok(SyncReport())
+
+    def pull_issue(self, issue_id: str) -> Result[bool, SyncError]:
+        """No-op: Pull a single issue.
+
+        For self-hosting, the user is responsible for git operations.
+        Delegates to pull_issues for consistency.
+
+        Args:
+            issue_id: The issue ID (unused)
+
+        Returns:
+            Ok(True) - no-op succeeds
+        """
+        report_result = self.pull_issues([issue_id])
+        if report_result.is_err():
+            return report_result  # type: ignore[return-value]
+
+        return Ok(True)  # No-op always succeeds
+
+    def get_conflict_resolution_options(self, conflict: SyncConflict) -> list[str]:
+        """Get available resolution strategies.
+
+        For self-hosting, no conflict resolution options (no remote to conflict with).
+
+        Args:
+            conflict: The SyncConflict (unused)
+
+        Returns:
+            Empty list (no remote database)
+        """
+        return []
+
+    def resolve_conflict(self, conflict: SyncConflict, resolution: str) -> bool:
+        """No-op: Resolve a conflict.
+
+        For self-hosting, no conflicts can occur (no remote database).
+
+        Args:
+            conflict: The SyncConflict (unused)
+            resolution: The resolution strategy (unused)
+
+        Returns:
+            True (no-op succeeds)
+        """
+        return True
+
+    def get_milestones(self) -> Result[dict[str, SyncMilestone], SyncError]:
+        """No-op: Get milestones from remote.
+
+        For self-hosting without a remote database, always returns empty dict.
+
+        Returns:
+            Ok with empty dict (no remote milestones in self-hosted scenario)
+        """
+        return Ok({})
+
+    def get_projects(self) -> Result[dict[str, SyncProject], SyncError]:
+        """No-op: Get projects from remote.
+
+        For self-hosting without a remote database, always returns empty dict.
+
+        Returns:
+            Ok with empty dict (no remote projects in self-hosted scenario)
+        """
+        return Ok({})

roadmap/adapters/sync/services/__init__.py

@@ -0,0 +1,11 @@
+"""Shared services for sync backends."""
+
+from .issue_persistence_service import IssuePersistenceService
+from .issue_state_service import IssueStateService
+from .sync_linking_service import SyncLinkingService
+
+__all__ = [
+    "IssueStateService",
+    "IssuePersistenceService",
+    "SyncLinkingService",
+]

roadmap/adapters/sync/services/baseline_state_handler.py

@@ -0,0 +1,83 @@
+"""Handles baseline state loading and updates for sync operations.
+
+Extracted from SyncMergeEngine to separate baseline management concerns.
+"""
+
+from dataclasses import fields
+from datetime import UTC, datetime
+from typing import Any
+
+from structlog import get_logger
+
+from roadmap.core.services.sync.sync_state import IssueBaseState, SyncState
+
+logger = get_logger(__name__)
+
+
+class BaselineStateHandler:
+    """Manages baseline state loading and updates."""
+
+    def __init__(self, core: Any, state_update_service: Any):
+        """Initialize with core services.
+
+        Args:
+            core: RoadmapCore instance with database access
+            state_update_service: SyncStateUpdateService for baseline updates
+        """
+        self.core = core
+        self.state_update_service = state_update_service
+
+    def load_baseline_state(self) -> SyncState | None:
+        """Load baseline state from database.
+
+        Returns:
+            SyncState object if baseline exists, None otherwise
+        """
+        try:
+            db_baseline = self.core.db.get_sync_baseline()
+            if db_baseline:
+                logger.debug(
+                    "baseline_loaded_from_database", issue_count=len(db_baseline)
+                )
+                base_issues = {}
+                issue_field_names = {field.name for field in fields(IssueBaseState)}
+                for issue_id, data in db_baseline.items():
+                    issue_kwargs = {
+                        "id": issue_id,
+                        "title": data.get("title", ""),
+                        "assignee": data.get("assignee"),
+                        "headline": data.get("headline", ""),
+                        "content": data.get("content", ""),
+                        "description": data.get("description", ""),
+                        "labels": data.get("labels", []),
+                    }
+                    status_value = data.get("status", "todo")
+                    if "status" in issue_field_names:
+                        issue_kwargs["status"] = status_value
+                    elif "state" in issue_field_names:
+                        issue_kwargs["state"] = status_value
+
+                    base_issues[issue_id] = IssueBaseState(**issue_kwargs)
+
+                sync_state = SyncState(
+                    last_sync_time=datetime.now(UTC),
+                    base_issues=base_issues,
+                )
+                return sync_state
+
+            logger.debug("baseline_not_found_in_database")
+            return None
+
+        except Exception as e:
+            logger.warning(
+                "baseline_load_failed", error=str(e), error_type=type(e).__name__
+            )
+            return None
+
+    def update_baseline_for_pulled(self, pulled_remote_ids: list[str]) -> None:
+        """Update baseline after pulling changes.
+
+        Args:
+            pulled_remote_ids: List of remote issue IDs that were pulled
+        """
+        self.state_update_service.update_baseline_for_pulled(pulled_remote_ids)

roadmap/adapters/sync/services/conflict_converter.py

@@ -0,0 +1,85 @@
+"""Converts issue changes to conflicts for resolution.
+
+Extracted from SyncMergeEngine to separate conflict conversion logic.
+"""
+
+from structlog import get_logger
+
+from roadmap.core.services.sync.sync_conflict_resolver import Conflict, ConflictField
+
+logger = get_logger(__name__)
+
+
+class ConflictConverter:
+    """Converts issue changes to conflict objects."""
+
+    def __init__(self, state_comparator):
+        """Initialize with state comparator.
+
+        Args:
+            state_comparator: SyncStateComparator for timestamp extraction
+        """
+        self.state_comparator = state_comparator
+
+    def convert_changes_to_conflicts(self, issue_changes: list) -> list[Conflict]:
+        """Convert issue changes with conflicts to conflict objects.
+
+        Args:
+            issue_changes: List of IssueChange objects with conflict info
+
+        Returns:
+            List of Conflict objects ready for resolution
+        """
+        conflicts: list[Conflict] = []
+
+        for change in issue_changes:
+            if (
+                not change.has_conflict
+                or not change.local_state
+                or not change.remote_state
+            ):
+                continue
+            try:
+                conflicting_fields = []
+                if change.local_changes:
+                    for field_name, _change_info in change.local_changes.items():
+                        if field_name in change.remote_changes:
+                            conflict_field = ConflictField(
+                                field_name=field_name,
+                                local_value=change.local_state.__dict__.get(
+                                    field_name, None
+                                ),
+                                remote_value=change.remote_state.get(field_name),
+                                local_updated=change.local_state.updated,
+                                remote_updated=self.state_comparator._extract_timestamp(
+                                    change.remote_state, "updated_at"
+                                ),
+                            )
+                            conflicting_fields.append(conflict_field)
+
+                if conflicting_fields:
+                    conflict = Conflict(
+                        issue_id=change.issue_id,
+                        local_issue=change.local_state,
+                        remote_issue=change.remote_state,
+                        fields=conflicting_fields,
+                        local_updated=change.local_state.updated,
+                        remote_updated=self.state_comparator._extract_timestamp(
+                            change.remote_state, "updated_at"
+                        ),
+                    )
+                    conflicts.append(conflict)
+
+            except Exception as e:
+                logger.warning(
+                    "conflict_conversion_failed",
+                    issue_id=change.issue_id,
+                    operation="analyze_conflicts",
+                    error_type=type(e).__name__,
+                    error=str(e),
+                    is_recoverable=True,
+                    suggested_action="skip_issue",
+                )
+                continue
+
+        return conflicts