curupira-plugins 0.1.0__py3-none-any.whl

curupira_plugins/__init__.py

@@ -0,0 +1,6 @@
+"""Official Curupira trigger extensions (GitHub issues, pull requests, and Projects)."""
+
+from importlib.metadata import version
+
+# Read from the installed distribution, whose version comes from the release tag.
+__version__ = version("curupira-plugins")

curupira_plugins/__main__.py

@@ -0,0 +1,54 @@
+"""Official Curupira trigger extension process (all providers).
+
+Console script ``curupira-plugins`` (also ``python -m curupira_plugins``) speaks
+the extension protocol on stdin/stdout. End-user settings typically launch with::
+
+    uvx --from curupira-plugins curupira-plugins
+"""
+
+from __future__ import annotations
+
+import sys
+
+from curupira_sdk import Curupira
+
+from curupira_plugins import __version__
+from curupira_plugins.github.triggers import register as register_github
+
+app = Curupira(name="curupira-plugins", version=__version__)
+register_github(app)
+
+MANIFEST = """
+manifest_version = 1
+name = "curupira-plugins"
+version = "{version}"
+protocol_version = 2
+runtime = "python"
+kind = "trigger"
+trigger_types = [
+  "github-issues",
+  "github-pull-requests",
+  "github-project-items",
+]
+
+[launch]
+type = "uvx"
+package = "curupira-plugins"
+executable = "curupira-plugins"
+
+[package]
+source = "pip"
+name = "curupira-plugins"
+version = "{version}"
+""".strip()
+
+
+def main() -> None:
+    if "--curupira-print-manifest" in sys.argv:
+        app.print_manifest(MANIFEST)
+        return
+    app.run()
+
+
+if __name__ == "__main__":
+    main()

curupira_plugins/github/__init__.py

@@ -0,0 +1 @@
+"""GitHub issues and pull-request discovery."""

curupira_plugins/github/client.py

