snodo-tools 0.7.2__tar.gz

snodo_tools-0.7.2/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: snodo-tools
+Version: 0.7.2
+Summary: Snodo tools — git, shell, workspace primitives + providers
+Author-email: The Snodo Authors <noreply@snodo.dev>
+License: Apache-2.0
+Project-URL: Homepage, https://snodo.dev
+Project-URL: Repository, https://github.com/snodo-dev/snodo
+Requires-Python: >=3.12
+Requires-Dist: snodo-core==0.7.2
+Requires-Dist: GitPython>=3.1.0
+Requires-Dist: PyGithub>=2.0.0

snodo_tools-0.7.2/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "snodo-tools"
+version = "0.7.2"
+description = "Snodo tools — git, shell, workspace primitives + providers"
+requires-python = ">=3.12"
+license = { text = "Apache-2.0" }
+authors = [{ name = "The Snodo Authors", email = "noreply@snodo.dev" }]
+dependencies = [
+    "snodo-core==0.7.2",
+    "GitPython>=3.1.0",
+    "PyGithub>=2.0.0",
+]
+
+[project.urls]
+Homepage = "https://snodo.dev"
+Repository = "https://github.com/snodo-dev/snodo"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+namespaces = true
+
+[tool.setuptools.package-data]
+snodo = ["py.typed"]

snodo_tools-0.7.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

snodo_tools-0.7.2/src/snodo/providers/__init__.py

@@ -0,0 +1,16 @@
+"""Code host provider plugins.
+
+FILE: snodo/providers/__init__.py
+"""
+
+from snodo.providers.base import CodeHostProvider, ProviderError
+from snodo.providers.local import LocalProvider
+from snodo.providers.registry import detect_provider, list_providers
+
+__all__ = [
+    "CodeHostProvider",
+    "ProviderError",
+    "LocalProvider",
+    "detect_provider",
+    "list_providers",
+]

snodo_tools-0.7.2/src/snodo/providers/base.py

@@ -0,0 +1,106 @@
+"""Code host provider abstract base class.
+
+FILE: snodo/providers/base.py
+
+Defines the interface that all code host providers must implement.
+Providers decouple PR operations from any specific platform (GitHub, GitLab, etc).
+"""
+
+from abc import ABC, abstractmethod
+
+
+class ProviderError(Exception):
+    """Raised when a provider operation fails."""
+
+
+class CodeHostProvider(ABC):
+    """Abstract base class for code host providers.
+
+    Each provider implements PR operations for a specific platform.
+    PrMCP delegates to a concrete provider instance.
+    """
+
+    @abstractmethod
+    def create_pr(self, branch: str, title: str, body: str) -> str:
+        """Create a pull request.
+
+        Args:
+            branch: Source branch name
+            title: PR title
+            body: PR description body
+
+        Returns:
+            PR URL or identifier string
+        """
+
+    @abstractmethod
+    def read_pr_diff(self, pr_number: int) -> str:
+        """Read the diff of a pull request.
+
+        Args:
+            pr_number: PR number
+
+        Returns:
+            Diff output as string
+        """
+
+    @abstractmethod
+    def post_review_comment(self, pr_number: int, comment: str) -> str:
+        """Post a comment on a pull request.
+
+        Args:
+            pr_number: PR number
+            comment: Comment text
+
+        Returns:
+            Confirmation string
+        """
+
+    @abstractmethod
+    def approve_pr(self, pr_number: int) -> str:
+        """Approve a pull request.
+
+        Args:
+            pr_number: PR number
+
+        Returns:
+            Confirmation string
+        """
+
+    @abstractmethod
+    def reject_pr(self, pr_number: int, reason: str) -> str:
+        """Request changes on a pull request.
+
+        Args:
+            pr_number: PR number
+            reason: Reason for rejection
+
+        Returns:
+            Confirmation string
+        """
+
+    @abstractmethod
+    def merge_pr(self, pr_number: int) -> str:
+        """Merge a pull request.
+
+        Args:
+            pr_number: PR number
+
+        Returns:
+            Confirmation string
+        """
+
+    @abstractmethod
+    def read_pr_comments(self, pr_number: int) -> str:
+        """Read comments and reviews on a pull request.
+
+        Returns JSON string with keys: title, comments, reviews.
+        Each comment has: author.login, body
+        Each review has: author.login, body, state
+
+        Args:
+            pr_number: PR number
+
+        Returns:
+            JSON string
+        """

snodo_tools-0.7.2/src/snodo/providers/github.py

