sase-github 0.1.0__tar.gz

sase_github-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: "**/pyproject.toml"
+      - uses: extractions/setup-just@v2
+      - name: Set up Python
+        run: uv python install 3.12
+      - name: Install dependencies
+        run: just install
+      - name: Lint
+        run: just lint
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: "**/pyproject.toml"
+      - uses: extractions/setup-just@v2
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: just install
+      - name: Run tests
+        run: just test

sase_github-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: Publish to PyPI
+on:
+  push:
+    tags: ["v*"]
+permissions:
+  contents: read
+  id-token: write # for trusted publishing
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv python install 3.12
+      - name: Build package
+        run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

sase_github-0.1.0/CLAUDE.md

@@ -0,0 +1,24 @@
+# sase-github - Agent Instructions
+
+## Overview
+GitHub VCS plugin for sase. Provides GitHubPlugin (PR creation, gh CLI integration)
+and GitHub-related xprompts (#gh, #pr, #new_pr_desc).
+
+## Build & Run
+```bash
+just install    # Install in editable mode with dev deps
+just lint       # ruff + mypy
+just fmt        # Auto-format
+just test       # pytest
+just check      # lint + test
+```
+
+## Architecture
+- `src/sase_github/plugin.py` — GitHubPlugin class (extends `sase.vcs_provider.plugins._git_common.GitCommon`)
+- `src/sase_github/xprompts/` — GitHub workflow YAML files discovered via `sase_xprompts` entry point
+- Depends on `sase>=0.1.0` for base classes, hookspec, and script modules
+
+## Code Conventions
+- Absolute imports: `from sase_github.plugin import GitHubPlugin`
+- Target Python 3.12+
+- Follow ruff rules matching sase core

sase_github-0.1.0/Justfile

@@ -0,0 +1,32 @@
+# sase-github task runner
+
+venv_dir := ".venv"
+venv_bin := venv_dir / "bin"
+
+default:
+    @just --list
+
+_setup:
+    @[ -x {{ venv_bin }}/python ] || (uv venv {{ venv_dir }} && uv pip install -e ".[dev]")
+
+install: _setup
+    uv pip install -e ".[dev]"
+
+lint: _setup
+    {{ venv_bin }}/ruff check src/ tests/
+    {{ venv_bin }}/mypy
+
+fmt: _setup
+    {{ venv_bin }}/ruff format src/ tests/
+    {{ venv_bin }}/ruff check --fix src/ tests/
+
+test *args: _setup
+    {{ venv_bin }}/pytest {{ args }}
+
+check: lint test
+
+clean:
+    rm -rf build/ dist/ *.egg-info src/*.egg-info .mypy_cache/ .ruff_cache/ .pytest_cache/
+
+build: _setup
+    {{ venv_bin }}/python -m build

sase_github-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bryan Bugyi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sase_github-0.1.0/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: sase-github
+Version: 0.1.0
+Summary: GitHub VCS plugin for sase
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: sase>=0.1.0
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest-mock; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'

sase_github-0.1.0/README.md

@@ -0,0 +1,82 @@
+# sase-github — GitHub VCS Plugin for sase
+
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![mypy](https://img.shields.io/badge/type_checker-mypy-blue.svg)](https://mypy-lang.org/)
+[![pytest](https://img.shields.io/badge/tests-pytest-blue.svg)](https://docs.pytest.org/)
+
+## Overview
+
+**sase-github** is a plugin for [sase](https://github.com/bbugyi200/sase) that adds GitHub-specific VCS support. It
+provides the `GitHubPlugin` VCS provider for GitHub-hosted repositories, integrating with the `gh` CLI for pull request
+creation and management, along with GitHub-specific xprompt workflows.
+
+## Installation
+
+```bash
+pip install sase-github
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv pip install sase-github
+```
+
+Requires `sase>=0.1.0` as a dependency (installed automatically).
+
+## What's Included
+
+### VCS Provider
+
+- **GitHubPlugin** — GitHub VCS provider that extends `GitCommon` with `gh` CLI integration for PR workflows
+
+### XPrompts
+
+| XPrompt         | Description                                |
+| --------------- | ------------------------------------------ |
+| `#gh`           | GitHub-specific operations and workflows   |
+| `#pr`           | Pull request creation and management       |
+| `#new_pr_desc`  | Generate PR descriptions from commit diffs |
+
+## How It Works
+
+sase-github uses Python [entry points](https://packaging.python.org/en/latest/specifications/entry-points/) to register
+itself with sase core:
+
+- **`sase_vcs`** — Registers `GitHubPlugin` as the `github` VCS provider
+- **`sase_xprompts`** — Makes GitHub xprompts discoverable via plugin discovery
+
+When sase detects a GitHub-hosted repository (via `gh` CLI), it automatically loads `GitHubPlugin` to handle VCS
+operations like PR creation, branch management, and commit workflows.
+
+## Requirements
+
+- Python 3.12+
+- [sase](https://github.com/bbugyi200/sase) >= 0.1.0
+- [gh](https://cli.github.com/) CLI (for GitHub API operations)
+
+## Development
+
+```bash
+just install    # Install in editable mode with dev deps
+just fmt        # Auto-format code
+just lint       # Run ruff + mypy
+just test       # Run tests
+just check      # All checks (lint + test)
+```
+
+## Project Structure
+
+```
+src/sase_github/
+├── __init__.py        # Package exports
+├── plugin.py          # GitHubPlugin implementation
+└── xprompts/
+    ├── gh.yml         # GitHub operations workflow
+    ├── pr.yml         # PR creation workflow
+    └── new_pr_desc.yml # PR description generation
+```
+
+## License
+
+MIT

sase_github-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sase-github"
+version = "0.1.0"
+description = "GitHub VCS plugin for sase"
+requires-python = ">=3.12"
+license = "MIT"
+dependencies = ["sase>=0.1.0"]
+
+[project.optional-dependencies]
+dev = [
+    "ruff",
+    "mypy",
+    "pytest",
+    "pytest-cov",
+    "pytest-mock",
+]
+
+[project.entry-points."sase_vcs"]
+github = "sase_github.plugin:GitHubPlugin"
+
+[project.entry-points."sase_xprompts"]
+sase_github = "sase_github"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sase_github"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 88
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "B", "C4", "UP"]
+ignore = ["E501", "W291", "F401", "F821", "B007"]
+
+[tool.mypy]
+files = ["src"]
+mypy_path = ["src"]
+python_version = "3.12"
+check_untyped_defs = true
+disallow_incomplete_defs = true
+disallow_untyped_defs = true
+ignore_missing_imports = false
+
+[[tool.mypy.overrides]]
+module = ["sase.*"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src", "tests"]
+addopts = [
+    "--import-mode=importlib",
+    "--strict-markers",
+    "--strict-config",
+    "-v",
+]

sase_github-0.1.0/src/sase_github/__init__.py

@@ -0,0 +1,5 @@
+"""sase-github: GitHub VCS plugin for sase."""
+
+from sase_github.plugin import GitHubPlugin
+
+__all__ = ["GitHubPlugin"]

sase_github-0.1.0/src/sase_github/plugin.py

@@ -0,0 +1,44 @@
+"""GitHub VCS plugin implementation.
+
+Handles git repositories hosted on GitHub (or similar hosted services).
+Inherits shared git operations from :class:`GitCommon` and adds
+GitHub-specific methods (``mail`` with PR creation, ``get_cl_number``
+and ``get_change_url`` via ``gh`` CLI).
+"""
+
+from sase.vcs_provider._hookspec import hookimpl
+from sase.vcs_provider.plugins._git_common import GitCommon
+
+
+class GitHubPlugin(GitCommon):
+    """Pluggy plugin for GitHub-hosted git repositories."""
+
+    @hookimpl
+    def vcs_get_change_url(self, cwd: str) -> tuple[bool, str | None]:
+        out = self._run(["gh", "pr", "view", "--json", "url", "-q", ".url"], cwd)
+        if out.success:
+            url = out.stdout.strip()
+            return (True, url) if url else (True, None)
+        return (True, None)
+
+    @hookimpl
+    def vcs_get_cl_number(self, cwd: str) -> tuple[bool, str | None]:
+        out = self._run(["gh", "pr", "view", "--json", "number", "-q", ".number"], cwd)
+        if out.success:
+            number = out.stdout.strip()
+            return (True, number) if number else (True, None)
+        return (True, None)
+
+    @hookimpl
+    def vcs_mail(self, revision: str, cwd: str) -> tuple[bool, str | None]:
+        out = self._run(["git", "push", "-u", "origin", revision], cwd)
+        if not out.success:
+            return self._to_result(out, "git push")
+        pr_check = self._run(
+            ["gh", "pr", "view", "--json", "number", "-q", ".number"], cwd
+        )
+        if not pr_check.success:
+            pr_create = self._run(["gh", "pr", "create", "--fill"], cwd)
+            if not pr_create.success:
+                return self._to_result(pr_create, "gh pr create")
+        return (True, None)

sase_github-0.1.0/src/sase_github/xprompts/gh.yml

@@ -0,0 +1,87 @@
+wraps_all: true
+
+input:
+  - name: gh_ref
+    type: word
+  - name: n
+    type: int
+    default: null
+  - name: release
+    type: bool
+    default: true
+
+steps:
+  - name: setup
+    python: |
+      from sase.scripts.gh_setup import main
+      main(
+          gh_ref={{ gh_ref | tojson }},
+          n={{ n | tojson }},
+          release={{ release | tojson }},
+      )
+    output:
+      project_name: word
+      project_file: path
+      workspace_dir: path
+      workspace_num: int
+      checkout_target: word
+      primary_workspace_dir: path
+      should_release: bool
+
+  - name: prepare
+    bash: |
+      # Save diff backup if workspace is dirty
+      if ! git diff --quiet HEAD 2>/dev/null; then
+        git diff HEAD > "/tmp/gh-workspace-backup-$(date +%s).patch"
+      fi
+      git checkout . && git clean -fd
+      git fetch --quiet
+      git pull --rebase --quiet 2>&1 || true
+      echo "head_before=$(git rev-parse HEAD)"
+      echo "success=true"
+    output: { success: bool, head_before: word }
+
+  - name: inject
+    prompt_part: ""
+
+  - name: release
+    if: "{{ setup.should_release }}"
+    python: |
+      from sase.running_field import release_workspace
+
+      release_workspace(
+          {{ setup.project_file | tojson }},
+          {{ setup.workspace_num }},
+          f"gh-{{ gh_ref }}",
+          {{ gh_ref | tojson }} if "/" not in {{ gh_ref | tojson }} else None,
+      )
+      print("released=true")
+    output: { released: bool }
+
+  - name: diff
+    bash: |
+      head_before="{{ prepare.head_before }}"
+      if [ -z "$head_before" ]; then
+        exit 0
+      fi
+      head_now=$(git rev-parse HEAD)
+      diff_file=$(mktemp /tmp/sase-gh-XXXXXX.diff)
+      if [ "$head_now" != "$head_before" ]; then
+        # Commits were made — show only the last commit's diff
+        git diff HEAD~1 HEAD > "$diff_file" 2>/dev/null
+        commit_msg=$(git log -1 --format='%s' HEAD)
+        echo "meta_commit_message=$commit_msg"
+      else
+        # No commits — show uncommitted changes
+        git diff HEAD > "$diff_file" 2>/dev/null
+        git ls-files --others --exclude-standard -z 2>/dev/null \
+          | while IFS= read -r -d '' f; do
+              git diff --no-index /dev/null "$f" 2>/dev/null
+            done >> "$diff_file"
+      fi
+      if [ -s "$diff_file" ]; then
+        echo "diff_path=$diff_file"
+      else
+        rm -f "$diff_file"
+      fi
+    output: { diff_path: path, meta_commit_message: line }

sase_github-0.1.0/src/sase_github/xprompts/new_pr_desc.yml

@@ -0,0 +1,64 @@
+input:
+  - name: name
+    type: word
+
+steps:
+  - name: get_context
+    python: |
+      from sase.scripts.new_pr_desc_get_context import main
+      main(name={{ name | tojson }})
+    output:
+      error: line
+      description: line
+      diff_file: path
+      commits: text
+      workspace_dir: path
+      default_branch: word
+      branch_name: word
+
+  - name: generate
+    if: "{{ not get_context.error }}"
+    agent: |
+      Generate a PR title and body for the following changes.
+
+      ## ChangeSpec Description
+      {{ get_context.description }}
+
+      ## Commits
+      {{ get_context.commits }}
+
+      ## Diff
+      @{{ get_context.diff_file }}
+
+      ## Instructions
+      - PR title: Use conventional commit format (e.g., "feat: ...", "fix: ..."), under 72 characters
+      - PR body: Start with "## Summary" followed by 1-3 bullet points
+
+      Output EXACTLY in this format (no extra text):
+      TITLE: <your title here>
+      BODY:
+      <your body here>
+
+  - name: apply
+    if: "{{ not get_context.error }}"
+    bash: |
+      # Check if PR exists for this branch
+      PR_NUMBER=$(gh pr view "{{ get_context.branch_name }}" --json number --jq '.number' 2>/dev/null || echo "")
+      if [ -z "$PR_NUMBER" ]; then
+        echo "applied=false"
+        echo "No existing PR found for branch {{ get_context.branch_name }}"
+        exit 0
+      fi
+
+      # Extract title and body from response
+      RESPONSE="{{ _response }}"
+      TITLE=$(echo "$RESPONSE" | grep -m1 '^TITLE: ' | sed 's/^TITLE: //')
+      BODY=$(echo "$RESPONSE" | sed -n '/^BODY:$/,$ p' | tail -n +2)
+
+      if [ -n "$TITLE" ] && [ -n "$BODY" ]; then
+        gh pr edit "$PR_NUMBER" --title "$TITLE" --body "$BODY" 2>/dev/null && echo "applied=true" || echo "applied=false"
+      else
+        echo "applied=false"
+        echo "Could not parse title/body from response"
+      fi
+    output: { applied: bool }

sase_github-0.1.0/src/sase_github/xprompts/pr.yml

@@ -0,0 +1,88 @@
+input:
+  - name: name
+    type: word
+
+steps:
+  - name: create_branch
+    bash: |
+      BRANCH="{{ name }}"
+      git checkout -b "$BRANCH" 2>&1
+      git push -u origin "$BRANCH" 2>&1
+      echo "branch_name=$BRANCH"
+      echo "meta_changespec=$BRANCH"
+    output:
+      branch_name: word
+
+  - name: inject
+    prompt_part: ""
+
+  - name: create_changespec
+    hidden: true
+    python: |
+      from sase.scripts.pr_create_changespec import main
+      main(
+          name={{ name | tojson }},
+          prompt={{ _prompt | tojson }},
+          response={{ _response | tojson }},
+      )
+    output:
+      success: bool
+      cl_name: word
+      project_file: path
+      default_branch: word
+
+  - name: create_pr
+    hidden: true
+    if: "{{ create_changespec.success | default(false) }}"
+    bash: |
+      BRANCH="{{ create_branch.branch_name }}"
+      DEFAULT_BRANCH="{{ create_changespec.default_branch }}"
+
+      # Check for existing PR first
+      EXISTING_URL=$(gh pr view "$BRANCH" --json url --jq '.url' 2>/dev/null || echo "")
+      if [ -n "$EXISTING_URL" ]; then
+        echo "pr_url=$EXISTING_URL"
+        echo "success=true"
+        exit 0
+      fi
+
+      # Get PR title from first commit
+      PR_TITLE=$(git log --format='%s' "origin/$DEFAULT_BRANCH".."$BRANCH" 2>/dev/null | tail -1)
+      if [ -z "$PR_TITLE" ]; then
+        PR_TITLE="Agent changes on branch $BRANCH"
+      fi
+
+      PR_URL=$(gh pr create \
+        --base "$DEFAULT_BRANCH" \
+        --head "$BRANCH" \
+        --title "$PR_TITLE" \
+        --body "Automated PR from sase." 2>&1) || true
+
+      if echo "$PR_URL" | grep -q "^http"; then
+        echo "pr_url=$PR_URL"
+        echo "success=true"
+      else
+        echo "pr_url="
+        echo "success=false"
+        echo "Error: $PR_URL" >&2
+      fi
+    output: { pr_url: line, success: bool }
+
+  - name: update_cl
+    hidden: true
+    if: "{{ create_pr.success | default(false) }}"
+    python: |
+      from sase.status_state_machine import update_changespec_cl_atomic
+
+      project_file = {{ create_changespec.project_file | tojson }}
+      cl_name = {{ create_changespec.cl_name | tojson }}
+      pr_url = {{ create_pr.pr_url | tojson }}
+
+      if pr_url and pr_url.startswith("http"):
+          update_changespec_cl_atomic(project_file, cl_name, pr_url)
+          print("updated=true")
+          print(f"pr_url={pr_url}")
+      else:
+          print("updated=false")
+          print(f"pr_url={pr_url}")
+    output: { updated: bool, pr_url: line }

sase_github-0.1.0/tests/test_github_plugin.py

@@ -0,0 +1,308 @@
+"""Tests for the GitHub pluggy plugin.
+
+Verifies that :class:`GitHubPlugin` works correctly when routed through
+:class:`VCSPluginManager`.
+"""
+
+from unittest.mock import MagicMock, patch
+
+import pluggy
+import pytest
+from sase.vcs_provider._base import VCSProvider
+from sase.vcs_provider._command_runner import CommandRunner
+from sase.vcs_provider._hookspec import VCSHookSpec
+from sase.vcs_provider._plugin_manager import VCSPluginManager
+from sase_github.plugin import GitHubPlugin
+
+_MOCK_TARGET = "sase.vcs_provider._command_runner.subprocess.run"
+
+
+@pytest.fixture
+def github_provider() -> VCSPluginManager:
+    """Create a VCSPluginManager backed by GitHubPlugin."""
+    pm = pluggy.PluginManager("sase_vcs")
+    pm.add_hookspecs(VCSHookSpec)
+    pm.register(GitHubPlugin())
+    return VCSPluginManager(pm)
+
+
+# === Tests for isinstance / type checks ===
+
+
+def test_github_plugin_provider_is_vcs_provider(
+    github_provider: VCSPluginManager,
+) -> None:
+    """The plugin-backed provider is a VCSProvider."""
+    assert isinstance(github_provider, VCSProvider)
+
+
+def test_github_plugin_is_command_runner() -> None:
+    """GitHubPlugin inherits from CommandRunner."""
+    plugin = GitHubPlugin()
+    assert isinstance(plugin, CommandRunner)
+
+
+# === Tests for core git operations via plugin ===
+
+
+@patch(_MOCK_TARGET)
+def test_plugin_checkout_success(
+    mock_run: MagicMock, github_provider: VCSPluginManager
+) -> None:
+    mock_run.return_value = MagicMock(returncode=0, stdout="", stderr="")
+    success, error = github_provider.checkout("main", "/workspace")
+
+    assert success is True
+    assert error is None
+    assert mock_run.call_args[0][0] == ["git", "checkout", "main"]
+
+
+@patch(_MOCK_TARGET)
+def test_plugin_diff_success(
+    mock_run: MagicMock, github_provider: VCSPluginManager
+) -> None:
+    mock_run.return_value = MagicMock(returncode=0, stdout="diff output", stderr="")
+    success, text = github_provider.diff("/workspace")
+
+    assert success is True
+    assert text == "diff output"
+
+
+@patch(_MOCK_TARGET)
+def test_plugin_add_remove(
+    mock_run: MagicMock, github_provider: VCSPluginManager
+) -> None:
+    mock_run.return_value = MagicMock(returncode=0, stdout="", stderr="")
+    success, error = github_provider.add_remove("/workspace")
+
+    assert success is True
+    assert error is None
+    assert mock_run.call_args[0][0] == ["git", "add", "-A"]
+
+
+@patch(_MOCK_TARGET)
+def test_plugin_commit(mock_run: MagicMock, github_provider: VCSPluginManager) -> None:
+    mock_run.return_value = MagicMock(returncode=0, stdout="", stderr="")
+    success, error = github_provider.commit("feature", "/tmp/msg.txt", "/workspace")
+
+    assert success is True
+    assert error is None
+
+
+# === Tests for GitHub-specific operations ===
+
+
+@patch(_MOCK_TARGET)
+def test_plugin_get_change_url_with_pr(
+    mock_run: MagicMock, github_provider: VCSPluginManager
+) -> None:
+    mock_run.return_value = MagicMock(
+        returncode=0, stdout="https://github.com/user/repo/pull/42\n", stderr=""
+    )
+    success, url = github_provider.get_change_url("/workspace")
+
+    assert success is True
+    assert url == "https://github.com/user/repo/pull/42"
+
+
+@patch(_MOCK_TARGET)
+def test_plugin_get_change_url_no_pr(
+    mock_run: MagicMock, github_provider: VCSPluginManager
+) -> None:
+    mock_run.return_value = MagicMock(returncode=1, stdout="", stderr="no PR")
+    success, url = github_provider.get_change_url("/workspace")
+
+    assert success is True
+    assert url is None
+
+
+@patch(_MOCK_TARGET)
+def test_plugin_get_cl_number_with_pr(
+    mock_run: MagicMock, github_provider: VCSPluginManager
+) -> None:
+    mock_run.return_value = MagicMock(returncode=0, stdout="42\n", stderr="")
+    success, number = github_provider.get_cl_number("/workspace")
+
+    assert success is True
+    assert number == "42"
+
+
+@patch(_MOCK_TARGET)
+def test_plugin_get_cl_number_no_pr(
+    mock_run: MagicMock, github_provider: VCSPluginManager
+) -> None:
+    mock_run.return_value = MagicMock(returncode=1, stdout="", stderr="no PR")
+    success, number = github_provider.get_cl_number("/workspace")
+
+    assert success is True
+    assert number is None
+
+
+@patch(_MOCK_TARGET)
+def test_plugin_mail_creates_pr(
+    mock_run: MagicMock, github_provider: VCSPluginManager
+) -> None:
+    """mail pushes and creates a PR when none exists."""
+    # First call: git push (success)
+    # Second call: gh pr view (fail = no existing PR)
+    # Third call: gh pr create (success)
+    mock_run.side_effect = [
+        MagicMock(returncode=0, stdout="", stderr=""),
+        MagicMock(returncode=1, stdout="", stderr="no PR"),
+        MagicMock(returncode=0, stdout="", stderr=""),
+    ]
+    success, error = github_provider.mail("feature-branch", "/workspace")
+
+    assert success is True
+    assert error is None
+    assert mock_run.call_count == 3
+    assert mock_run.call_args_list[0][0][0] == [
+        "git",
+        "push",
+        "-u",
+        "origin",
+        "feature-branch",
+    ]
+    assert mock_run.call_args_list[2][0][0] == ["gh", "pr", "create", "--fill"]
+
+
+@patch(_MOCK_TARGET)
+def test_plugin_mail_existing_pr(
+    mock_run: MagicMock, github_provider: VCSPluginManager
+) -> None:
+    """mail pushes but skips PR creation when PR already exists."""
+    mock_run.side_effect = [
+        MagicMock(returncode=0, stdout="", stderr=""),  # git push
+        MagicMock(returncode=0, stdout="42\n", stderr=""),  # gh pr view (PR exists)
+    ]
+    success, error = github_provider.mail("feature-branch", "/workspace")
+
+    assert success is True
+    assert error is None
+    assert mock_run.call_count == 2
+
+
+# === Tests for prepare_description_for_reword ===
+
+
+def test_plugin_prepare_description_passthrough(
+    github_provider: VCSPluginManager,
+) -> None:
+    """Git plugins pass description through unchanged."""
+    result = github_provider.prepare_description_for_reword("hello\nworld")
+    assert result == "hello\nworld"
+
+
+# === Direct plugin method tests (GitHub-specific) ===
+
+
+@patch(_MOCK_TARGET)
+def test_direct_get_change_url_with_pr(mock_run: MagicMock) -> None:
+    """Test GitHubPlugin.vcs_get_change_url when PR exists."""
+    mock_run.return_value = MagicMock(
+        returncode=0,
+        stdout="https://github.com/user/repo/pull/42\n",
+        stderr="",
+    )
+
+    plugin = GitHubPlugin()
+    success, url = plugin.vcs_get_change_url("/workspace")
+
+    assert success is True
+    assert url == "https://github.com/user/repo/pull/42"
+
+
+@patch(_MOCK_TARGET)
+def test_direct_get_change_url_no_pr(mock_run: MagicMock) -> None:
+    """Test GitHubPlugin.vcs_get_change_url when no PR exists."""
+    mock_run.return_value = MagicMock(
+        returncode=1, stdout="", stderr="no pull requests found"
+    )
+
+    plugin = GitHubPlugin()
+    success, url = plugin.vcs_get_change_url("/workspace")
+
+    assert success is True
+    assert url is None
+
+
+@patch(_MOCK_TARGET)
+def test_direct_get_cl_number_with_pr(mock_run: MagicMock) -> None:
+    """Test GitHubPlugin.vcs_get_cl_number when PR exists."""
+    mock_run.return_value = MagicMock(returncode=0, stdout="42\n", stderr="")
+
+    plugin = GitHubPlugin()
+    success, number = plugin.vcs_get_cl_number("/workspace")
+
+    assert success is True
+    assert number == "42"
+
+
+@patch(_MOCK_TARGET)
+def test_direct_get_cl_number_no_pr(mock_run: MagicMock) -> None:
+    """Test GitHubPlugin.vcs_get_cl_number when no PR exists."""
+    mock_run.return_value = MagicMock(
+        returncode=1, stdout="", stderr="no pull requests found"
+    )
+
+    plugin = GitHubPlugin()
+    success, number = plugin.vcs_get_cl_number("/workspace")
+
+    assert success is True
+    assert number is None
+
+
+@patch(_MOCK_TARGET)
+def test_direct_mail_push_and_create_pr(mock_run: MagicMock) -> None:
+    """Test GitHubPlugin.vcs_mail pushes and creates PR when none exists."""
+    mock_run.side_effect = [
+        MagicMock(returncode=0, stdout="", stderr=""),  # git push
+        MagicMock(returncode=1, stdout="", stderr="no PR"),  # gh pr view (no PR)
+        MagicMock(returncode=0, stdout="", stderr=""),  # gh pr create
+    ]
+
+    plugin = GitHubPlugin()
+    success, error = plugin.vcs_mail("feature-branch", "/workspace")
+
+    assert success is True
+    assert error is None
+    assert mock_run.call_count == 3
+    assert mock_run.call_args_list[0][0][0] == [
+        "git",
+        "push",
+        "-u",
+        "origin",
+        "feature-branch",
+    ]
+    assert mock_run.call_args_list[2][0][0] == ["gh", "pr", "create", "--fill"]
+
+
+@patch(_MOCK_TARGET)
+def test_direct_mail_push_existing_pr(mock_run: MagicMock) -> None:
+    """Test GitHubPlugin.vcs_mail just pushes when PR already exists."""
+    mock_run.side_effect = [
+        MagicMock(returncode=0, stdout="", stderr=""),  # git push
+        MagicMock(returncode=0, stdout="42\n", stderr=""),  # gh pr view (PR exists)
+    ]
+
+    plugin = GitHubPlugin()
+    success, error = plugin.vcs_mail("feature-branch", "/workspace")
+
+    assert success is True
+    assert error is None
+    assert mock_run.call_count == 2
+
+
+@patch(_MOCK_TARGET)
+def test_direct_mail_push_fails(mock_run: MagicMock) -> None:
+    """Test GitHubPlugin.vcs_mail when push fails."""
+    mock_run.return_value = MagicMock(
+        returncode=1, stdout="", stderr="permission denied"
+    )
+
+    plugin = GitHubPlugin()
+    success, error = plugin.vcs_mail("feature-branch", "/workspace")
+
+    assert success is False
+    assert error is not None
+    assert "git push failed" in error