@@ -0,0 +1,298 @@
+"""GitHub access through the authenticated gh CLI: bearer token, GraphQL search, and paging."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import time
+import urllib.error
+import urllib.request
+from collections import deque
+from collections.abc import Callable
+from typing import Any, Generic, TypeVar
+
+from curupira_sdk import RpcError
+from pydantic import ValidationError
+
+from curupira_plugins.github.models import (
+    Node,
+    ProjectItems,
+    ProjectResponse,
+    ProjectV2,
+    SearchConnection,
+    SearchResponse,
+)
+
+GRAPHQL_URL = "https://api.github.com/graphql"
+TOKEN_CACHE_SECONDS = 300.0
+PAGE_SIZE = 100
+_RETRY_STATUSES = frozenset({429, 500, 502, 503, 504})
+_ATTEMPTS = 3
+_GH_TIMEOUT_SECONDS = 30
+_HTTP_TIMEOUT_SECONDS = 30
+
+COMMON_FIELDS = """
+  id number title body url state createdAt
+  author { login }
+  labels(first: 50) { nodes { name } }
+  assignees(first: 20) { nodes { login } }
+  milestone { title }
+"""
+
+ISSUE_FIELDS = (
+    COMMON_FIELDS
+    + """
+  stateReason
+"""
+)
+
+PULL_REQUEST_FIELDS = (
+    COMMON_FIELDS
+    + """
+  headRefName baseRefName headRefOid isDraft mergeable mergeStateStatus
+  changedFiles additions deletions
+  closingIssuesReferences(first: 10) { nodes { number url } }
+"""
+)
+
+CONTENT_FRAGMENTS = f"""
+... on Issue {{ {ISSUE_FIELDS} repository {{ nameWithOwner }} }}
+... on PullRequest {{ {PULL_REQUEST_FIELDS} repository {{ nameWithOwner }} }}
+"""
+
+SEARCH_QUERY = f"""
+query CuripiraSearch($query: String!, $first: Int!, $after: String) {{
+  search(query: $query, type: ISSUE, first: $first, after: $after) {{
+    pageInfo {{ hasNextPage endCursor }}
+    nodes {{
+      ... on Issue {{ {ISSUE_FIELDS} }}
+      ... on PullRequest {{ {PULL_REQUEST_FIELDS} }}
+    }}
+  }}
+}}
+"""
+
+# `repositoryOwner` resolves users and organizations alike. `query` is the Projects view filter
+# syntax (for example `status:"In Progress",Review`) and is applied by GitHub.
+PROJECT_ITEMS_QUERY = f"""
+query CuripiraProjectItems($owner: String!, $number: Int!, $first: Int!, $after: String,
+                           $query: String) {{
+  repositoryOwner(login: $owner) {{
+    ... on ProjectV2Owner {{
+      projectV2(number: $number) {{
+        title url
+        items(first: $first, after: $after, query: $query) {{
+          pageInfo {{ hasNextPage endCursor }}
+          nodes {{
+            id isArchived
+            fieldValues(first: 50) {{
+              nodes {{
+                ... on ProjectV2ItemFieldSingleSelectValue {{ name field {{ ... on ProjectV2FieldCommon {{ name }} }} }}
+                ... on ProjectV2ItemFieldTextValue {{ text field {{ ... on ProjectV2FieldCommon {{ name }} }} }}
+                ... on ProjectV2ItemFieldNumberValue {{ number field {{ ... on ProjectV2FieldCommon {{ name }} }} }}
+                ... on ProjectV2ItemFieldDateValue {{ date field {{ ... on ProjectV2FieldCommon {{ name }} }} }}
+                ... on ProjectV2ItemFieldIterationValue {{ title field {{ ... on ProjectV2FieldCommon {{ name }} }} }}
+              }}
+            }}
+            content {{ __typename {CONTENT_FRAGMENTS} }}
+          }}
+        }}
+      }}
+    }}
+  }}
+}}
+"""
+
+NodeT = TypeVar("NodeT", bound=Node)
+ItemT = TypeVar("ItemT")
+ResponseT = TypeVar("ResponseT", SearchResponse, ProjectResponse)
+
+
+class GitHubCliToken:
+    """Read the bearer token from `gh auth token`, caching it for five minutes."""
+
+    def __init__(
+        self,
+        *,
+        clock: Callable[[], float] = time.monotonic,
+        run: Callable[..., subprocess.CompletedProcess[str]] = subprocess.run,
+    ) -> None:
+        self._clock = clock
+        self._run = run
+        self._token: str | None = None
+        self._expires_at = 0.0
+
+    def token(self) -> str:
+        now = self._clock()
+        if self._token is not None and now < self._expires_at:
+            return self._token
+        try:
+            completed = self._run(
+                ["gh", "auth", "token"],
+                capture_output=True,
+                text=True,
+                timeout=_GH_TIMEOUT_SECONDS,
+                check=False,
+            )
+        except FileNotFoundError as exc:
+            raise RpcError(-32002, "Required executable not found: gh") from exc
+        except subprocess.TimeoutExpired as exc:
+            raise RpcError(-32002, "gh auth token timed out") from exc
+        if completed.returncode != 0:
+            detail = completed.stderr.strip() or f"exit status {completed.returncode}"
+            raise RpcError(-32002, f"gh auth token failed: {detail}")
+        token = completed.stdout.strip()
+        if not token:
+            raise RpcError(-32002, "gh auth token returned an empty token")
+        self._token = token
+        self._expires_at = now + TOKEN_CACHE_SECONDS
+        return token
+
+
+class GitHubClient:
+    """Run GraphQL search requests with the gh CLI token and bounded retries."""
+
+    def __init__(
+        self,
+        tokens: GitHubCliToken,
+        *,
+        endpoint: str = GRAPHQL_URL,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        self._tokens = tokens
+        self._endpoint = endpoint
+        self._sleep = sleep
+
+    def search(self, query: str, *, after: str | None) -> SearchConnection:
+        """Return one page of issue/pull-request search results for `query`."""
+        payload = {
+            "query": SEARCH_QUERY,
+            "variables": {"query": query, "first": PAGE_SIZE, "after": after},
+        }
+        response = self._parse(self._post(payload), SearchResponse)
+        if response.data is None:
+            raise RpcError(-32002, "GitHub GraphQL response has no data")
+        return response.data.search
+
+    def project_items(
+        self, owner: str, number: int, *, view_filter: str | None, after: str | None
+    ) -> tuple[ProjectV2, ProjectItems]:
+        """Return the project and one page of its items, filtered server-side by `view_filter`."""
+        payload = {
+            "query": PROJECT_ITEMS_QUERY,
+            "variables": {
+                "owner": owner,
+                "number": number,
+                "first": PAGE_SIZE,
+                "after": after,
+                "query": view_filter,
+            },
+        }
+        response = self._parse(self._post(payload), ProjectResponse)
+        owner_node = response.data.repository_owner if response.data else None
+        project = owner_node.project_v2 if owner_node else None
+        if project is None:
+            raise RpcError(
+                -32002,
+                f"GitHub project {number} not found for {owner!r}; check the owner, the project "
+                "number, and that your token has the read:project scope "
+                "(gh auth refresh -s read:project)",
+            )
+        return project, project.items
+
+    @staticmethod
+    def _parse(body: bytes, model: type[ResponseT]) -> ResponseT:
+        try:
+            response = model.model_validate_json(body)
+        except ValidationError as exc:
+            raise RpcError(-32002, f"unexpected GitHub GraphQL response: {exc}") from exc
+        errors = getattr(response, "errors", [])
+        data = getattr(response, "data", None)
+        # A missing project is reported as a NOT_FOUND error next to partial data; let the
+        # caller explain that one, and surface everything else.
+        if errors and not (
+            data is not None and all("Could not resolve" in e.message for e in errors)
+        ):
+            messages = "; ".join(error.message for error in errors)
+            raise RpcError(-32002, f"GitHub GraphQL error: {messages}")
+        return response
+
+    def _post(self, payload: dict[str, Any]) -> bytes:
+        data = json.dumps(payload).encode("utf-8")
+        for attempt in range(1, _ATTEMPTS + 1):
+            request = urllib.request.Request(
+                self._endpoint,
+                data=data,
+                method="POST",
+                headers={
+                    "Authorization": f"Bearer {self._tokens.token()}",
+                    "Content-Type": "application/json",
+                    "Accept": "application/json",
+                    "User-Agent": "curupira-plugins",
+                },
+            )
+            try:
+                with urllib.request.urlopen(request, timeout=_HTTP_TIMEOUT_SECONDS) as response:
+                    return bytes(response.read())
+            except urllib.error.HTTPError as exc:
+                # Close the response so the connection is released before retrying or raising.
+                status = exc.code
+                exc.close()
+                if status not in _RETRY_STATUSES or attempt == _ATTEMPTS:
+                    raise RpcError(
+                        -32002, f"GitHub GraphQL request failed with status {status}"
+                    ) from exc
+            except urllib.error.URLError as exc:
+                if attempt == _ATTEMPTS:
+                    raise RpcError(-32002, f"GitHub GraphQL request failed: {exc.reason}") from exc
+            self._sleep(2.0 ** (attempt - 1))
+        raise RpcError(-32002, "GitHub GraphQL request failed")
+
+
+def parse_nodes(connection: SearchConnection, model: type[NodeT]) -> list[NodeT]:
+    """Validate raw search nodes into `model` (IssueNode or PullRequestNode)."""
+    try:
+        return [model.model_validate(node) for node in connection.nodes]
+    except ValidationError as exc:
+        raise RpcError(-32002, f"unexpected GitHub search node: {exc}") from exc
+
+
+class Discovery(Generic[NodeT, ItemT]):
+    """Yield each matching item once per process, fetching result pages lazily.
+
+    The host starts a new extension process for every poll cycle, so the seen set only has
+    to hold for one cycle. Items already completed are filtered by the host.
+    """
+
+    def __init__(
+        self,
+        *,
+        fetch_page: Callable[[str | None], SearchConnection],
+        parse_page: Callable[[SearchConnection], list[NodeT]],
+        keep: Callable[[NodeT], bool],
+        to_item: Callable[[NodeT], ItemT],
+    ) -> None:
+        self._fetch_page = fetch_page
+        self._parse_page = parse_page
+        self._keep = keep
+        self._to_item = to_item
+        self._pending: deque[NodeT] = deque()
+        self._cursor: str | None = None
+        self._has_more = True
+        self._seen: set[str] = set()
+
+    def next_item(self) -> ItemT | None:
+        while True:
+            while self._pending:
+                node = self._pending.popleft()
+                if node.id in self._seen:
+                    continue
+                self._seen.add(node.id)
+                if self._keep(node):
+                    return self._to_item(node)
+            if not self._has_more:
+                return None
+            connection = self._fetch_page(self._cursor)
+            self._pending.extend(self._parse_page(connection))
+            self._has_more = connection.page_info.has_next_page
+            self._cursor = connection.page_info.end_cursor

curupira_plugins/github/filters.py

@@ -0,0 +1,233 @@
+"""Typed automation filters and their compilation into GitHub Search query strings."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+REPO_PATTERN = r"^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$"
+
+SearchState = Literal["open", "closed", "all"]
+SortOrder = Literal[
+    "created-asc",
+    "created-desc",
+    "updated-asc",
+    "updated-desc",
+    "comments-asc",
+    "comments-desc",
+]
+MergeState = Literal[
+    "BEHIND", "BLOCKED", "CLEAN", "DIRTY", "DRAFT", "HAS_HOOKS", "UNKNOWN", "UNSTABLE"
+]
+
+
+class SearchFilters(BaseModel):
+    """Filters shared by issue and pull-request automations."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    repo: str = Field(pattern=REPO_PATTERN)
+    state: SearchState = "open"
+    labels: list[str] | None = None
+    exclude_labels: list[str] | None = None
+    assignee: str | None = None
+    author: str | None = None
+    milestone: str | None = None
+    project: str | None = None
+    sort: SortOrder | None = None
+
+    @field_validator("labels", "exclude_labels", mode="before")
+    @classmethod
+    def _as_list(cls, value: object) -> object:
+        return [value] if isinstance(value, str) else value
+
+    @field_validator("repo")
+    @classmethod
+    def _reject_traversal(cls, value: str) -> str:
+        if any(part in {".", ".."} for part in value.split("/")):
+            raise ValueError("repo must not contain traversal segments")
+        return value
+
+    def shared_qualifiers(self) -> list[str]:
+        """Return the Search qualifiers that both issues and pull requests accept."""
+        qualifiers = [f"repo:{self.repo}", _STATE_QUALIFIERS[self.state]]
+        qualifiers += [_qualifier("label", label) for label in self.labels or []]
+        qualifiers += [f"-{_qualifier('label', label)}" for label in self.exclude_labels or []]
+        qualifiers += _assignee_qualifiers(self.assignee)
+        if self.author:
+            qualifiers.append(_qualifier("author", self.author))
+        if self.milestone:
+            qualifiers.append(_qualifier("milestone", self.milestone))
+        if self.project:
+            qualifiers.append(_qualifier("project", self.project))
+        return qualifiers
+
+
+class IssueFilters(SearchFilters):
+    """Filters for `github-issues` automations."""
+
+    linked_pull_request: bool | None = None
+
+    def search_query(self) -> str:
+        qualifiers = ["is:issue", *self.shared_qualifiers()]
+        if self.linked_pull_request is not None:
+            qualifiers.append("linked:pr" if self.linked_pull_request else "-linked:pr")
+        return _join(qualifiers, self.sort)
+
+
+class PullRequestFilters(SearchFilters):
+    """Filters for `github-pull-requests` automations."""
+
+    draft: bool | None = None
+    base: str | None = None
+    head: str | None = None
+    review: Literal["none", "required", "approved", "changes_requested"] | None = None
+    ci_status: Literal["success", "failure", "pending"] | None = None
+    linked_issue: bool | None = None
+    mergeable: bool | None = None
+    merge_state: list[MergeState] | None = None
+
+    @field_validator("merge_state", mode="before")
+    @classmethod
+    def _merge_state_as_list(cls, value: object) -> object:
+        return [value] if isinstance(value, str) else value
+
+    def search_query(self) -> str:
+        qualifiers = ["is:pr", *self.shared_qualifiers()]
+        if self.draft is not None:
+            qualifiers.append(f"draft:{str(self.draft).lower()}")
+        if self.base:
+            qualifiers.append(_qualifier("base", self.base))
+        if self.head:
+            qualifiers.append(_qualifier("head", self.head))
+        if self.review:
+            qualifiers.append(f"review:{self.review}")
+        if self.ci_status:
+            qualifiers.append(f"status:{self.ci_status}")
+        if self.linked_issue is not None:
+            qualifiers.append("linked:issue" if self.linked_issue else "-linked:issue")
+        return _join(qualifiers, self.sort)
+
+    def keeps(self, *, mergeable_state: str, merge_state_status: str) -> bool:
+        """Apply the GraphQL post-filters that Search cannot express."""
+        if self.mergeable is not None:
+            expected = "MERGEABLE" if self.mergeable else "CONFLICTING"
+            if mergeable_state != expected:
+                return False
+        return not self.merge_state or merge_state_status in self.merge_state
+
+
+_STATE_QUALIFIERS: dict[str, str] = {"open": "is:open", "closed": "is:closed", "all": ""}
+
+
+def _join(qualifiers: list[str], sort: str | None) -> str:
+    """Join qualifiers in a stable order, appending the sort qualifier last."""
+    parts = [part for part in qualifiers if part]
+    parts.append(f"sort:{sort or 'created-asc'}")
+    return " ".join(parts)
+
+
+def _assignee_qualifiers(assignee: str | None) -> list[str]:
+    if assignee is None:
+        return []
+    if assignee == "none":
+        return ["no:assignee"]
+    if assignee == "any":
+        return ["assignee:*"]
+    return [_qualifier("assignee", assignee)]
+
+
+def _qualifier(name: str, value: str) -> str:
+    """Render `name:value`, quoting values that contain whitespace or `"`, `:`, `,`."""
+    if any(char in value for char in ' \t\n":,'):
+        escaped = value.replace('"', '\\"')
+        return f'{name}:"{escaped}"'
+    return f"{name}:{value}"
+
+
+ProjectContent = Literal["all", "issue", "pull_request"]
+
+
+class ProjectFilters(BaseModel):
+    """Filters for `github-project-items`: one board, one or more Status columns."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    owner: str = Field(min_length=1, pattern=r"^[A-Za-z0-9_.-]+$")
+    project: int = Field(gt=0)
+    column: list[str] = Field(min_length=1)
+    status_field: str = "Status"
+    content: ProjectContent = "all"
+    repo: str | None = Field(default=None, pattern=REPO_PATTERN)
+    state: SearchState = "open"
+    labels: list[str] | None = None
+    exclude_labels: list[str] | None = None
+    assignee: str | None = None
+    author: str | None = None
+
+    @field_validator("column", "labels", "exclude_labels", mode="before")
+    @classmethod
+    def _as_list(cls, value: object) -> object:
+        return [value] if isinstance(value, str) else value
+
+    @field_validator("column")
+    @classmethod
+    def _column_not_blank(cls, value: list[str]) -> list[str]:
+        if any(not name.strip() for name in value):
+            raise ValueError("column names must not be blank")
+        return value
+
+    def view_filter(self) -> str | None:
+        """Projects view-filter text that makes GitHub return only the chosen columns.
+
+        Field names with whitespace are not safe in that syntax, so those fall back to the
+        client-side check in `keeps_column`.
+        """
+        if any(char.isspace() for char in self.status_field):
+            return None
+        values = ",".join(_view_value(name) for name in self.column)
+        return f"{self.status_field.lower()}:{values}"
+
+    def keeps_column(self, fields: dict[str, str]) -> bool:
+        wanted = {name.strip().casefold() for name in self.column}
+        by_field = {name.casefold(): value for name, value in fields.items()}
+        return by_field.get(self.status_field.casefold(), "").strip().casefold() in wanted
+
+    def keeps_content(
+        self,
+        *,
+        kind: str,
+        repo: str,
+        state: str,
+        labels: list[str],
+        assignees: list[str],
+        author: str,
+    ) -> bool:
+        """Apply the issue/pull-request filters that the view filter cannot express."""
+        if self.content != "all" and kind != self.content:
+            return False
+        if self.repo and repo.casefold() != self.repo.casefold():
+            return False
+        if self.state != "all" and state.casefold() != self.state:
+            return False
+        have = {label.casefold() for label in labels}
+        if any(label.casefold() not in have for label in self.labels or []):
+            return False
+        if any(label.casefold() in have for label in self.exclude_labels or []):
+            return False
+        if self.assignee is not None and not _assignee_matches(self.assignee, assignees):
+            return False
+        return self.author is None or author.casefold() == self.author.casefold()
+
+
+def _view_value(name: str) -> str:
+    return f'"{name}"' if any(char in name for char in ' ,"') else name
+
+
+def _assignee_matches(wanted: str, assignees: list[str]) -> bool:
+    if wanted == "none":
+        return not assignees
+    if wanted == "any":
+        return bool(assignees)
+    return wanted.casefold() in {login.casefold() for login in assignees}

