feat: close branch-list / push-delete / default-branch gaps (#171-#176) (#174)

* feat(git,github): close branch-list/push-delete/default-branch gaps

Three missing-capability issues addressed in one change.

Issue #171 — register git_branch_list as a lean MCP tool
  - Extend existing _branch_ops.git_branch_list with schema requested
    in the issue: branch_type (local|remote|all), pattern, contains,
    merged. Return structured records (name/sha/is_current/upstream).
  - Legacy remote=/all= bools kept as aliases for back-compat;
    explicit conflict with branch_type surfaces as error text.
  - Add GitBranchList pydantic model and register in lean/registry_git.
  - 21 tests (test_git_branch_list.py rewritten).

Issue #172 — default_branch passthrough on github_update_repo_settings
  - Add default_branch: str | None field to GitHubUpdateRepoSettings
    and forward to the PATCH /repos/{owner}/{name} payload.
  - Unblocks workflows that need to flip the repo's default branch
    (e.g. main -> development for sub-package conventions).
  - 1 new test verifies the payload entry.

Issue #173 — delete + raw refspec support on git_push
  - Add delete: bool and refspec: str | None fields to GitPush.
  - model_validator enforces five mutual-exclusion rules; same guards
    mirrored in the handler in case lean dispatch skips pydantic.
  - delete=True dispatches `git push <remote> --delete <branch>`;
    refspec dispatches `git push <remote> <refspec>`.
  - Closes the circular dead-end where shell-runner refused
    `git push --delete` and the MCP tool didn't support it.
  - 16 new tests in test_git_push_delete.py.

* feat(git): add sort to git_branch_list, dry_run to git_push

Bundled into PR #174 to avoid staggering MCP server restarts.

Issue #175 — git_branch_list sort
  - Add sort: str | None field to GitBranchList (e.g. '-committerdate',
    'refname', 'authordate'); mirrors `git for-each-ref --sort=<key>`.
  - When set, branches are collected via for_each_ref with NUL-separated
    format; existing pattern/contains/merged filters apply post-fetch.
  - sort=None preserves the legacy collection path (no perf regression).
  - 10 new tests in TestGitBranchListSort.

Issue #176 — git_push dry_run
  - Add dry_run: bool = False to GitPush; orthogonal to all existing
    mutual-exclusion rules (no validator changes).
  - Appends --dry-run to all four push paths: normal, force, delete,
    raw refspec. Return string carries a 'dry-run' marker.
  - 11 new tests in TestGitPushDryRun.

Author: MementoRC

src/mcp_server_git/git/_branch_ops.py

@@ -1,6 +1,8 @@
 """Branch operations for MCP Git Server."""
 
+import fnmatch
 import logging
+from typing import Any, Literal
 
 from ..utils.git_import import GitCommandError, Repo
 
@@ -116,43 +118,221 @@ def git_checkout(repo: Repo, branch_name: str) -> str:
         return f"❌ Checkout error: {str(e)}"
 
 
+def _resolve_branch_type(
+    branch_type: Literal["local", "remote", "all"],
+    remote: bool,
+    all: bool,  # noqa: A002
+) -> Literal["local", "remote", "all"]:
+    """Resolve branch_type from new param or legacy bool aliases."""
+    legacy_used = remote or all
+    explicit_type = branch_type != "local"
+
+    if explicit_type and legacy_used:
+        raise ValueError(
+            "Cannot combine 'branch_type' with legacy 'remote'/'all' flags. "
+            "Use 'branch_type' only."
+        )
+
+    if legacy_used:
+        if all:
+            return "all"
+        return "remote"
+
+    return branch_type
+
+
+def _get_contains_set(repo: Repo, contains: str) -> set[str]:
+    """Return set of branch names (stripped) that contain the given commit-ish."""
+    raw = repo.git.branch("--contains", contains)
+    names = set()
+    for line in raw.splitlines():
+        name = line.lstrip("* ").strip()
+        if name:
+            names.add(name)
+    return names
+
+
+def _get_merged_set(repo: Repo, *, merged: bool) -> set[str]:
+    """Return set of branch names filtered by --merged or --no-merged."""
+    flag = "--merged" if merged else "--no-merged"
+    raw = repo.git.branch(flag)
+    names = set()
+    for line in raw.splitlines():
+        name = line.lstrip("* ").strip()
+        if name:
+            names.add(name)
+    return names
+
+
+def _build_branch_record(
+    name: str,
+    sha: str,
+    is_current: bool,
+    upstream: str | None,
+) -> dict[str, Any]:
+    return {"name": name, "sha": sha, "is_current": is_current, "upstream": upstream}
+
+
+def _collect_local_branches(repo: Repo) -> list[dict[str, Any]]:
+    """Collect local branch records."""
+    try:
+        active = repo.active_branch.name
+    except TypeError:
+        active = None  # detached HEAD
+
+    records = []
+    for head in repo.branches:
+        try:
+            upstream = (
+                head.tracking_branch().name
+                if head.tracking_branch() is not None
+                else None
+            )
+        except Exception:
+            upstream = None
+        records.append(
+            _build_branch_record(
+                name=head.name,
+                sha=head.commit.hexsha,
+                is_current=(head.name == active),
+                upstream=upstream,
+            )
+        )
+    return records
+
+
+def _collect_remote_branches(repo: Repo) -> list[dict[str, Any]]:
+    """Collect remote branch records (remotes/origin/... style names)."""
+    records = []
+    for remote in repo.remotes:
+        for ref in remote.refs:
+            if ref.name.endswith("/HEAD"):
+                continue
+            records.append(
+                _build_branch_record(
+                    name=ref.name,
+                    sha=ref.commit.hexsha,
+                    is_current=False,
+                    upstream=None,
+                )
+            )
+    return records
+
+
+def _collect_sorted_branches(
+    repo: Repo,
+    effective_type: Literal["local", "remote", "all"],
+    sort: str,
+) -> list[dict[str, Any]]:
+    """Collect branches in sorted order using git for-each-ref."""
+    patterns: list[str]
+    if effective_type == "local":
+        patterns = ["refs/heads"]
+    elif effective_type == "remote":
+        patterns = ["refs/remotes"]
+    else:
+        patterns = ["refs/heads", "refs/remotes"]
+
+    fmt = "%(refname:short)%00%(objectname)%00%(upstream:short)"
+    raw = repo.git.for_each_ref(f"--sort={sort}", f"--format={fmt}", *patterns)
+
+    try:
+        active = repo.active_branch.name
+    except TypeError:
+        active = None  # detached HEAD
+
+    records = []
+    for line in raw.splitlines():
+        if not line:
+            continue
+        parts = line.split("\x00")
+        if len(parts) < 3:  # pragma: no cover
+            continue
+        name, sha, upstream = parts[0], parts[1], parts[2]
+        # Skip remote HEAD symbolic refs
+        if name.endswith("/HEAD"):
+            continue
+        records.append(
+            _build_branch_record(
+                name=name,
+                sha=sha,
+                is_current=(name == active),
+                upstream=upstream if upstream else None,
+            )
+        )
+    return records
+
+
+def _format_branches(records: list[dict[str, Any]]) -> str:
+    if not records:
+        return "No branches found"
+    lines = []
+    for r in records:
+        marker = "* " if r["is_current"] else "  "
+        sha_short = r["sha"][:8]
+        upstream_info = f" -> {r['upstream']}" if r["upstream"] else ""
+        lines.append(f"{marker}{r['name']} [{sha_short}]{upstream_info}")
+    return "Branches:\n" + "\n".join(lines)
+
+
 def git_branch_list(
     repo: Repo,
-    remote: bool = False,
-    all: bool = False,
+    branch_type: Literal["local", "remote", "all"] = "local",
     pattern: str | None = None,
+    contains: str | None = None,
+    merged: bool | None = None,
+    sort: str | None = None,
+    # Deprecated back-compat aliases — derive branch_type from these if branch_type
+    # is at default ("local") and no explicit branch_type was set.
+    remote: bool = False,
+    all: bool = False,  # noqa: A002
 ) -> str:
-    """List branches in the repository
+    """List branches in the repository.
 
     Args:
         repo: Repository object
-        remote: If True, list remote branches (git branch -r)
-        all: If True, list all branches including remote (git branch -a)
-        pattern: Optional pattern to filter branches (supports glob patterns like 'feature/*')
+        branch_type: Which branches to list — "local" (default), "remote", or "all"
+        pattern: Optional fnmatch glob to filter branch names, e.g. 'feature/*'
+        contains: commit-ish; only branches containing this commit are returned
+        merged: True = only merged into HEAD, False = only unmerged, None = no filter
+        sort: Sort key for git for-each-ref, e.g. '-committerdate'. None = legacy path.
+        remote: Deprecated. Use branch_type='remote' instead.
+        all: Deprecated. Use branch_type='all' instead.
 
     Returns:
-        String containing the list of branches
+        Formatted string listing branches with sha and upstream info.
     """
     try:
-        args = []
-
-        # Add branch listing flags
-        if all:
-            args.append("-a")
-        elif remote:
-            args.append("-r")
-
-        # When using pattern, we need to add --list flag
+        effective_type = _resolve_branch_type(branch_type, remote, all)
+
+        # Collect candidate records
+        if sort is not None:
+            records = _collect_sorted_branches(repo, effective_type, sort)
+        elif effective_type == "local":
+            records = _collect_local_branches(repo)
+        elif effective_type == "remote":
+            records = _collect_remote_branches(repo)
+        else:  # "all"
+            records = _collect_local_branches(repo) + _collect_remote_branches(repo)
+
+        # Apply pattern filter
         if pattern and pattern.strip():
-            args.append("--list")
-            args.append(pattern)
+            records = [r for r in records if fnmatch.fnmatch(r["name"], pattern)]
 
-        branch_output = repo.git.branch(*args)
+        # Apply contains filter
+        if contains is not None:
+            allowed = _get_contains_set(repo, contains)
+            records = [r for r in records if r["name"] in allowed]
 
-        if not branch_output.strip():
-            return "No branches found"
+        # Apply merged filter
+        if merged is not None:
+            allowed = _get_merged_set(repo, merged=merged)
+            records = [r for r in records if r["name"] in allowed]
 
-        return f"Branches:\n{branch_output}"
+        return _format_branches(records)
+
+    except ValueError as e:
+        return f"❌ Branch list error: {str(e)}"
     except GitCommandError as e:
         return f"❌ Branch list failed: {str(e)}"
     except Exception as e:

src/mcp_server_git/git/_remote_ops.py

@@ -67,6 +67,9 @@ def git_push(
     force_with_lease: bool = False,
     force_with_lease_expect: str | None = None,
     force_if_includes: bool = False,
+    delete: bool = False,
+    refspec: str | None = None,
+    dry_run: bool = False,
 ) -> str:
     """Push with comprehensive authentication including fallback to system git credentials.
 
@@ -81,6 +84,16 @@ def git_push(
         Composes with ``--force-with-lease`` to also detect rebase-on-stale-base.
 
     ``force`` and ``force_with_lease`` are mutually exclusive.
+
+    Delete / refspec controls (issue #173):
+      - ``delete``: maps to ``--delete <branch>`` (delete remote branch).
+        Requires ``branch``; mutually exclusive with force/refspec.
+      - ``refspec``: raw push refspec (e.g. ``src:dst`` or ``:branch``).
+        Mutually exclusive with ``branch``/``delete``.
+
+    Dry-run control (issue #176):
+      - ``dry_run``: maps to ``--dry-run``. Compatible with all push modes.
+        When True, git reports what would be pushed without modifying remote state.
     """
     try:
         # Validate force-push parameter combinations (issue #161)
@@ -92,6 +105,36 @@ def git_push(
         if force_with_lease_expect is not None and not force_with_lease:
             return "❌ force_with_lease_expect requires force_with_lease=True"
 
+        # Validate delete/refspec combinations (issue #173)
+        if delete:
+            if not branch:
+                return "❌ delete=True requires branch to be set"
+            if force or force_with_lease or force_if_includes:
+                return "❌ delete=True cannot be combined with force/force_with_lease/force_if_includes"
+            if set_upstream:
+                return "❌ delete=True cannot be combined with set_upstream"
+            if refspec is not None:
+                return "❌ delete=True cannot be combined with refspec"
+        if refspec is not None:
+            if branch is not None:
+                return "❌ refspec cannot be combined with branch"
+            if set_upstream:
+                return "❌ refspec cannot be combined with set_upstream"
+
+        # Handle raw refspec push
+        if refspec is not None:
+            extra = ["--dry-run"] if dry_run else []
+            repo.git.push(remote, refspec, *extra)
+            suffix = " (dry-run; no remote state modified)" if dry_run else ""
+            return f"✅ Successfully pushed refspec '{refspec}' to {remote}{suffix}"
+
+        # Handle delete remote branch
+        if delete:
+            extra = ["--dry-run"] if dry_run else []
+            repo.git.push(remote, "--delete", branch, *extra)
+            suffix = " (dry-run; no remote state modified)" if dry_run else ""
+            return f"✅ Successfully deleted remote branch '{branch}' from {remote}{suffix}"
+
         # Get current branch if not specified
         if not branch:
             try:
@@ -121,6 +164,8 @@ def git_push(
         if force_if_includes:
             # Compatible with --force-with-lease; harmless without it on git 2.30+.
             push_args.insert(0, "--force-if-includes")
+        if dry_run:
+            push_args.append("--dry-run")
 
         # Get remote URL for GitHub authentication handling (cache for reuse)
         remote_url = ""
@@ -176,6 +221,8 @@ def git_push(
                         success_msg = f"✅ Successfully pushed {branch} to {remote}"
                         if set_upstream:
                             success_msg += " (set upstream tracking)"
+                        if dry_run:
+                            success_msg += " (dry-run; no remote state modified)"
 
                         # Indicate which authentication method was used
                         if os.getenv("GITHUB_TOKEN"):
@@ -217,6 +264,8 @@ def git_push(
                         success_msg = f"✅ Successfully pushed {branch} to {remote}"
                         if set_upstream:
                             success_msg += " (set upstream tracking)"
+                        if dry_run:
+                            success_msg += " (dry-run; no remote state modified)"
                         success_msg += "\n🔐 Used system git authentication"
                         return success_msg
                     else:
@@ -258,6 +307,8 @@ def git_push(
             success_msg = f"✅ Successfully pushed {branch} to {remote}"
             if set_upstream:
                 success_msg += " (set upstream tracking)"
+            if dry_run:
+                success_msg += " (dry-run; no remote state modified)"
             return success_msg
         except GitCommandError as e:
             # If regular push fails and this is GitHub HTTPS, suggest auth options