@@ -0,0 +1,158 @@
+"""GitHub code host provider using PyGithub.
+
+FILE: snodo/providers/github.py
+
+Implements CodeHostProvider for GitHub using the PyGithub library.
+No gh CLI required.
+"""
+
+import json
+import os
+from typing import Optional
+
+from snodo.providers.base import CodeHostProvider, ProviderError
+
+try:
+    from github import Github
+except ImportError:
+    Github = None  # type: ignore[assignment,misc]
+
+
+class GitHubProvider(CodeHostProvider):
+    """GitHub provider using PyGithub.
+
+    Authentication via GITHUB_TOKEN env var or snodo config.
+    Repo slug detected from git remote URL or passed explicitly.
+    """
+
+    def __init__(self, repo_slug: str, token: Optional[str] = None):
+        """Initialize GitHub provider.
+
+        Args:
+            repo_slug: Repository in "owner/repo" format
+            token: GitHub API token. If None, resolved from environment.
+
+        Raises:
+            ProviderError: If PyGithub is not installed or auth fails
+        """
+        if Github is None:
+            raise ProviderError(
+                "PyGithub is required for GitHub provider. "
+                "Install it with: pip install PyGithub"
+            )
+
+        self._token = token or self._resolve_token()
+        if not self._token:
+            raise ProviderError(
+                "GitHub token required. Set GITHUB_TOKEN env var "
+                "or configure via: snodo config set github <token>"
+            )
+
+        self._repo_slug = repo_slug
+
+        try:
+            self._github = Github(self._token)
+            self._repo = self._github.get_repo(repo_slug)
+        except Exception as e:
+            raise ProviderError(f"Failed to connect to GitHub repo '{repo_slug}': {e}") from e
+
+    @staticmethod
+    def _resolve_token() -> Optional[str]:
+        """Resolve GitHub token from env or snodo config."""
+        token = os.environ.get("GITHUB_TOKEN")
+        if token:
+            return token
+        try:
+            from snodo.config import ConfigManager
+            return ConfigManager().get_key("github")
+        except Exception:
+            return None
+
+    def create_pr(self, branch: str, title: str, body: str) -> str:
+        """Create a pull request on GitHub."""
+        try:
+            pr = self._repo.create_pull(
+                title=title, body=body, head=branch, base="main",
+            )
+            return pr.html_url
+        except Exception as e:
+            raise ProviderError(f"Failed to create PR: {e}") from e
+
+    def read_pr_diff(self, pr_number: int) -> str:
+        """Read PR diff by concatenating file patches."""
+        try:
+            pr = self._repo.get_pull(pr_number)
+            files = pr.get_files()
+            patches = []
+            for f in files:
+                header = f"diff --git a/{f.filename} b/{f.filename}"
+                if f.patch:
+                    patches.append(f"{header}\n{f.patch}")
+                else:
+                    patches.append(f"{header}\n(binary file)")
+            return "\n".join(patches) if patches else "(no changes)"
+        except Exception as e:
+            raise ProviderError(f"Failed to read PR diff: {e}") from e
+
+    def post_review_comment(self, pr_number: int, comment: str) -> str:
+        """Post a comment on a GitHub PR."""
+        try:
+            pr = self._repo.get_pull(pr_number)
+            c = pr.create_issue_comment(comment)
+            return c.html_url
+        except Exception as e:
+            raise ProviderError(f"Failed to post comment: {e}") from e
+
+    def approve_pr(self, pr_number: int) -> str:
+        """Approve a GitHub PR."""
+        try:
+            pr = self._repo.get_pull(pr_number)
+            pr.create_review(event="APPROVE")
+            return f"PR #{pr_number} approved"
+        except Exception as e:
+            raise ProviderError(f"Failed to approve PR: {e}") from e
+
+    def reject_pr(self, pr_number: int, reason: str) -> str:
+        """Request changes on a GitHub PR."""
+        try:
+            pr = self._repo.get_pull(pr_number)
+            pr.create_review(body=reason, event="REQUEST_CHANGES")
+            return f"PR #{pr_number} changes requested"
+        except Exception as e:
+            raise ProviderError(f"Failed to reject PR: {e}") from e
+
+    def merge_pr(self, pr_number: int) -> str:
+        """Merge a GitHub PR."""
+        try:
+            pr = self._repo.get_pull(pr_number)
+            result = pr.merge()
+            return f"PR #{pr_number} merged: {result.sha[:8]}"
+        except Exception as e:
+            raise ProviderError(f"Failed to merge PR: {e}") from e
+
+    def read_pr_comments(self, pr_number: int) -> str:
+        """Read PR comments and reviews as JSON.
+
+        Returns JSON compatible with _format_pr_comments in run_cmd.py.
+        """
+        try:
+            pr = self._repo.get_pull(pr_number)
+            comments = [
+                {"author": {"login": c.user.login}, "body": c.body or ""}
+                for c in pr.get_issue_comments()
+            ]
+            reviews = [
+                {
+                    "author": {"login": r.user.login},
+                    "body": r.body or "",
+                    "state": r.state,
+                }
+                for r in pr.get_reviews()
+            ]
+            return json.dumps({
+                "title": pr.title,
+                "comments": comments,
+                "reviews": reviews,
+            })
+        except Exception as e:
+            raise ProviderError(f"Failed to read PR comments: {e}") from e

