hexastack-tools 0.2.0__tar.gz

hexastack_tools-0.2.0/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: hexastack-tools
+Version: 0.2.0
+Summary: Developer tooling and governance suite for Hexastack dogfooding
+Author: Richard West
+Author-email: Richard West <dopplereffect.us@gmail.com>
+License-Expression: Apache-2.0
+Requires-Dist: hexastack-cli
+Requires-Dist: hexastack-core
+Requires-Dist: hexastack-cqrs
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: rich>=13.8.0
+Requires-Dist: typer>=0.27.1
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# Hexastack Tools (`packages/hexastack_tools`)
+
+Developer tooling, repository governance, code-scanning analysis, and CI automation suite for the Hexastack monorepo.
+
+---
+
+## 📖 Complete Documentation & Usage
+
+For full CLI usage instructions and command examples, see the canonical [**USAGE Guide**](USAGE.md) or the [online developer documentation](file:///docs/tools.md).
+
+---
+
+## 🏛️ Architectural Intent
+
+`hexastack-tools` strictly dogfoods Hexastack's own hexagonal architecture with:
+- **`domain/`**: Pure data contracts (`PrSummary`, `CheckRunFinding`, `ReviewThread`, `OutputFormat`).
+- **`ports/`**: Decoupled port interfaces (`GitHubApiPort`).
+- **`adapters/`**: REST/GraphQL HTTP adapters (`GitHubHttpAdapter`) and multi-format presenters (`pr.py`, `checks.py`, `security.py`).
+- **`commands/`**: Clean Typer CLI entrypoints.
+- **`utils/`**: Shared monorepo workspace discovery and package graph resolvers.
+
+---
+
+## ⚙️ Output Presentation Modes
+
+All CLI commands support multi-format presenters:
+1. **`auto` (default)**: Renders interactive Rich tables/panels if connected to a terminal TTY, or automatically switches to plain TSV when output is piped to tools like `grep`, `awk`, `cut`, or `xargs`.
+2. **`rich`**: Colorized ANSI dashboards with status icons and panels.
+3. **`json`**: Structured JSON payload for CI integration or agent tooling.
+4. **`plain`**: Clean, newline- and tab-delimited (TSV) stream.
+
+---
+
+## 🛠️ Quick Command Reference
+
+| Command | Purpose |
+|---|---|
+| `uv run gh-pr-examine [pr]` | Full PR dashboard inspecting checks, review threads, failed CI logs, and conflicts. |
+| `uv run gh-pr-examine runs [branch]` | Lists recent workflow runs for a branch. |
+| `uv run gh-checks [pr/ref]` | Detailed status checks inspector. |
+| `uv run gh-security [pr]` | Review comments and bot discussion thread auditor. |
+| `uv run gh-code-scanning` | CodeQL SAST security alerts browser. |
+| `uv run check-test-parity` | Validates 1:1 mirroring between `src/` and `tests/unit/`. |
+| `uv run check-all-statements` | Validates `__all__` alphabetical sorting. |
+| `uv run fix-all-statements` | Automatically sorts and alphabetizes `__all__`. |
+| `uv run import-linter-run` | Validates package and hexagonal architecture layer boundaries. |
+| `uv run pypi-build` | Builds sdist and wheel packages across workspace. |
+| `uv run pypi-check` | Verifies build metadata and checks for PyPI release collisions. |
+| `uv run codeql-scan` | Runs local SARIF CodeQL SAST security scan. |
+
+For detailed syntax and flags, see [**USAGE.md**](USAGE.md).

hexastack_tools-0.2.0/README.md

@@ -0,0 +1,51 @@
+# Hexastack Tools (`packages/hexastack_tools`)
+
+Developer tooling, repository governance, code-scanning analysis, and CI automation suite for the Hexastack monorepo.
+
+---
+
+## 📖 Complete Documentation & Usage
+
+For full CLI usage instructions and command examples, see the canonical [**USAGE Guide**](USAGE.md) or the [online developer documentation](file:///docs/tools.md).
+
+---
+
+## 🏛️ Architectural Intent
+
+`hexastack-tools` strictly dogfoods Hexastack's own hexagonal architecture with:
+- **`domain/`**: Pure data contracts (`PrSummary`, `CheckRunFinding`, `ReviewThread`, `OutputFormat`).
+- **`ports/`**: Decoupled port interfaces (`GitHubApiPort`).
+- **`adapters/`**: REST/GraphQL HTTP adapters (`GitHubHttpAdapter`) and multi-format presenters (`pr.py`, `checks.py`, `security.py`).
+- **`commands/`**: Clean Typer CLI entrypoints.
+- **`utils/`**: Shared monorepo workspace discovery and package graph resolvers.
+
+---
+
+## ⚙️ Output Presentation Modes
+
+All CLI commands support multi-format presenters:
+1. **`auto` (default)**: Renders interactive Rich tables/panels if connected to a terminal TTY, or automatically switches to plain TSV when output is piped to tools like `grep`, `awk`, `cut`, or `xargs`.
+2. **`rich`**: Colorized ANSI dashboards with status icons and panels.
+3. **`json`**: Structured JSON payload for CI integration or agent tooling.
+4. **`plain`**: Clean, newline- and tab-delimited (TSV) stream.
+
+---
+
+## 🛠️ Quick Command Reference
+
+| Command | Purpose |
+|---|---|
+| `uv run gh-pr-examine [pr]` | Full PR dashboard inspecting checks, review threads, failed CI logs, and conflicts. |
+| `uv run gh-pr-examine runs [branch]` | Lists recent workflow runs for a branch. |
+| `uv run gh-checks [pr/ref]` | Detailed status checks inspector. |
+| `uv run gh-security [pr]` | Review comments and bot discussion thread auditor. |
+| `uv run gh-code-scanning` | CodeQL SAST security alerts browser. |
+| `uv run check-test-parity` | Validates 1:1 mirroring between `src/` and `tests/unit/`. |
+| `uv run check-all-statements` | Validates `__all__` alphabetical sorting. |
+| `uv run fix-all-statements` | Automatically sorts and alphabetizes `__all__`. |
+| `uv run import-linter-run` | Validates package and hexagonal architecture layer boundaries. |
+| `uv run pypi-build` | Builds sdist and wheel packages across workspace. |
+| `uv run pypi-check` | Verifies build metadata and checks for PyPI release collisions. |
+| `uv run codeql-scan` | Runs local SARIF CodeQL SAST security scan. |
+
+For detailed syntax and flags, see [**USAGE.md**](USAGE.md).

hexastack_tools-0.2.0/pyproject.toml

@@ -0,0 +1,72 @@
+[project]
+name = "hexastack-tools"
+version = "0.2.0"
+description = "Developer tooling and governance suite for Hexastack dogfooding"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.13"
+dependencies = [
+    "hexastack-cli",
+    "hexastack-core",
+    "hexastack-cqrs",
+    "httpx>=0.28.0",
+    "rich>=13.8.0",
+    "typer>=0.27.1",
+]
+
+[[project.authors]]
+name = "Richard West"
+email = "dopplereffect.us@gmail.com"
+
+[project.scripts]
+alphabetizer = "hexastack_tools.commands.rope:alphabetize_main"
+check-all-statements = "hexastack_tools.commands.all_statements:check_main"
+check-test-parity = "hexastack_tools.commands.test_parity:main"
+codeql-scan = "hexastack_tools.commands.codeql_scan:main"
+deptry-run = "hexastack_tools.commands.deptry:main"
+fix-all-statements = "hexastack_tools.commands.all_statements:fix_main"
+generate-usage-docs = "hexastack_tools.commands.usage_docs:main"
+gh-checks = "hexastack_tools.commands.checks:main"
+gh-code-scanning = "hexastack_tools.commands.code_scanning:main"
+gh-pr-examine = "hexastack_tools.commands.pr_examine:main"
+gh-security = "hexastack_tools.commands.security:main"
+import-linter-generate = "hexastack_tools.commands.import_linter:generate_main"
+import-linter-run = "hexastack_tools.commands.import_linter:run_main"
+inline-snapshot-update = "hexastack_tools.commands.inline_snapshot:main"
+mutmut-inspect = "hexastack_tools.commands.mutmut:inspect_main"
+mutmut-run = "hexastack_tools.commands.mutmut:run_main"
+pydeps-generate = "hexastack_tools.commands.pydeps:generate_main"
+pypi-build = "hexastack_tools.commands.pypi:build_main"
+pypi-check = "hexastack_tools.commands.pypi:check_main"
+pypi-publish = "hexastack_tools.commands.pypi:publish_main"
+pytest-archon-generate = "hexastack_tools.commands.pytest_runner:archon_generate_main"
+pytest-run = "hexastack_tools.commands.pytest_runner:run_main"
+rope-alphabetizer = "hexastack_tools.commands.rope:alphabetize_main"
+rope-run = "hexastack_tools.commands.rope:run_main"
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources.hexastack-cli]
+workspace = true
+
+[tool.uv.sources.hexastack-core]
+workspace = true
+
+[tool.uv.sources.hexastack-cqrs]
+workspace = true
+
+[tool.importlinter]
+root_packages = ["hexastack_tools"]
+
+[[tool.importlinter.contracts]]
+name = "Hexagonal architecture layer hierarchy"
+type = "layers"
+containers = ["hexastack_tools"]
+layers = [
+    "adapters",
+    "infra",
+    "ports",
+    "domain",
+]

hexastack_tools-0.2.0/pyproject.toml.orig

@@ -0,0 +1,68 @@
+[project]
+name = "hexastack-tools"
+version = "0.2.0"
+description = "Developer tooling and governance suite for Hexastack dogfooding"
+readme = "README.md"
+license = "Apache-2.0"
+authors = [
+    { name = "Richard West", email = "dopplereffect.us@gmail.com" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "hexastack-cli",
+    "hexastack-core",
+    "hexastack-cqrs",
+    "httpx>=0.28.0",
+    "rich>=13.8.0",
+    "typer>=0.27.1",
+]
+
+[project.scripts]
+alphabetizer = "hexastack_tools.commands.rope:alphabetize_main"
+check-all-statements = "hexastack_tools.commands.all_statements:check_main"
+check-test-parity = "hexastack_tools.commands.test_parity:main"
+codeql-scan = "hexastack_tools.commands.codeql_scan:main"
+deptry-run = "hexastack_tools.commands.deptry:main"
+fix-all-statements = "hexastack_tools.commands.all_statements:fix_main"
+generate-usage-docs = "hexastack_tools.commands.usage_docs:main"
+gh-checks = "hexastack_tools.commands.checks:main"
+
+gh-code-scanning = "hexastack_tools.commands.code_scanning:main"
+gh-pr-examine = "hexastack_tools.commands.pr_examine:main"
+gh-security = "hexastack_tools.commands.security:main"
+import-linter-generate = "hexastack_tools.commands.import_linter:generate_main"
+import-linter-run = "hexastack_tools.commands.import_linter:run_main"
+inline-snapshot-update = "hexastack_tools.commands.inline_snapshot:main"
+mutmut-inspect = "hexastack_tools.commands.mutmut:inspect_main"
+mutmut-run = "hexastack_tools.commands.mutmut:run_main"
+pydeps-generate = "hexastack_tools.commands.pydeps:generate_main"
+pypi-build = "hexastack_tools.commands.pypi:build_main"
+pypi-check = "hexastack_tools.commands.pypi:check_main"
+pypi-publish = "hexastack_tools.commands.pypi:publish_main"
+pytest-archon-generate = "hexastack_tools.commands.pytest_runner:archon_generate_main"
+pytest-run = "hexastack_tools.commands.pytest_runner:run_main"
+rope-alphabetizer = "hexastack_tools.commands.rope:alphabetize_main"
+rope-run = "hexastack_tools.commands.rope:run_main"
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources]
+hexastack-cli = { workspace = true }
+hexastack-core = { workspace = true }
+hexastack-cqrs = { workspace = true }
+
+[tool.importlinter]
+root_packages = ["hexastack_tools"]
+
+[[tool.importlinter.contracts]]
+name = "Hexagonal architecture layer hierarchy"
+type = "layers"
+containers = ["hexastack_tools"]
+layers = [
+    "adapters",
+    "infra",
+    "ports",
+    "domain",
+]

hexastack_tools-0.2.0/src/hexastack_tools/__init__.py

@@ -0,0 +1,3 @@
+"""Developer tooling, code scanning analysis, and CI automation suite for Hexastack."""
+
+__all__: list[str] = []

hexastack_tools-0.2.0/src/hexastack_tools/adapters/github/__init__.py

@@ -0,0 +1,11 @@
+"""GitHub adapter package exports."""
+
+from hexastack_tools.adapters.github.client import (
+    GitHubHttpAdapter,
+    get_github_token,
+)
+
+__all__ = [
+    "get_github_token",
+    "GitHubHttpAdapter",
+]

hexastack_tools-0.2.0/src/hexastack_tools/adapters/github/client.py

@@ -0,0 +1,398 @@
+"""Concrete adapter implementing GitHubApiPort using httpx and GitHub REST / GraphQL APIs."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from typing import Any
+
+import httpx
+
+from hexastack_tools.domain.github import (
+    CheckRunFinding,
+    PrSummary,
+    ReviewComment,
+    ReviewThread,
+    SecurityAlert,
+)
+from hexastack_tools.ports.github import GitHubApiPort
+
+
+def get_github_token() -> str | None:
+    """Retrieve GitHub token from environment or gh CLI."""
+    token = os.getenv("GITHUB_TOKEN") or os.getenv("GH_TOKEN")
+    if token:
+        return token.strip()
+
+    if shutil.which("gh"):
+        try:
+            res = subprocess.run(
+                ["gh", "auth", "token"],
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+            if res.returncode == 0 and res.stdout.strip():
+                return res.stdout.strip()
+        except (subprocess.SubprocessError, OSError):
+            return None
+
+    return None
+
+
+class GitHubHttpAdapter(GitHubApiPort):
+    """Adapter executing synchronous HTTP requests to GitHub REST and GraphQL APIs."""
+
+    def __init__(
+        self,
+        token: str | None = None,
+        owner: str = "TheTrueSCU",
+        repo: str = "hexastack",
+    ) -> None:
+        """Initialize GitHub HTTP client adapter.
+
+        Args:
+            token: Optional GitHub bearer token.
+            owner: Repository owner / organization.
+            repo: Repository name.
+        """
+        self.owner = owner
+        self.repo = repo
+        self.token = token or get_github_token()
+        headers = {
+            "Accept": "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+        }
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+
+        self._client = httpx.Client(
+            base_url="https://api.github.com",
+            headers=headers,
+            timeout=30.0,
+        )
+
+    def close(self) -> None:
+        """Close underlying httpx client."""
+        self._client.close()
+
+    def __enter__(self) -> GitHubHttpAdapter:
+        """Context manager enter."""
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        """Context manager exit."""
+        self.close()
+
+    def get_pr_summary(self, pr_number: int) -> PrSummary:
+        """Fetch full aggregate summary for a pull request."""
+        resp = self._client.get(f"/repos/{self.owner}/{self.repo}/pulls/{pr_number}")
+        resp.raise_for_status()
+        data = resp.json()
+
+        head_ref = data.get("head", {}).get("ref", "")
+        head_sha = data.get("head", {}).get("sha", "")
+
+        check_runs = self.get_check_runs(head_sha or head_ref)
+        review_threads = self.get_review_threads(pr_number)
+        alerts = self.get_code_scanning_alerts(ref=f"refs/pull/{pr_number}/merge")
+
+        # Fetch issue comments
+        comments_resp = self._client.get(
+            f"/repos/{self.owner}/{self.repo}/issues/{pr_number}/comments"
+        )
+        general_comments: list[ReviewComment] = []
+        if comments_resp.status_code == 200:
+            for c in comments_resp.json():
+                general_comments.append(
+                    ReviewComment(
+                        id=c.get("id", 0),
+                        author=c.get("user", {}).get("login", "unknown"),
+                        body=c.get("body", ""),
+                        created_at=c.get("created_at", ""),
+                        url=c.get("html_url", ""),
+                        is_review_comment=False,
+                    )
+                )
+
+        # Fetch inline review comments (including CodeQL and code reviews)
+        pull_comments_resp = self._client.get(
+            f"/repos/{self.owner}/{self.repo}/pulls/{pr_number}/comments"
+        )
+        if pull_comments_resp.status_code == 200:
+            for c in pull_comments_resp.json():
+                general_comments.append(
+                    ReviewComment(
+                        id=c.get("id", 0),
+                        author=c.get("user", {}).get("login", "unknown"),
+                        body=c.get("body", ""),
+                        created_at=c.get("created_at", ""),
+                        path=c.get("path"),
+                        line=c.get("line") or c.get("original_line"),
+                        url=c.get("html_url", ""),
+                        diff_hunk=c.get("diff_hunk"),
+                        is_review_comment=True,
+                    )
+                )
+
+        return PrSummary(
+            number=pr_number,
+            title=data.get("title", ""),
+            author=data.get("user", {}).get("login", "unknown"),
+            state=data.get("state", "open"),
+            mergeable=str(data.get("mergeable_state") or "unknown"),
+            is_draft=bool(data.get("draft", False)),
+            head_ref=head_ref,
+            base_ref=data.get("base", {}).get("ref", "main"),
+            html_url=data.get("html_url", ""),
+            check_runs=tuple(check_runs),
+            review_threads=tuple(review_threads),
+            security_alerts=tuple(alerts),
+            general_comments=tuple(general_comments),
+        )
+
+    def get_check_runs(self, ref: str) -> list[CheckRunFinding]:
+        """Fetch check runs and commit statuses for a ref."""
+        resp = self._client.get(
+            f"/repos/{self.owner}/{self.repo}/commits/{ref}/check-runs"
+        )
+        if resp.status_code != 200:
+            return []
+
+        runs = resp.json().get("check_runs", [])
+        findings: list[CheckRunFinding] = []
+        for r in runs:
+            findings.append(
+                CheckRunFinding(
+                    name=r.get("name", "unknown"),
+                    status=r.get("status", "unknown"),
+                    conclusion=r.get("conclusion") or "in_progress",
+                    details_url=r.get("html_url") or r.get("details_url", ""),
+                    workflow_name=r.get("workflow_name"),
+                    started_at=r.get("started_at"),
+                    completed_at=r.get("completed_at"),
+                )
+            )
+        return findings
+
+    def get_review_threads(self, pr_number: int) -> list[ReviewThread]:
+        """Fetch review discussion threads and conversation resolution state via GraphQL."""
+        query = """
+        query($owner: String!, $repo: String!, $pr: Int!) {
+          repository(owner: $owner, name: $repo) {
+            pullRequest(number: $pr) {
+              reviewThreads(first: 50) {
+                nodes {
+                  id
+                  isResolved
+                  resolvedBy { login }
+                  comments(first: 20) {
+                    nodes {
+                      id
+                      body
+                      author { login }
+                      path
+                      line
+                      createdAt
+                      url
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+        """
+        payload = {
+            "query": query,
+            "variables": {"owner": self.owner, "repo": self.repo, "pr": pr_number},
+        }
+        resp = self._client.post("/graphql", json=payload)
+        if resp.status_code != 200:
+            return []
+
+        data = resp.json()
+        threads_nodes = (
+            data.get("data", {})
+            .get("repository", {})
+            .get("pullRequest", {})
+            .get("reviewThreads", {})
+            .get("nodes", [])
+        )
+        results: list[ReviewThread] = []
+        for t in threads_nodes:
+            thread_id = t.get("id", "")
+            is_resolved = bool(t.get("isResolved", False))
+            resolved_by = (
+                t.get("resolvedBy", {}).get("login") if t.get("resolvedBy") else None
+            )
+
+            comments_list: list[ReviewComment] = []
+            for c in t.get("comments", {}).get("nodes", []):
+                comments_list.append(
+                    ReviewComment(
+                        id=c.get("id", ""),
+                        author=c.get("author", {}).get("login", "unknown"),
+                        body=c.get("body", ""),
+                        created_at=c.get("createdAt", ""),
+                        path=c.get("path"),
+                        line=c.get("line"),
+                        url=c.get("url"),
+                    )
+                )
+
+            results.append(
+                ReviewThread(
+                    id=thread_id,
+                    is_resolved=is_resolved,
+                    resolved_by=resolved_by,
+                    comments=tuple(comments_list),
+                )
+            )
+        return results
+
+    def get_code_scanning_alerts(
+        self,
+        ref: str | None = None,
+        state: str = "open",
+    ) -> list[SecurityAlert]:
+        """Fetch CodeQL code scanning alerts."""
+        params: dict[str, str] = {"per_page": "100"}
+        if state != "all":
+            params["state"] = state
+        if ref:
+            params["ref"] = ref
+
+        resp = self._client.get(
+            f"/repos/{self.owner}/{self.repo}/code-scanning/alerts",
+            params=params,
+        )
+        if resp.status_code != 200:
+            return []
+
+        raw_alerts = resp.json()
+        if not isinstance(raw_alerts, list):
+            return []
+
+        results: list[SecurityAlert] = []
+        for a in raw_alerts:
+            rule = a.get("rule", {})
+            inst = a.get("most_recent_instance", {})
+            loc = inst.get("location", {})
+            results.append(
+                SecurityAlert(
+                    number=a.get("number", 0),
+                    rule_id=rule.get("id", "unknown"),
+                    rule_description=rule.get("description", ""),
+                    severity=rule.get("severity", "unknown"),
+                    security_severity_level=rule.get("security_severity_level"),
+                    state=a.get("state", "open"),
+                    path=loc.get("path", "-"),
+                    start_line=loc.get("start_line"),
+                    end_line=loc.get("end_line"),
+                    message=inst.get("message", {}).get("text", ""),
+                    help_markdown=rule.get("help"),
+                )
+            )
+        return results
+
+    def get_single_alert(self, alert_number: int) -> SecurityAlert:
+        """Fetch full metadata for a single security alert."""
+        resp = self._client.get(
+            f"/repos/{self.owner}/{self.repo}/code-scanning/alerts/{alert_number}"
+        )
+        resp.raise_for_status()
+        a = resp.json()
+
+        rule = a.get("rule", {})
+        inst = a.get("most_recent_instance", {})
+        loc = inst.get("location", {})
+        return SecurityAlert(
+            number=a.get("number", alert_number),
+            rule_id=rule.get("id", "unknown"),
+            rule_description=rule.get("description", ""),
+            severity=rule.get("severity", "unknown"),
+            security_severity_level=rule.get("security_severity_level"),
+            state=a.get("state", "open"),
+            path=loc.get("path", "-"),
+            start_line=loc.get("start_line"),
+            end_line=loc.get("end_line"),
+            message=inst.get("message", {}).get("text", ""),
+            help_markdown=rule.get("help"),
+        )
+
+    def get_failed_run_logs(self, run_id: int | str) -> str | None:
+        """Fetch failed log output for a workflow run using gh CLI or REST API."""
+        if shutil.which("gh"):
+            try:
+                res = subprocess.run(
+                    ["gh", "run", "view", str(run_id), "--log-failed"],
+                    capture_output=True,
+                    text=True,
+                    check=False,
+                )
+                if res.returncode == 0 and res.stdout.strip():
+                    return res.stdout.strip()
+            except (subprocess.SubprocessError, OSError):
+                # Ignore subprocess failure when retrieving failed run logs via gh CLI
+                pass
+
+        return None
+
+    def get_workflow_runs(
+        self,
+        branch: str | None = None,
+        limit: int = 5,
+    ) -> list[dict[str, Any]]:
+        """Fetch recent workflow runs for a branch."""
+        if shutil.which("gh"):
+            cmd = [
+                "gh",
+                "run",
+                "list",
+                "--json",
+                "databaseId,name,conclusion,headSha,event,status,displayTitle,url",
+                "--limit",
+                str(limit),
+            ]
+            if branch:
+                cmd.extend(["--branch", branch])
+            try:
+                res = subprocess.run(cmd, capture_output=True, text=True, check=False)
+                if res.returncode == 0 and res.stdout.strip():
+                    import json
+
+                    return json.loads(res.stdout.strip())
+            except (subprocess.SubprocessError, OSError, json.JSONDecodeError):
+                # Fall back to GitHub REST API if local gh CLI execution fails
+                pass
+
+        params: dict[str, Any] = {"per_page": limit}
+        if branch:
+            params["branch"] = branch
+        resp = self._client.get(
+            f"/repos/{self.owner}/{self.repo}/actions/runs", params=params
+        )
+        if resp.status_code != 200:
+            return []
+        data = resp.json().get("workflow_runs", [])
+        return [
+            {
+                "databaseId": r.get("id"),
+                "name": r.get("name"),
+                "conclusion": r.get("conclusion") or "",
+                "headSha": r.get("head_sha", ""),
+                "event": r.get("event", ""),
+                "status": r.get("status", ""),
+                "displayTitle": r.get("display_title", ""),
+                "url": r.get("html_url", ""),
+            }
+            for r in data
+        ]
+
+
+__all__ = [
+    "get_github_token",
+    "GitHubHttpAdapter",
+]