curupira_plugins/github/models.py

@@ -0,0 +1,247 @@
+"""Typed models for GitHub GraphQL responses and the task items returned to the host."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+from pydantic.alias_generators import to_camel
+
+
+class _GraphQLModel(BaseModel):
+    """Parse GitHub's camelCase payloads and ignore fields the plugin does not use."""
+
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True, extra="ignore")
+
+
+class Actor(_GraphQLModel):
+    login: str
+
+
+class LabelName(_GraphQLModel):
+    name: str
+
+
+class LabelConnection(_GraphQLModel):
+    nodes: list[LabelName] = Field(default_factory=list)
+
+
+class Milestone(_GraphQLModel):
+    title: str
+
+
+class ActorConnection(_GraphQLModel):
+    nodes: list[Actor] = Field(default_factory=list)
+
+
+class LinkedReference(_GraphQLModel):
+    number: int
+    url: str
+
+
+class ReferenceConnection(_GraphQLModel):
+    nodes: list[LinkedReference] = Field(default_factory=list)
+
+
+class Node(_GraphQLModel):
+    id: str
+
+
+class IssueNode(Node):
+    number: int
+    title: str
+    body: str | None = None
+    url: str
+    state: str
+    author: Actor | None = None
+    labels: LabelConnection = Field(default_factory=LabelConnection)
+    assignees: ActorConnection = Field(default_factory=ActorConnection)
+    milestone: Milestone | None = None
+    created_at: str = ""
+    # Issue-only; absent from pull-request nodes.
+    state_reason: str | None = None
+
+
+class PullRequestNode(IssueNode):
+    head_ref_name: str
+    base_ref_name: str
+    head_ref_oid: str
+    is_draft: bool
+    mergeable: str
+    merge_state_status: str
+    changed_files: int = 0
+    additions: int = 0
+    deletions: int = 0
+    closing_issues_references: ReferenceConnection = Field(default_factory=ReferenceConnection)
+
+
+class PageInfo(_GraphQLModel):
+    has_next_page: bool
+    end_cursor: str | None = None
+
+
+class SearchConnection(_GraphQLModel):
+    page_info: PageInfo
+    nodes: list[Any] = Field(default_factory=list)
+
+
+class SearchData(_GraphQLModel):
+    search: SearchConnection
+
+
+class GraphQLErrorEntry(_GraphQLModel):
+    message: str
+
+
+class SearchResponse(_GraphQLModel):
+    data: SearchData | None = None
+    errors: list[GraphQLErrorEntry] = Field(default_factory=list)
+
+
+class IssueItem(BaseModel):
+    """Issue task item; field names match the `${issue_*}` prompt placeholders."""
+
+    model_config = ConfigDict(frozen=True)
+
+    id: str
+    title: str
+    url: str
+    repo: str
+    issue_number: int
+    issue_title: str
+    issue_body: str
+    issue_url: str
+    issue_state: str
+    issue_author: str
+    issue_labels: list[str]
+    issue_assignees: list[str]
+    issue_milestone: str
+    issue_created_at: str
+    issue_state_reason: str
+
+
+class PullRequestItem(BaseModel):
+    """Pull-request task item; field names match the `${pull_request_*}` prompt placeholders."""
+
+    model_config = ConfigDict(frozen=True)
+
+    id: str
+    title: str
+    url: str
+    repo: str
+    pull_request_number: int
+    pull_request_title: str
+    pull_request_body: str
+    pull_request_url: str
+    pull_request_is_draft: bool
+    pull_request_head_ref: str
+    pull_request_base_ref: str
+    pull_request_head_sha: str
+    pull_request_author: str
+    pull_request_labels: list[str]
+    pull_request_mergeable: str
+    pull_request_merge_state_status: str
+    pull_request_assignees: list[str]
+    pull_request_milestone: str
+    pull_request_created_at: str
+    pull_request_changed_files: int
+    pull_request_additions: int
+    pull_request_deletions: int
+    pull_request_closing_issues: list[str]
+
+
+class ProjectItemNode(Node):
+    """One Projects v2 item: its field values plus the issue or pull request it wraps."""
+
+    is_archived: bool = False
+    field_values: FieldValueConnection
+    content: dict[str, Any] | None = None
+
+
+class FieldRef(_GraphQLModel):
+    name: str = ""
+
+
+class FieldValue(_GraphQLModel):
+    """Any field value; only single-select, text, number, date and iteration carry data."""
+
+    field: FieldRef | None = None
+    name: str | None = None
+    text: str | None = None
+    number: float | None = None
+    date: str | None = None
+    title: str | None = None
+
+    def rendered(self) -> str | None:
+        for candidate in (self.name, self.text, self.date, self.title):
+            if candidate is not None:
+                return candidate
+        return None if self.number is None else f"{self.number:g}"
+
+
+class FieldValueConnection(_GraphQLModel):
+    nodes: list[FieldValue] = Field(default_factory=list)
+
+    def by_name(self) -> dict[str, str]:
+        """Map field name to rendered value, skipping untyped values (repository, PR links)."""
+        values: dict[str, str] = {}
+        for value in self.nodes:
+            rendered = value.rendered()
+            if value.field is not None and value.field.name and rendered is not None:
+                values[value.field.name] = rendered
+        return values
+
+
+ProjectItemNode.model_rebuild()
+
+
+ProjectItems = SearchConnection
+
+
+class ProjectV2(_GraphQLModel):
+    title: str
+    url: str
+    items: ProjectItems
+
+
+class ProjectOwner(_GraphQLModel):
+    project_v2: ProjectV2 | None = None
+
+
+class ProjectData(_GraphQLModel):
+    repository_owner: ProjectOwner | None = None
+
+
+class ProjectResponse(_GraphQLModel):
+    data: ProjectData | None = None
+    errors: list[GraphQLErrorEntry] = Field(default_factory=list)
+
+
+class ProjectItem(BaseModel):
+    """Project item task; field names match the `${item_*}` / `${project_*}` placeholders."""
+
+    model_config = ConfigDict(frozen=True)
+
+    id: str
+    title: str
+    url: str
+    repo: str
+    project_title: str
+    project_url: str
+    project_column: str
+    project_fields: str
+    item_type: str
+    item_number: int
+    item_title: str
+    item_body: str
+    item_url: str
+    item_state: str
+    item_author: str
+    item_labels: list[str]
+    item_assignees: list[str]
+    item_milestone: str
+    item_created_at: str
+    pull_request_head_ref: str
+    pull_request_base_ref: str
+    pull_request_head_sha: str
+    pull_request_is_draft: bool

