kestrel-feature-github 0.1.1__tar.gz → 0.2.0__tar.gz

{kestrel_feature_github-0.1.1 → kestrel_feature_github-0.2.0}/.gitignore

@@ -1,3 +1,4 @@
 __pycache__/
 *.pyc
 agent_data/
+uv.lock

{kestrel_feature_github-0.1.1 → kestrel_feature_github-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kestrel-feature-github
-Version: 0.1.1
+Version: 0.2.0
 Summary: Kestrel GitHub integration feature
 License: Apache-2.0
 License-File: LICENSE

{kestrel_feature_github-0.1.1 → kestrel_feature_github-0.2.0}/kestrel_feature_github/SKILL.md

@@ -52,6 +52,12 @@
 - **Description**: Get information about the agent's own source repository
 - **Category**: data_access
 
+### get_github_repo_info
+- **Description**: Get metadata for any accessible GitHub repository, including visibility, default branch, description, and open issue count
+- **Category**: data_access
+- **Parameters**:
+  - `repo` (string, optional): Repository in 'owner/repo' format, or 'self' (default: self)
+
 ### list_source_components
 - **Description**: List all feature components in the agent's source code
 - **Category**: data_access

{kestrel_feature_github-0.1.1 → kestrel_feature_github-0.2.0}/kestrel_feature_github/client.py

@@ -2,7 +2,7 @@
 import base64
 import logging
 import os
-from typing import Optional
+from typing import Any, Optional
 from urllib.parse import quote
 
 import httpx
@@ -112,11 +112,26 @@ class GitHubClient:
             self._client = None
 
     def _parse_repo(self, repo: str) -> tuple[str, str]:
-        """Parse owner/repo string."""
+        """Parse and URL-encode an ``owner/repo`` string.
+
+        The segments are only ever interpolated into REST paths, so encode them
+        (``safe=""`` also encodes ``/``): a crafted repo containing ``/``,
+        ``..``, or query/fragment characters can't inject into or traverse the
+        API path (F348). Legit ``owner/repo`` characters are all unreserved, so
+        they pass through unchanged.
+        """
         if "/" not in repo:
             raise GitHubClientError(f"Invalid repo format: {repo}. Expected 'owner/repo'.")
-        parts = repo.split("/", 1)
-        return parts[0], parts[1]
+        owner, repo_name = repo.split("/", 1)
+        # Reject empty or dot-only segments: '.'/'..' are unreserved so ``quote``
+        # leaves them intact and httpx collapses them in the path, which would
+        # still allow REST traversal (e.g. '../meta', 'owner/..').
+        for seg in (owner, repo_name):
+            if seg in ("", ".", ".."):
+                raise GitHubClientError(
+                    f"Invalid repo format: {repo}. Expected 'owner/repo'."
+                )
+        return quote(owner, safe=""), quote(repo_name, safe="")
 
     async def get_file_content(
         self,
@@ -430,6 +445,8 @@ class GitHubClient:
         state: str = "open",
         labels: Optional[list[str]] = None,
         per_page: int = 30,
+        sort: Optional[str] = None,
+        direction: Optional[str] = None,
     ) -> list[dict]:
         """List issues in a repository.
 
@@ -438,6 +455,9 @@ class GitHubClient:
             state: Issue state filter ('open', 'closed', 'all')
             labels: Optional list of label names to filter by
             per_page: Number of results per page (max 100)
+            sort: Optional sort field ('created', 'updated', 'comments').
+                GitHub defaults to 'created' descending.
+            direction: Optional sort direction ('asc', 'desc').
 
         Returns:
             List of issue dicts (excludes pull requests)
@@ -454,6 +474,10 @@ class GitHubClient:
         }
         if labels:
             params["labels"] = ",".join(labels)
+        if sort:
+            params["sort"] = sort
+        if direction:
+            params["direction"] = direction
 
         response = await client.get(
             f"/repos/{owner}/{repo_name}/issues",
@@ -471,6 +495,92 @@ class GitHubClient:
         items = response.json()
         return [i for i in items if "pull_request" not in i]
 
+    async def list_pull_requests(
+        self,
+        repo: str,
+        state: str = "open",
+        per_page: int = 100,
+    ) -> list[dict]:
+        """List pull requests in a repository (oldest-updated first).
+
+        Args:
+            repo: Repository in 'owner/repo' format
+            state: PR state filter ('open', 'closed', 'all')
+            per_page: Number of results per page (max 100)
+
+        Returns:
+            List of pull-request dicts.
+
+        Raises:
+            GitHubClientError: If request fails
+        """
+        owner, repo_name = self._parse_repo(repo)
+        client = await self._get_client()
+
+        response = await client.get(
+            f"/repos/{owner}/{repo_name}/pulls",
+            params={
+                "state": state,
+                "per_page": min(per_page, 100),
+                "sort": "updated",
+                "direction": "asc",
+            },
+        )
+
+        if response.status_code == 404:
+            raise GitHubClientError(f"Repository not found: {repo}", 404)
+        elif response.status_code == 403:
+            raise GitHubClientError("Rate limited or access denied", 403)
+        elif response.status_code != 200:
+            raise GitHubClientError(f"GitHub API error: {response.text}", response.status_code)
+
+        return response.json()
+
+    async def list_workflow_runs(
+        self,
+        repo: str,
+        branch: Optional[str] = None,
+        per_page: int = 1,
+        status: str = "completed",
+    ) -> list[dict]:
+        """List Actions workflow runs for a repo (newest first).
+
+        Args:
+            repo: Repository in 'owner/repo' format
+            branch: Optional branch filter (e.g. the default branch)
+            per_page: Number of runs to return (max 100)
+            status: Run status filter (default 'completed')
+
+        Returns:
+            List of workflow-run dicts (the ``workflow_runs`` array).
+
+        Raises:
+            GitHubClientError: If request fails
+        """
+        owner, repo_name = self._parse_repo(repo)
+        client = await self._get_client()
+
+        params: dict[str, Any] = {
+            "per_page": min(per_page, 100),
+            "status": status,
+        }
+        if branch:
+            params["branch"] = branch
+
+        response = await client.get(
+            f"/repos/{owner}/{repo_name}/actions/runs",
+            params=params,
+        )
+
+        if response.status_code == 404:
+            raise GitHubClientError(f"Repository not found: {repo}", 404)
+        elif response.status_code == 403:
+            raise GitHubClientError("Rate limited or access denied", 403)
+        elif response.status_code != 200:
+            raise GitHubClientError(f"GitHub API error: {response.text}", response.status_code)
+
+        return response.json().get("workflow_runs", [])
+
     async def get_issue(
         self,
         repo: str,
@@ -539,3 +649,252 @@ class GitHubClient:
             raise GitHubClientError(f"GitHub API error: {response.text}", response.status_code)
 
         return response.json()
+
+    # ============================================================
+    # Write API — feeds the @tool surface in feature.py.
+    # Each method is a thin wrapper around a single REST endpoint;
+    # error mapping mirrors the read-side pattern.
+    # ============================================================
+
+    async def add_issue_comment(
+        self,
+        repo: str,
+        issue_number: int,
+        body: str,
+    ) -> dict:
+        """Post a comment on an issue or pull request.
+
+        Note: GitHub uses the issues endpoint for both issue and PR comments —
+        PR review comments (on specific lines) are a separate endpoint not
+        wrapped here.
+        """
+        owner, repo_name = self._parse_repo(repo)
+        client = await self._get_client()
+        response = await client.post(
+            f"/repos/{owner}/{repo_name}/issues/{issue_number}/comments",
+            json={"body": body},
+        )
+        if response.status_code == 201:
+            return response.json()
+        if response.status_code == 404:
+            raise GitHubClientError(f"Issue #{issue_number} not found in {repo}", 404)
+        if response.status_code == 403:
+            raise GitHubClientError("Rate limited or access denied", 403)
+        raise GitHubClientError(
+            f"Comment creation failed: {response.text}", response.status_code,
+        )
+
+    async def add_labels(
+        self,
+        repo: str,
+        issue_number: int,
+        labels: list[str],
+    ) -> list[dict]:
+        """Add labels to an issue or PR (additive — existing labels preserved)."""
+        owner, repo_name = self._parse_repo(repo)
+        client = await self._get_client()
+        response = await client.post(
+            f"/repos/{owner}/{repo_name}/issues/{issue_number}/labels",
+            json={"labels": labels},
+        )
+        if response.status_code == 200:
+            return response.json()
+        if response.status_code == 404:
+            raise GitHubClientError(f"Issue #{issue_number} not found in {repo}", 404)
+        if response.status_code == 403:
+            raise GitHubClientError("Rate limited or access denied", 403)
+        raise GitHubClientError(
+            f"Label add failed: {response.text}", response.status_code,
+        )
+
+    async def remove_label(
+        self,
+        repo: str,
+        issue_number: int,
+        label: str,
+    ) -> None:
+        """Remove a single label from an issue or PR.
+
+        Returns None on success. Specifically idempotent ONLY for
+        "label-not-on-issue" — GitHub's response body for that case
+        contains "Label does not exist". A 404 with any other body
+        (missing issue, missing repo, insufficient access) raises
+        ``GitHubClientError`` so the caller doesn't get a false-positive
+        success for an entirely different failure mode.
+        """
+        owner, repo_name = self._parse_repo(repo)
+        client = await self._get_client()
+        # GitHub requires the label path-segment to be URL-encoded.
+        from urllib.parse import quote
+        response = await client.delete(
+            f"/repos/{owner}/{repo_name}/issues/{issue_number}/labels/{quote(label, safe='')}",
+        )
+        if response.status_code in (200, 204):
+            return None
+        if response.status_code == 404:
+            # Disambiguate label-not-on-issue from issue/repo-missing. GitHub
+            # returns the same status code for both; only the body differs.
+            body = (response.text or "").lower()
+            if "label does not exist" in body:
+                return None  # Idempotent success — label wasn't on the issue.
+            raise GitHubClientError(
+                f"Issue or repo not found, or label endpoint unreachable: "
+                f"{response.text}",
+                404,
+            )
+        if response.status_code == 403:
+            raise GitHubClientError("Rate limited or access denied", 403)
+        raise GitHubClientError(
+            f"Label remove failed: {response.text}", response.status_code,
+        )
+
+    async def update_issue(
+        self,
+        repo: str,
+        issue_number: int,
+        *,
+        state: Optional[str] = None,
+        state_reason: Optional[str] = None,
+        title: Optional[str] = None,
+        body: Optional[str] = None,
+    ) -> dict:
+        """Patch an issue. Used for close/reopen (via state) and edits.
+
+        ``state`` is ``open`` or ``closed``. ``state_reason`` may be
+        ``completed``, ``not_planned``, or ``reopened`` (per GitHub's
+        documented values). Pass only the fields you intend to change.
+        """
+        owner, repo_name = self._parse_repo(repo)
+        client = await self._get_client()
+        payload: dict = {}
+        if state is not None:
+            payload["state"] = state
+        if state_reason is not None:
+            payload["state_reason"] = state_reason
+        if title is not None:
+            payload["title"] = title
+        if body is not None:
+            payload["body"] = body
+        if not payload:
+            raise GitHubClientError(
+                "update_issue called with no fields to update", 400,
+            )
+        response = await client.patch(
+            f"/repos/{owner}/{repo_name}/issues/{issue_number}",
+            json=payload,
+        )
+        if response.status_code == 200:
+            return response.json()
+        if response.status_code == 404:
+            raise GitHubClientError(f"Issue #{issue_number} not found in {repo}", 404)
+        if response.status_code == 403:
+            raise GitHubClientError("Rate limited or access denied", 403)
+        if response.status_code == 422:
+            raise GitHubClientError(
+                f"Issue update validation failed: {response.text}", 422,
+            )
+        raise GitHubClientError(
+            f"Issue update failed: {response.text}", response.status_code,
+        )
+
+    async def create_pull_request(
+        self,
+        repo: str,
+        *,
+        title: str,
+        head: str,
+        base: str,
+        body: str = "",
+        draft: bool = False,
+        maintainer_can_modify: bool = True,
+    ) -> dict:
+        """Open a pull request.
+
+        ``head`` is the branch carrying the changes (use ``owner:branch`` for
+        cross-fork PRs; same-repo can be just the branch name). ``base`` is
+        the target branch on this repo.
+        """
+        owner, repo_name = self._parse_repo(repo)
+        client = await self._get_client()
+        response = await client.post(
+            f"/repos/{owner}/{repo_name}/pulls",
+            json={
+                "title": title,
+                "head": head,
+                "base": base,
+                "body": body,
+                "draft": draft,
+                "maintainer_can_modify": maintainer_can_modify,
+            },
+        )
+        if response.status_code == 201:
+            return response.json()
+        if response.status_code == 403:
+            raise GitHubClientError("Rate limited or access denied", 403)
+        if response.status_code == 404:
+            raise GitHubClientError(f"Repository not found or no permission: {repo}", 404)
+        if response.status_code == 422:
+            # 422 covers "no diff", "head already PR'd", "branch missing", etc.
+            raise GitHubClientError(
+                f"PR creation validation failed: {response.text}", 422,
+            )
+        raise GitHubClientError(
+            f"PR creation failed: {response.text}", response.status_code,
+        )
+
+    async def merge_pull_request(
+        self,
+        repo: str,
+        pull_number: int,
+        *,
+        commit_title: Optional[str] = None,
+        commit_message: Optional[str] = None,
+        merge_method: str = "squash",
+        sha: Optional[str] = None,
+    ) -> dict:
+        """Merge a pull request.
+
+        ``merge_method`` is ``merge``, ``squash``, or ``rebase``.
+        If ``sha`` is set, the merge will fail unless the PR HEAD matches —
+        callers should pass it when they need strict head-stability.
+        """
+        if merge_method not in ("merge", "squash", "rebase"):
+            raise GitHubClientError(
+                f"merge_method must be merge|squash|rebase, got {merge_method!r}",
+                400,
+            )
+        owner, repo_name = self._parse_repo(repo)
+        client = await self._get_client()
+        payload: dict = {"merge_method": merge_method}
+        if commit_title is not None:
+            payload["commit_title"] = commit_title
+        if commit_message is not None:
+            payload["commit_message"] = commit_message
+        if sha is not None:
+            payload["sha"] = sha
+        response = await client.put(
+            f"/repos/{owner}/{repo_name}/pulls/{pull_number}/merge",
+            json=payload,
+        )
+        if response.status_code == 200:
+            return response.json()
+        if response.status_code == 405:
+            raise GitHubClientError(
+                f"PR #{pull_number} is not mergeable: {response.text}", 405,
+            )
+        if response.status_code == 409:
+            raise GitHubClientError(
+                f"PR #{pull_number} head SHA mismatch (someone pushed): {response.text}",
+                409,
+            )
+        if response.status_code == 403:
+            raise GitHubClientError("Rate limited or access denied", 403)
+        if response.status_code == 404:
+            raise GitHubClientError(f"PR #{pull_number} not found in {repo}", 404)
+        if response.status_code == 422:
+            raise GitHubClientError(
+                f"Merge validation failed: {response.text}", 422,
+            )
+        raise GitHubClientError(
+            f"PR merge failed: {response.text}", response.status_code,
+        )