roadmap-cli 0.1.1__py3-none-any.whl

roadmap/adapters/sync/__init__.py

@@ -0,0 +1,21 @@
+"""Sync infrastructure for integrating local roadmap with remote repositories.
+
+Provides pluggable backend architecture supporting multiple sync targets.
+"""
+
+from .backend_factory import (
+    detect_backend_from_config,
+    get_backend_for_config,
+    get_sync_backend,
+)
+from .backends import GitHubSyncBackend, VanillaGitSyncBackend
+from .sync_merge_orchestrator import SyncMergeOrchestrator
+
+__all__ = [
+    "GitHubSyncBackend",
+    "VanillaGitSyncBackend",
+    "get_sync_backend",
+    "get_backend_for_config",
+    "detect_backend_from_config",
+    "SyncMergeOrchestrator",
+]

roadmap/adapters/sync/backend_factory.py

@@ -0,0 +1,108 @@
+"""Factory for creating sync backend instances based on configuration."""
+
+from typing import Literal
+
+import structlog
+
+from roadmap.adapters.sync.backends.github_sync_backend import GitHubSyncBackend
+from roadmap.adapters.sync.backends.vanilla_git_sync_backend import (
+    VanillaGitSyncBackend,
+)
+from roadmap.core.interfaces.sync_backend import SyncBackendInterface
+from roadmap.infrastructure.coordination.core import RoadmapCore
+
+log = structlog.get_logger()
+
+
+def get_sync_backend(
+    backend_type: Literal["github", "git"],
+    core: RoadmapCore,
+    config: dict | None = None,
+) -> SyncBackendInterface | None:
+    """Create and return a sync backend instance.
+
+    Args:
+        backend_type: Type of backend to create ('github' or 'git')
+        core: RoadmapCore instance
+        config: Configuration dict for the backend
+
+    Returns:
+        Backend instance implementing SyncBackendInterface, or None if creation fails
+
+    Raises:
+        ValueError: If backend_type is invalid
+    """
+    config_dict = config or {}
+
+    if backend_type == "github":
+        log.info("sync_backend_creating", backend_type="github")
+        return GitHubSyncBackend(core, config_dict)
+    elif backend_type == "git":
+        try:
+            log.info("sync_backend_creating", backend_type="git")
+            return VanillaGitSyncBackend(core, config_dict)
+        except (ValueError, RuntimeError) as e:
+            # VanillaGitSyncBackend raises on init failure (not in git repo, etc.)
+            log.warning(
+                "sync_backend_creation_failed",
+                backend_type="git",
+                error=str(e),
+                error_type=type(e).__name__,
+            )
+            return None
+    else:
+        raise ValueError(
+            f"Invalid backend type: {backend_type}. Must be 'github' or 'git'"
+        )
+
+
+def detect_backend_from_config(config: dict) -> Literal["github", "git"]:
+    """Detect the appropriate backend from configuration.
+
+    Args:
+        config: Configuration dict from .roadmap/config.json or .github/config.json
+
+    Returns:
+        Backend type to use ('github' or 'git')
+    """
+    # If explicitly specified in config, use that
+    if config.get("backend") in ("github", "git"):
+        backend = config["backend"]
+        log.info("backend_detected_explicit", backend=backend)
+        return backend
+
+    # If GitHub config present, prefer GitHub backend
+    if config.get("github") and (
+        config["github"].get("owner") and config["github"].get("repo")
+    ):
+        log.info(
+            "backend_detected_github_config",
+            has_owner=bool(config["github"].get("owner")),
+            has_repo=bool(config["github"].get("repo")),
+        )
+        return "github"
+
+    # Default to vanilla git backend
+    log.info("backend_detected_default", backend="git")
+    return "git"
+
+
+def get_backend_for_config(
+    core: RoadmapCore, config: dict | None = None
+) -> SyncBackendInterface | None:
+    """Create backend based on auto-detected config.
+
+    Convenience function that detects the appropriate backend type
+    and creates an instance.
+
+    Args:
+        core: RoadmapCore instance
+        config: Configuration dict (optional)
+
+    Returns:
+        Backend instance, or None if creation fails
+    """
+    config = config or {}
+    backend_type = detect_backend_from_config(config)
+    log.debug("backend_factory_creating_instance", backend_type=backend_type)
+    return get_sync_backend(backend_type, core, config)