curupira_plugins/github/triggers.py

@@ -0,0 +1,336 @@
+"""Official GitHub issues / pull-requests triggers.
+
+Discovery authenticates through `gh auth token`; no GitHub credentials are stored here.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from curupira_sdk import Curupira, RpcError
+from pydantic import ValidationError
+
+from curupira_plugins.github.client import Discovery, GitHubClient, GitHubCliToken, parse_nodes
+from curupira_plugins.github.filters import IssueFilters, ProjectFilters, PullRequestFilters
+from curupira_plugins.github.models import (
+    IssueItem,
+    IssueNode,
+    ProjectItem,
+    ProjectItemNode,
+    PullRequestItem,
+    PullRequestNode,
+    ReferenceConnection,
+)
+
+_CLIENT = GitHubClient(GitHubCliToken())
+# One discovery feed per distinct filter set, kept for the lifetime of this process.
+_FEEDS: dict[str, Discovery[Any, Any]] = {}
+
+
+def _validation_message(exc: ValidationError) -> str:
+    return "; ".join(
+        f"{'.'.join(str(part) for part in error['loc'])}: {error['msg']}" for error in exc.errors()
+    )
+
+
+def _check_issue_filters(kwargs: dict[str, object]) -> None:
+    try:
+        IssueFilters(**kwargs)  # type: ignore[arg-type]
+    except ValidationError as exc:
+        raise RpcError(-32003, _validation_message(exc)) from exc
+
+
+def _check_pull_request_filters(kwargs: dict[str, object]) -> None:
+    try:
+        PullRequestFilters(**kwargs)  # type: ignore[arg-type]
+    except ValidationError as exc:
+        raise RpcError(-32003, _validation_message(exc)) from exc
+
+
+def _reference_urls(references: ReferenceConnection) -> list[str]:
+    return [reference.url for reference in references.nodes]
+
+
+def _check_project_filters(kwargs: dict[str, object]) -> None:
+    try:
+        ProjectFilters(**kwargs)  # type: ignore[arg-type]
+    except ValidationError as exc:
+        raise RpcError(-32003, _validation_message(exc)) from exc
+
+
+def _issue_item(repo: str, node: IssueNode) -> IssueItem:
+    return IssueItem(
+        id=str(node.number),
+        title=node.title,
+        url=node.url,
+        repo=repo,
+        issue_number=node.number,
+        issue_title=node.title,
+        issue_body=node.body or "",
+        issue_url=node.url,
+        issue_state=node.state,
+        issue_author=node.author.login if node.author else "",
+        issue_labels=[label.name for label in node.labels.nodes],
+        issue_assignees=[actor.login for actor in node.assignees.nodes],
+        issue_milestone=node.milestone.title if node.milestone else "",
+        issue_created_at=node.created_at,
+        issue_state_reason=node.state_reason or "",
+    )
+
+
+def _pull_request_item(repo: str, node: PullRequestNode) -> PullRequestItem:
+    return PullRequestItem(
+        id=str(node.number),
+        title=node.title,
+        url=node.url,
+        repo=repo,
+        pull_request_number=node.number,
+        pull_request_title=node.title,
+        pull_request_body=node.body or "",
+        pull_request_url=node.url,
+        pull_request_is_draft=node.is_draft,
+        pull_request_head_ref=node.head_ref_name,
+        pull_request_base_ref=node.base_ref_name,
+        pull_request_head_sha=node.head_ref_oid,
+        pull_request_author=node.author.login if node.author else "",
+        pull_request_labels=[label.name for label in node.labels.nodes],
+        pull_request_mergeable=node.mergeable,
+        pull_request_merge_state_status=node.merge_state_status,
+        pull_request_assignees=[actor.login for actor in node.assignees.nodes],
+        pull_request_milestone=node.milestone.title if node.milestone else "",
+        pull_request_created_at=node.created_at,
+        pull_request_changed_files=node.changed_files,
+        pull_request_additions=node.additions,
+        pull_request_deletions=node.deletions,
+        pull_request_closing_issues=_reference_urls(node.closing_issues_references),
+    )
+
+
+def _issue_feed(filters: IssueFilters) -> Discovery[IssueNode, IssueItem]:
+    key = f"issue:{filters.model_dump_json()}"
+    feed = _FEEDS.get(key)
+    if feed is None:
+        query = filters.search_query()
+        feed = Discovery(
+            fetch_page=lambda after: _CLIENT.search(query, after=after),
+            parse_page=lambda connection: parse_nodes(connection, IssueNode),
+            keep=lambda node: True,
+            to_item=lambda node: _issue_item(filters.repo, node),
+        )
+        _FEEDS[key] = feed
+    return feed
+
+
+def _pull_request_feed(
+    filters: PullRequestFilters,
+) -> Discovery[PullRequestNode, PullRequestItem]:
+    key = f"pull_request:{filters.model_dump_json()}"
+    feed = _FEEDS.get(key)
+    if feed is None:
+        query = filters.search_query()
+        feed = Discovery(
+            fetch_page=lambda after: _CLIENT.search(query, after=after),
+            parse_page=lambda connection: parse_nodes(connection, PullRequestNode),
+            keep=lambda node: filters.keeps(
+                mergeable_state=node.mergeable,
+                merge_state_status=node.merge_state_status,
+            ),
+            to_item=lambda node: _pull_request_item(filters.repo, node),
+        )
+        _FEEDS[key] = feed
+    return feed
+
+
+def _project_item(
+    filters: ProjectFilters,
+    project_title: str,
+    project_url: str,
+    node: ProjectItemNode,
+) -> ProjectItem | None:
+    """Map one project item to a task, or None when it is not an eligible issue/PR."""
+    content = node.content or {}
+    kind = content.get("__typename")
+    if node.is_archived or kind not in {"Issue", "PullRequest"}:
+        return None  # draft items, redacted content, and archived cards carry no repository
+    fields = node.field_values.by_name()
+    if not filters.keeps_column(fields):
+        return None
+    repo = str(content.get("repository", {}).get("nameWithOwner", ""))
+    pull_request = PullRequestNode.model_validate(content) if kind == "PullRequest" else None
+    base = pull_request or IssueNode.model_validate(content)
+    labels = [label.name for label in base.labels.nodes]
+    assignees = [actor.login for actor in base.assignees.nodes]
+    author = base.author.login if base.author else ""
+    item_type = "pull_request" if pull_request else "issue"
+    if not filters.keeps_content(
+        kind=item_type,
+        repo=repo,
+        state=base.state,
+        labels=labels,
+        assignees=assignees,
+        author=author,
+    ):
+        return None
+    return ProjectItem(
+        id=f"{repo}#{base.number}",
+        title=base.title,
+        url=base.url,
+        repo=repo,
+        project_title=project_title,
+        project_url=project_url,
+        project_column=fields.get(filters.status_field, ""),
+        project_fields=json.dumps(fields, ensure_ascii=False, sort_keys=True),
+        item_type=item_type,
+        item_number=base.number,
+        item_title=base.title,
+        item_body=base.body or "",
+        item_url=base.url,
+        item_state=base.state,
+        item_author=author,
+        item_labels=labels,
+        item_assignees=assignees,
+        item_milestone=base.milestone.title if base.milestone else "",
+        item_created_at=base.created_at,
+        pull_request_head_ref=pull_request.head_ref_name if pull_request else "",
+        pull_request_base_ref=pull_request.base_ref_name if pull_request else "",
+        pull_request_head_sha=pull_request.head_ref_oid if pull_request else "",
+        pull_request_is_draft=pull_request.is_draft if pull_request else False,
+    )
+
+
+def _project_feed(filters: ProjectFilters) -> Discovery[ProjectItemNode, ProjectItem]:
+    key = f"project:{filters.model_dump_json()}"
+    feed = _FEEDS.get(key)
+    if feed is None:
+        view_filter = filters.view_filter()
+        # The project title and URL arrive with every page; keep the latest for `to_item`.
+        meta: dict[str, str] = {"title": "", "url": ""}
+
+        def fetch(after: str | None) -> Any:
+            project, items = _CLIENT.project_items(
+                filters.owner, filters.project, view_filter=view_filter, after=after
+            )
+            meta["title"], meta["url"] = project.title, project.url
+            return items
+
+        feed = Discovery(
+            fetch_page=fetch,
+            parse_page=lambda connection: parse_nodes(connection, ProjectItemNode),
+            keep=lambda node: _project_item(filters, meta["title"], meta["url"], node) is not None,
+            to_item=lambda node: _project_item(  # type: ignore[arg-type, return-value]
+                filters, meta["title"], meta["url"], node
+            ),
+        )
+        _FEEDS[key] = feed
+    return feed
+
+
+def github_issues(
+    repo: str,
+    labels: str | list[str] | None = None,
+    exclude_labels: str | list[str] | None = None,
+    state: str = "open",
+    assignee: str | None = None,
+    author: str | None = None,
+    milestone: str | None = None,
+    project: str | None = None,
+    linked_pull_request: bool | None = None,
+    sort: str | None = None,
+) -> IssueItem | None:
+    """Return the next eligible GitHub issue, or None when none are available."""
+    filters = IssueFilters(
+        repo=repo,
+        labels=labels,
+        exclude_labels=exclude_labels,
+        state=state,  # type: ignore[arg-type]
+        assignee=assignee,
+        author=author,
+        milestone=milestone,
+        project=project,
+        linked_pull_request=linked_pull_request,
+        sort=sort,  # type: ignore[arg-type]
+    )
+    return _issue_feed(filters).next_item()
+
+
+def github_pull_requests(
+    repo: str,
+    labels: str | list[str] | None = None,
+    exclude_labels: str | list[str] | None = None,
+    state: str = "open",
+    assignee: str | None = None,
+    author: str | None = None,
+    milestone: str | None = None,
+    project: str | None = None,
+    draft: bool | None = None,
+    base: str | None = None,
+    head: str | None = None,
+    review: str | None = None,
+    ci_status: str | None = None,
+    linked_issue: bool | None = None,
+    mergeable: bool | None = None,
+    merge_state: str | list[str] | None = None,
+    sort: str | None = None,
+) -> PullRequestItem | None:
+    """Return the next eligible GitHub pull request, or None when none are available."""
+    filters = PullRequestFilters(
+        repo=repo,
+        labels=labels,
+        exclude_labels=exclude_labels,
+        state=state,  # type: ignore[arg-type]
+        assignee=assignee,
+        author=author,
+        milestone=milestone,
+        project=project,
+        draft=draft,
+        base=base,
+        head=head,
+        review=review,  # type: ignore[arg-type]
+        ci_status=ci_status,  # type: ignore[arg-type]
+        linked_issue=linked_issue,
+        mergeable=mergeable,
+        merge_state=merge_state,  # type: ignore[arg-type]
+        sort=sort,  # type: ignore[arg-type]
+    )
+    return _pull_request_feed(filters).next_item()
+
+
+def github_project_items(
+    owner: str,
+    project: int,
+    column: str | list[str],
+    status_field: str = "Status",
+    content: str = "all",
+    repo: str | None = None,
+    state: str = "open",
+    labels: str | list[str] | None = None,
+    exclude_labels: str | list[str] | None = None,
+    assignee: str | None = None,
+    author: str | None = None,
+) -> ProjectItem | None:
+    """Return the next issue or pull request sitting in a GitHub Project column."""
+    filters = ProjectFilters(
+        owner=owner,
+        project=project,
+        column=column,
+        status_field=status_field,
+        content=content,  # type: ignore[arg-type]
+        repo=repo,
+        state=state,  # type: ignore[arg-type]
+        labels=labels,
+        exclude_labels=exclude_labels,
+        assignee=assignee,
+        author=author,
+    )
+    return _project_feed(filters).next_item()
+
+
+def register(app: Curupira) -> None:
+    """Register GitHub triggers on ``app``."""
+    app.trigger(github_issues)
+    app.trigger(github_pull_requests)
+    app.trigger(github_project_items)
+    app.param_check("github-project-items", _check_project_filters)
+    app.param_check("github-issues", _check_issue_filters)
+    app.param_check("github-pull-requests", _check_pull_request_filters)

curupira_plugins-0.1.0.dist-info/METADATA

@@ -0,0 +1,9 @@
+Metadata-Version: 2.5
+Name: curupira-plugins
+Version: 0.1.0
+Summary: Official Curupira trigger extensions (GitHub issues, pull requests, and Projects)
+Project-URL: Homepage, https://github.com/caipora-labs/curupira
+Project-URL: Repository, https://github.com/caipora-labs/curupira
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: curupira-sdk[pydantic]>=0.1.0.dev0

curupira_plugins-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+curupira_plugins/__init__.py,sha256=Umr4i7TagRBDdIOtob7ZvGLulwU15_ycQ3kefmvwktU,254
+curupira_plugins/__main__.py,sha256=Wt8FGMlzaGaAksZhbQzkIGdMzT72lO9nHSOImqX6mTg,1142
+curupira_plugins/github/__init__.py,sha256=ryXNkmrBCwwigyt0qzpwdkzwYdPlabvTimlkuPFxaL0,48
+curupira_plugins/github/client.py,sha256=6uKfO9Q68LWqAPWUXpl8tllTtyB6G14lRae9WghwcP0,10917
+curupira_plugins/github/filters.py,sha256=ajS_-UNGl6LYAX3nZVlq94O0HaCVy95v76pdszPWLjU,8616
+curupira_plugins/github/models.py,sha256=F2LYUmXpO6gnZyvK9A3sQyP_tZTOxsLYElHKyEZbSmY,6077
+curupira_plugins/github/triggers.py,sha256=Tk3k0fJUqIX434bFbW5s1o1SFdGbZRTViolaHRQIqmc,12030
+curupira_plugins-0.1.0.dist-info/METADATA,sha256=iC46A5QNioLSPBA1SHViDqmw3xhH5dr4Juc7k3W9xEM,379
+curupira_plugins-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+curupira_plugins-0.1.0.dist-info/entry_points.txt,sha256=65ycZitgY2NoI1K8vepqnHghBab4F4X-TX-9pJoYlZw,68
+curupira_plugins-0.1.0.dist-info/RECORD,,

curupira_plugins-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

curupira_plugins-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+curupira-plugins = curupira_plugins.__main__:main