snodo_tools-0.7.2/src/snodo/providers/local.py

@@ -0,0 +1,54 @@
+"""Local (no-op) code host provider.
+
+FILE: snodo/providers/local.py
+
+Provider for repositories without a remote code host.
+PR operations return stub responses. Useful for solo/offline workflows.
+"""
+
+
+from snodo.providers.base import CodeHostProvider, ProviderError
+
+
+class LocalProvider(CodeHostProvider):
+    """No-op provider for local-only repositories.
+
+    All mutating operations return stub responses.
+    Read operations return empty/placeholder data.
+    """
+
+    def create_pr(self, branch: str, title: str, body: str) -> str:
+        raise ProviderError(
+            "Cannot create PR: no remote code host configured. "
+            "Push to a remote and configure a provider."
+        )
+
+    def read_pr_diff(self, pr_number: int) -> str:
+        raise ProviderError(
+            f"Cannot read PR #{pr_number}: no remote code host configured."
+        )
+
+    def post_review_comment(self, pr_number: int, comment: str) -> str:
+        raise ProviderError(
+            "Cannot post comment: no remote code host configured."
+        )
+
+    def approve_pr(self, pr_number: int) -> str:
+        raise ProviderError(
+            "Cannot approve PR: no remote code host configured."
+        )
+
+    def reject_pr(self, pr_number: int, reason: str) -> str:
+        raise ProviderError(
+            "Cannot reject PR: no remote code host configured."
+        )
+
+    def merge_pr(self, pr_number: int) -> str:
+        raise ProviderError(
+            "Cannot merge PR: no remote code host configured."
+        )
+
+    def read_pr_comments(self, pr_number: int) -> str:
+        raise ProviderError(
+            f"Cannot read PR #{pr_number} comments: no remote code host configured."
+        )

snodo_tools-0.7.2/src/snodo/providers/registry.py