roadmap/adapters/sync/backends/__init__.py

@@ -0,0 +1,15 @@
+"""Sync backend implementations.
+
+Provides pluggable sync backends for integrating with various platforms:
+- GitHub: GitHub API-based sync
+- Vanilla Git: Git push/pull-based sync
+- Other: Extensible for GitLab, Jira, etc.
+"""
+
+from .github_sync_backend import GitHubSyncBackend
+from .vanilla_git_sync_backend import VanillaGitSyncBackend
+
+__all__ = [
+    "GitHubSyncBackend",
+    "VanillaGitSyncBackend",
+]

roadmap/adapters/sync/backends/converters.py

@@ -0,0 +1,209 @@
+"""Converters between Issue domain objects and GitHub API payloads.
+
+This module handles bidirectional conversion:
+- Issue → GitHub API payload (for push)
+- GitHub API response → Issue (for pull)
+"""
+
+from typing import Any
+
+from structlog import get_logger
+
+from roadmap.common.constants import Status
+from roadmap.core.domain.issue import Issue
+from roadmap.core.models.sync_models import SyncIssue
+
+logger = get_logger()
+
+
+class IssueToGitHubPayloadConverter:
+    """Convert Issue domain object to GitHub API payload."""
+
+    @staticmethod
+    def to_create_payload(issue: Issue) -> dict[str, Any]:
+        """Convert Issue to GitHub API payload for create_issue().
+
+        Args:
+            issue: The Issue domain object
+
+        Returns:
+            Dictionary suitable for GitHub API create_issue() call
+            (does NOT include 'state' - that's only for updates)
+        """
+        payload: dict[str, Any] = {
+            "title": issue.title,
+            "body": issue.content or "",  # Use content as description
+        }
+
+        labels = [
+            label
+            for label in (issue.labels or [])
+            if isinstance(label, str) and label.strip()
+        ]
+        if labels:
+            payload["labels"] = labels
+
+        if isinstance(issue.assignee, str) and issue.assignee.strip():
+            payload["assignees"] = [issue.assignee.strip()]
+
+        # NOTE: milestone field requires a milestone number/ID, not a string name
+        # GitHub API validation fails if we send milestone names instead of numbers
+        # Skip milestone for now until we have proper milestone mapping
+        # if issue.milestone:
+        #     payload["milestone"] = issue.milestone
+
+        return payload
+
+    @staticmethod
+    def to_update_payload(issue: Issue) -> dict[str, Any]:
+        """Convert Issue to GitHub API payload for update_issue().
+
+        Args:
+            issue: The Issue domain object
+
+        Returns:
+            Dictionary suitable for GitHub API update_issue() call
+        """
+        payload: dict[str, Any] = {
+            "title": issue.title,
+            "body": issue.content or "",  # Use content as description
+        }
+
+        # Map roadmap status to GitHub state (only on update)
+        # GitHub only has open/closed, so we map our status accordingly
+        if issue.status == Status.CLOSED:
+            payload["state"] = "closed"
+        else:
+            payload["state"] = "open"
+
+        labels = [
+            label
+            for label in (issue.labels or [])
+            if isinstance(label, str) and label.strip()
+        ]
+        if labels:
+            payload["labels"] = labels
+
+        if isinstance(issue.assignee, str) and issue.assignee.strip():
+            payload["assignees"] = [issue.assignee.strip()]
+
+        # NOTE: milestone field requires a milestone number/ID, not a string name
+        # GitHub API validation fails if we send milestone names instead of numbers
+        # Skip milestone for now until we have proper milestone mapping
+        # if issue.milestone:
+        #     payload["milestone"] = issue.milestone
+
+        return payload
+
+    @staticmethod
+    def to_payload(issue: Issue, github_number: int | None = None) -> dict[str, Any]:
+        """Convert Issue to GitHub API payload for create or update.
+
+        Args:
+            issue: The Issue domain object
+            github_number: Optional GitHub issue number for update (None for create)
+
+        Returns:
+            Dictionary suitable for GitHub API create_issue or update_issue call
+        """
+        # Delegate to specific methods based on whether this is create or update
+        if github_number:
+            return IssueToGitHubPayloadConverter.to_update_payload(issue)
+        else:
+            return IssueToGitHubPayloadConverter.to_create_payload(issue)
+
+    @staticmethod
+    def get_github_number(issue: Issue) -> int | None:
+        """Extract GitHub issue number from Issue's remote_ids.
+
+        Args:
+            issue: The Issue domain object
+
+        Returns:
+            GitHub issue number if linked, None otherwise
+        """
+        if issue.remote_ids and "github" in issue.remote_ids:
+            github_id = issue.remote_ids["github"]
+            # Convert to int if needed
+            if isinstance(github_id, str):
+                try:
+                    return int(github_id)
+                except ValueError:
+                    logger.debug(
+                        "failed_to_convert_github_id_to_int",
+                        github_id=github_id,
+                    )
+                    return None
+            return github_id
+        return None
+
+
+class GitHubPayloadToIssueConverter:
+    """Convert GitHub API response to Issue domain object."""
+
+    @staticmethod
+    def from_sync_issue(sync_issue: SyncIssue) -> Issue:
+        """Convert SyncIssue to Issue domain object.
+
+        Args:
+            sync_issue: The SyncIssue from GitHub fetch
+
+        Returns:
+            Issue domain object
+        """
+        # Map GitHub state to roadmap status
+        # SyncIssue.status is already normalized: "open" or "closed"
+        status = Status.CLOSED if sync_issue.status == "closed" else Status.TODO
+
+        issue = Issue(
+            title=sync_issue.title,
+            content=sync_issue.headline or "",  # headline is the content in SyncIssue
+            status=status,
+            labels=sync_issue.labels or [],
+            assignee=sync_issue.assignee,
+            milestone=sync_issue.milestone,
+        )
+
+        # Store the GitHub issue number as remote_id
+        # Use backend_id if available, or look in remote_ids dict
+        github_number = sync_issue.backend_id or sync_issue.remote_ids.get("github")
+        if github_number:
+            issue.remote_ids["github"] = (
+                int(github_number) if isinstance(github_number, str) else github_number
+            )
+
+        return issue
+
+    @staticmethod
+    def from_github_dict(github_dict: dict[str, Any]) -> Issue:
+        """Convert GitHub API issue dict to Issue domain object.
+
+        Args:
+            github_dict: Dictionary from GitHub API response
+
+        Returns:
+            Issue domain object
+        """
+        # Map GitHub state to roadmap status
+        status = Status.CLOSED if github_dict.get("state") == "closed" else Status.TODO
+
+        # Extract assignee (GitHub returns list)
+        assignees = github_dict.get("assignees") or []
+        assignee = assignees[0]["login"] if assignees else None
+
+        issue = Issue(
+            title=github_dict.get("title", ""),
+            content=github_dict.get("body") or "",
+            status=status,
+            labels=[label["name"] for label in (github_dict.get("labels") or [])],
+            assignee=assignee,
+            milestone=github_dict.get("milestone", {}).get("title")
+            if github_dict.get("milestone")
+            else None,
+        )
+
+        # Store GitHub issue number
+        if "number" in github_dict:
+            issue.remote_ids["github"] = github_dict["number"]
+
+        return issue