@@ -0,0 +1,222 @@
+"""Provider registry: detection, resolution, and plugin discovery.
+
+FILE: snodo/providers/registry.py
+
+Resolves which CodeHostProvider to use for a project:
+1. Explicit provider in protocol.metadata["provider"]
+2. Auto-detect from git remote URL
+3. Setuptools entry points (snodo.providers group)
+4. Fallback to LocalProvider
+"""
+
+import logging
+import re
+import subprocess
+from typing import Dict, Optional, Type
+
+from snodo.providers.base import CodeHostProvider, ProviderError
+from snodo.providers.local import LocalProvider
+
+_logger = logging.getLogger(__name__)
+
+
+# Built-in provider name -> class mapping (lazy imports to avoid hard deps)
+_BUILTIN_PROVIDERS = {"github", "local"}
+
+
+def detect_provider(
+    project_root: str,
+    protocol_metadata: Optional[Dict] = None,
+) -> CodeHostProvider:
+    """Detect and create the appropriate code host provider.
+
+    Resolution order:
+    1. Explicit "provider" key in protocol metadata
+    2. Auto-detect from git remote URL
+    3. Fallback to LocalProvider
+
+    Args:
+        project_root: Absolute path to project root
+        protocol_metadata: Optional protocol.metadata dict
+
+    Returns:
+        Configured CodeHostProvider instance
+    """
+    metadata = protocol_metadata or {}
+
+    # 1. Explicit provider in metadata
+    provider_name = metadata.get("provider")
+    if provider_name:
+        return _create_provider(provider_name, project_root, metadata)
+
+    # 2. Auto-detect from git remote
+    remote_url = _get_git_remote(project_root)
+    if remote_url:
+        detected = _detect_from_url(remote_url)
+        if detected:
+            return _create_provider(detected, project_root, metadata)
+
+    # 3. Fallback
+    return LocalProvider()
+
+
+def _get_git_remote(project_root: str) -> Optional[str]:
+    """Get the origin remote URL from git.
+
+    Returns:
+        Remote URL string, or None if not available
+    """
+    try:
+        result = subprocess.run(
+            ["git", "remote", "get-url", "origin"],  # noqa: S607 - git resolved from PATH by design; argv list, no shell, fully controlled flags
+            cwd=project_root,
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        return result.stdout.strip()
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return None
+
+
+def _detect_from_url(url: str) -> Optional[str]:
+    """Detect provider name from a git remote URL.
+
+    Args:
+        url: Git remote URL (SSH or HTTPS)
+
+    Returns:
+        Provider name string, or None if no match
+    """
+    if "github.com" in url:
+        return "github"
+    # Future: gitlab.com, bitbucket.org, etc.
+    return None
+
+
+def parse_github_slug(url: str) -> Optional[str]:
+    """Extract owner/repo slug from a GitHub remote URL.
+
+    Handles:
+    - git@github.com:owner/repo.git
+    - https://github.com/owner/repo.git
+    - https://github.com/owner/repo
+
+    Args:
+        url: Git remote URL
+
+    Returns:
+        "owner/repo" string, or None if not a GitHub URL
+    """
+    match = re.search(r"github\.com[:/]([^/]+/[^/]+?)(?:\.git)?$", url)
+    if match:
+        return match.group(1)
+    return None
+
+
+def _create_provider(
+    name: str,
+    project_root: str,
+    metadata: Optional[Dict] = None,
+) -> CodeHostProvider:
+    """Create a provider instance by name.
+
+    Checks built-in providers first, then entry points.
+
+    Args:
+        name: Provider name (e.g., "github", "local")
+        project_root: Project root directory
+        metadata: Protocol metadata for provider config
+
+    Returns:
+        CodeHostProvider instance
+
+    Raises:
+        ProviderError: If provider not found or initialization fails
+    """
+    metadata = metadata or {}
+
+    if name == "local":
+        return LocalProvider()
+
+    if name == "github":
+        return _create_github(project_root, metadata)
+
+    # Check entry points for third-party providers
+    provider_cls = _load_entry_point(name)
+    if provider_cls:
+        try:
+            return provider_cls(project_root=project_root, metadata=metadata)  # type: ignore[call-arg]
+        except TypeError:
+            # Provider may not accept these kwargs
+            return provider_cls()
+
+    raise ProviderError(
+        f"Unknown provider: '{name}'. "
+        f"Built-in providers: {', '.join(sorted(_BUILTIN_PROVIDERS))}. "
+        f"Install a plugin or check your protocol metadata."
+    )
+
+
+def _create_github(project_root: str, metadata: Dict) -> CodeHostProvider:
+    """Create a GitHubProvider, resolving repo slug from git remote."""
+    from snodo.providers.github import GitHubProvider
+
+    # Repo slug from metadata or git remote
+    repo_slug = metadata.get("github_repo")
+    if not repo_slug:
+        remote_url = _get_git_remote(project_root)
+        if remote_url:
+            repo_slug = parse_github_slug(remote_url)
+    if not repo_slug:
+        raise ProviderError(
+            "Could not determine GitHub repo. Set metadata.github_repo "
+            "in protocol.yml or add a github.com git remote."
+        )
+
+    token = metadata.get("github_token")
+    return GitHubProvider(repo_slug=repo_slug, token=token)
+
+
+def _load_entry_point(name: str) -> Optional[Type[CodeHostProvider]]:
+    """Load a provider class from setuptools entry points.
+
+    Looks in the 'snodo.providers' entry point group.
+
+    Args:
+        name: Entry point name
+
+    Returns:
+        Provider class, or None if not found
+    """
+    try:
+        from importlib.metadata import entry_points
+        eps = entry_points(group="snodo.providers")
+        for ep in eps:
+            if ep.name == name:
+                return ep.load()
+    except Exception as e:
+        _logger.debug("Failed to load provider entry point %s: %s", name, e)
+    return None
+
+
+def list_providers() -> Dict[str, str]:
+    """List all available providers (built-in + plugins).
+
+    Returns:
+        Dict of provider_name -> description
+    """
+    providers = {
+        "github": "GitHub (PyGithub)",
+        "local": "Local only (no remote)",
+    }
+
+    try:
+        from importlib.metadata import entry_points
+        eps = entry_points(group="snodo.providers")
+        for ep in eps:
+            providers[ep.name] = f"Plugin: {ep.value}"
+    except Exception as e:
+        _logger.debug("Failed to discover provider entry points: %s", e)
+
+    return providers

snodo_tools-0.7.2/src/snodo/tools/__init__.py

@@ -0,0 +1 @@
+# Snodo primitives / backing tools