Release version 1.8.1

- Add GhTokenProvider to read GitHub tokens via `gh auth token`
- Extend TokenResolver policy: ENV → gh → keyring (validate) → prompt (overwrite)
- Introduce provider-specific token validation for GitHub
- Ensure invalid keyring tokens trigger interactive re-prompt and overwrite
- Add end-to-end integration test covering gh → keyring → prompt flow
- Clean up credentials package exports and documentation

https://chatgpt.com/share/69418c81-6748-800f-8fec-616684746e3c

CHANGELOG.md

@@ -1,3 +1,11 @@
+## [1.8.1] - 2025-12-16
+
+* * Improved stability and consistency of all Git operations (clone, pull, push, release, branch handling) with clearer error messages and predictable preview behavior.
+* Mirrors are now handled cleanly: only valid Git remotes are used for Git operations, while non-Git URLs (e.g. PyPI) are excluded, preventing broken or confusing repository configs.
+* GitHub authentication is more robust: tokens are automatically resolved via the GitHub CLI (`gh`), invalid stored tokens are replaced, and interactive prompts occur only when necessary.
+* Repository creation and release workflows are more reliable, producing cleaner Git configurations and more predictable version handling.
+
+
 ## [1.8.0] - 2025-12-15
 
 * *** New Features: ***

flake.nix

@@ -32,7 +32,7 @@
         rec {
           pkgmgr = pyPkgs.buildPythonApplication {
             pname   = "package-manager";
-            version = "1.8.0";
+            version = "1.8.1";
 
             # Use the git repo as source
             src = ./.;

packaging/arch/PKGBUILD

@@ -1,7 +1,7 @@
 # Maintainer: Kevin Veen-Birkenbach <info@veen.world>
 
 pkgname=package-manager
-pkgver=1.8.0
+pkgver=1.8.1
 pkgrel=1
 pkgdesc="Local-flake wrapper for Kevin's package-manager (Nix-based)."
 arch=('any')

packaging/debian/changelog

@@ -1,3 +1,12 @@
+package-manager (1.8.1-1) unstable; urgency=medium
+
+  * * Improved stability and consistency of all Git operations (clone, pull, push, release, branch handling) with clearer error messages and predictable preview behavior.
+* Mirrors are now handled cleanly: only valid Git remotes are used for Git operations, while non-Git URLs (e.g. PyPI) are excluded, preventing broken or confusing repository configs.
+* GitHub authentication is more robust: tokens are automatically resolved via the GitHub CLI (`gh`), invalid stored tokens are replaced, and interactive prompts occur only when necessary.
+* Repository creation and release workflows are more reliable, producing cleaner Git configurations and more predictable version handling.
+
+ -- Kevin Veen-Birkenbach <kevin@veen.world>  Tue, 16 Dec 2025 18:06:35 +0100
+
 package-manager (1.8.0-1) unstable; urgency=medium
 
   * *** New Features: ***

packaging/fedora/package-manager.spec

@@ -1,5 +1,5 @@
 Name:           package-manager
-Version:        1.8.0
+Version:        1.8.1
 Release:        1%{?dist}
 Summary:        Wrapper that runs Kevin's package-manager via Nix flake
 
@@ -74,6 +74,12 @@ echo ">>> package-manager removed. Nix itself was not removed."
 /usr/lib/package-manager/
 
 %changelog
+* Tue Dec 16 2025 Kevin Veen-Birkenbach <kevin@veen.world> - 1.8.1-1
+- * Improved stability and consistency of all Git operations (clone, pull, push, release, branch handling) with clearer error messages and predictable preview behavior.
+* Mirrors are now handled cleanly: only valid Git remotes are used for Git operations, while non-Git URLs (e.g. PyPI) are excluded, preventing broken or confusing repository configs.
+* GitHub authentication is more robust: tokens are automatically resolved via the GitHub CLI (`gh`), invalid stored tokens are replaced, and interactive prompts occur only when necessary.
+* Repository creation and release workflows are more reliable, producing cleaner Git configurations and more predictable version handling.
+
 * Mon Dec 15 2025 Kevin Veen-Birkenbach <kevin@veen.world> - 1.8.0-1
 - *** New Features: ***
 - **Silent Updates**: You can now use the `--silent` flag during installs and updates to suppress error messages for individual repositories and get a single summary at the end. This ensures the process continues even if some repositories fail, while still preserving interactive checks when not in silent mode.

pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "kpmx"
-version = "1.8.0"
+version = "1.8.1"
 description = "Kevin's package-manager tool (pkgmgr)"
 readme = "README.md"
 requires-python = ">=3.9"

src/pkgmgr/actions/__init__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+# expose subpackages for patch() / resolve_name() friendliness
+from . import release as release  # noqa: F401
+
+__all__ = ["release"]

src/pkgmgr/actions/branch/close_branch.py

@@ -1,7 +1,21 @@
 from __future__ import annotations
+
 from typing import Optional
-from pkgmgr.core.git import run_git, GitError, get_current_branch
-from .utils import _resolve_base_branch
+
+from pkgmgr.core.git.errors import GitError
+from pkgmgr.core.git.queries import get_current_branch
+from pkgmgr.core.git.commands import (
+    GitDeleteRemoteBranchError,
+    checkout,
+    delete_local_branch,
+    delete_remote_branch,
+    fetch,
+    merge_no_ff,
+    pull,
+    push,
+)
+
+from pkgmgr.core.git.queries import resolve_base_branch
 
 
 def close_branch(
@@ -14,7 +28,6 @@ def close_branch(
     """
     Merge a feature branch into the base branch and delete it afterwards.
     """
-
     # Determine branch name
     if not name:
         try:
@@ -25,7 +38,7 @@ def close_branch(
     if not name:
         raise RuntimeError("Branch name must not be empty.")
 
-    target_base = _resolve_base_branch(base_branch, fallback_base, cwd=cwd)
+    target_base = resolve_base_branch(base_branch, fallback_base, cwd=cwd)
 
     if name == target_base:
         raise RuntimeError(
@@ -42,58 +55,20 @@ def close_branch(
             print("Aborted closing branch.")
             return
 
-    # Fetch
-    try:
-        run_git(["fetch", "origin"], cwd=cwd)
-    except GitError as exc:
-        raise RuntimeError(
-            f"Failed to fetch from origin before closing branch {name!r}: {exc}"
-        ) from exc
+    # Execute workflow (commands raise specific GitError subclasses)
+    fetch("origin", cwd=cwd)
+    checkout(target_base, cwd=cwd)
+    pull("origin", target_base, cwd=cwd)
+    merge_no_ff(name, cwd=cwd)
+    push("origin", target_base, cwd=cwd)
 
-    # Checkout base
-    try:
-        run_git(["checkout", target_base], cwd=cwd)
-    except GitError as exc:
-        raise RuntimeError(
-            f"Failed to checkout base branch {target_base!r}: {exc}"
-        ) from exc
+    # Delete local branch (safe delete by default)
+    delete_local_branch(name, cwd=cwd, force=False)
 
-    # Pull latest
+    # Delete remote branch (special-case error message)
     try:
-        run_git(["pull", "origin", target_base], cwd=cwd)
-    except GitError as exc:
-        raise RuntimeError(
-            f"Failed to pull latest changes for base branch {target_base!r}: {exc}"
-        ) from exc
-
-    # Merge
-    try:
-        run_git(["merge", "--no-ff", name], cwd=cwd)
-    except GitError as exc:
-        raise RuntimeError(
-            f"Failed to merge branch {name!r} into {target_base!r}: {exc}"
-        ) from exc
-
-    # Push result
-    try:
-        run_git(["push", "origin", target_base], cwd=cwd)
-    except GitError as exc:
-        raise RuntimeError(
-            f"Failed to push base branch {target_base!r} after merge: {exc}"
-        ) from exc
-
-    # Delete local
-    try:
-        run_git(["branch", "-d", name], cwd=cwd)
-    except GitError as exc:
-        raise RuntimeError(
-            f"Failed to delete local branch {name!r}: {exc}"
-        ) from exc
-
-    # Delete remote
-    try:
-        run_git(["push", "origin", "--delete", name], cwd=cwd)
-    except GitError as exc:
+        delete_remote_branch("origin", name, cwd=cwd)
+    except GitDeleteRemoteBranchError as exc:
         raise RuntimeError(
             f"Branch {name!r} deleted locally, but remote deletion failed: {exc}"
         ) from exc

src/pkgmgr/actions/branch/drop_branch.py

@@ -1,7 +1,16 @@
 from __future__ import annotations
+
 from typing import Optional
-from pkgmgr.core.git import run_git, GitError, get_current_branch
-from .utils import _resolve_base_branch
+
+from pkgmgr.core.git.errors import GitError
+from pkgmgr.core.git.queries import get_current_branch
+from pkgmgr.core.git.commands import (
+    GitDeleteRemoteBranchError,
+    delete_local_branch,
+    delete_remote_branch,
+)
+
+from pkgmgr.core.git.queries import resolve_base_branch
 
 
 def drop_branch(
@@ -14,7 +23,6 @@ def drop_branch(
     """
     Delete a branch locally and remotely without merging.
     """
-
     if not name:
         try:
             name = get_current_branch(cwd=cwd)
@@ -24,7 +32,7 @@ def drop_branch(
     if not name:
         raise RuntimeError("Branch name must not be empty.")
 
-    target_base = _resolve_base_branch(base_branch, fallback_base, cwd=cwd)
+    target_base = resolve_base_branch(base_branch, fallback_base, cwd=cwd)
 
     if name == target_base:
         raise RuntimeError(
@@ -40,16 +48,12 @@ def drop_branch(
             print("Aborted dropping branch.")
             return
 
-    # Local delete
+    delete_local_branch(name, cwd=cwd, force=False)
+    
+    # Remote delete (special-case message)
     try:
-        run_git(["branch", "-d", name], cwd=cwd)
-    except GitError as exc:
-        raise RuntimeError(f"Failed to delete local branch {name!r}: {exc}") from exc
-
-    # Remote delete
-    try:
-        run_git(["push", "origin", "--delete", name], cwd=cwd)
-    except GitError as exc:
+        delete_remote_branch("origin", name, cwd=cwd)
+    except GitDeleteRemoteBranchError as exc:
         raise RuntimeError(
             f"Branch {name!r} was deleted locally, but remote deletion failed: {exc}"
         ) from exc

src/pkgmgr/actions/branch/open_branch.py

@@ -1,7 +1,15 @@
 from __future__ import annotations
+
 from typing import Optional
-from pkgmgr.core.git import run_git, GitError
-from .utils import _resolve_base_branch
+
+from pkgmgr.core.git.commands import (
+    checkout,
+    create_branch,
+    fetch,
+    pull,
+    push_upstream,
+)
+from pkgmgr.core.git.queries import resolve_base_branch
 
 
 def open_branch(
@@ -13,7 +21,6 @@ def open_branch(
     """
     Create and push a new feature branch on top of a base branch.
     """
-
     # Request name interactively if not provided
     if not name:
         name = input("Enter new branch name: ").strip()
@@ -21,44 +28,13 @@ def open_branch(
     if not name:
         raise RuntimeError("Branch name must not be empty.")
 
-    resolved_base = _resolve_base_branch(base_branch, fallback_base, cwd=cwd)
+    resolved_base = resolve_base_branch(base_branch, fallback_base, cwd=cwd)
 
-    # 1) Fetch from origin
-    try:
-        run_git(["fetch", "origin"], cwd=cwd)
-    except GitError as exc:
-        raise RuntimeError(
-            f"Failed to fetch from origin before creating branch {name!r}: {exc}"
-        ) from exc
+    # Workflow (commands raise specific GitError subclasses)
+    fetch("origin", cwd=cwd)
+    checkout(resolved_base, cwd=cwd)
+    pull("origin", resolved_base, cwd=cwd)
 
-    # 2) Checkout base branch
-    try:
-        run_git(["checkout", resolved_base], cwd=cwd)
-    except GitError as exc:
-        raise RuntimeError(
-            f"Failed to checkout base branch {resolved_base!r}: {exc}"
-        ) from exc
-
-    # 3) Pull latest changes
-    try:
-        run_git(["pull", "origin", resolved_base], cwd=cwd)
-    except GitError as exc:
-        raise RuntimeError(
-            f"Failed to pull latest changes for base branch {resolved_base!r}: {exc}"
-        ) from exc
-
-    # 4) Create new branch
-    try:
-        run_git(["checkout", "-b", name], cwd=cwd)
-    except GitError as exc:
-        raise RuntimeError(
-            f"Failed to create new branch {name!r} from base {resolved_base!r}: {exc}"
-        ) from exc
-
-    # 5) Push new branch
-    try:
-        run_git(["push", "-u", "origin", name], cwd=cwd)
-    except GitError as exc:
-        raise RuntimeError(
-            f"Failed to push new branch {name!r} to origin: {exc}"
-        ) from exc
+    # Create new branch from resolved base and push it with upstream tracking
+    create_branch(name, resolved_base, cwd=cwd)
+    push_upstream("origin", name, cwd=cwd)

src/pkgmgr/actions/branch/utils.py

@@ -1,27 +0,0 @@
-from __future__ import annotations
-from pkgmgr.core.git import run_git, GitError
-
-
-def _resolve_base_branch(
-    preferred: str,
-    fallback: str,
-    cwd: str,
-) -> str:
-    """
-    Resolve the base branch to use.
-
-    Try `preferred` first (default: main),
-    fall back to `fallback` (default: master).
-
-    Raise RuntimeError if neither exists.
-    """
-    for candidate in (preferred, fallback):
-        try:
-            run_git(["rev-parse", "--verify", candidate], cwd=cwd)
-            return candidate
-        except GitError:
-            continue
-
-    raise RuntimeError(
-        f"Neither {preferred!r} nor {fallback!r} exist in this repository."
-    )

src/pkgmgr/actions/changelog/__init__.py

@@ -3,17 +3,16 @@
 
 """
 Helpers to generate changelog information from Git history.
-
-This module provides a small abstraction around `git log` so that
-CLI commands can request a changelog between two refs (tags, branches,
-commits) without dealing with raw subprocess calls.
 """
 
 from __future__ import annotations
 
 from typing import Optional
 
-from pkgmgr.core.git import run_git, GitError
+from pkgmgr.core.git.queries import (
+    get_changelog,
+    GitChangelogQueryError,
+)
 
 
 def generate_changelog(
@@ -25,48 +24,20 @@ def generate_changelog(
     """
     Generate a plain-text changelog between two Git refs.
 
-    Parameters
-    ----------
-    cwd:
-        Repository directory in which to run Git commands.
-    from_ref:
-        Optional starting reference (exclusive). If provided together
-        with `to_ref`, the range `from_ref..to_ref` is used.
-        If only `from_ref` is given, the range `from_ref..HEAD` is used.
-    to_ref:
-        Optional end reference (inclusive). If omitted, `HEAD` is used.
-    include_merges:
-        If False (default), merge commits are filtered out.
-
-    Returns
-    -------
-    str
-        The output of `git log` formatted as a simple text changelog.
-        If no commits are found or Git fails, an explanatory message
-        is returned instead of raising.
+    Returns a human-readable message instead of raising.
     """
-    # Determine the revision range
     if to_ref is None:
         to_ref = "HEAD"
 
-    if from_ref:
-        rev_range = f"{from_ref}..{to_ref}"
-    else:
-        rev_range = to_ref
-
-    # Use a custom pretty format that includes tags/refs (%d)
-    cmd = [
-        "log",
-        "--pretty=format:%h %d %s",
-    ]
-    if not include_merges:
-        cmd.append("--no-merges")
-    cmd.append(rev_range)
-
+    rev_range = f"{from_ref}..{to_ref}" if from_ref else to_ref
     try:
-        output = run_git(cmd, cwd=cwd)
-    except GitError as exc:
-        # Do not raise to the CLI, return a human-readable error instead.
+        output = get_changelog(
+            cwd=cwd,
+            from_ref=from_ref,
+            to_ref=to_ref,
+            include_merges=include_merges,
+        )
+    except GitChangelogQueryError as exc:
         return (
             f"[ERROR] Failed to generate changelog in {cwd!r} "
             f"for range {rev_range!r}:\n{exc}"

src/pkgmgr/actions/config/init.py

@@ -14,7 +14,7 @@ with the expected structure:
 
 For each discovered repository, the function:
   • derives provider, account, repository from the folder structure
-  • (optionally) determines the latest commit hash via git log
+  • (optionally) determines the latest commit hash via git
   • generates a unique CLI alias
   • marks ignore=True for newly discovered repos
   • skips repos already known in defaults or user config
@@ -23,11 +23,11 @@ For each discovered repository, the function:
 from __future__ import annotations
 
 import os
-import subprocess
 from typing import Any, Dict
 
 from pkgmgr.core.command.alias import generate_alias
 from pkgmgr.core.config.save import save_user_config
+from pkgmgr.core.git.queries import get_latest_commit
 
 
 def config_init(
@@ -116,27 +116,18 @@ def config_init(
 
                 print(f"[ADD]      {provider}/{account}/{repo_name}")
 
-                # Determine commit hash
-                try:
-                    result = subprocess.run(
-                        ["git", "log", "-1", "--format=%H"],
-                        cwd=repo_path,
-                        stdout=subprocess.PIPE,
-                        stderr=subprocess.PIPE,
-                        text=True,
-                        check=True,
-                    )
-                    verified = result.stdout.strip()
-                    print(f"[INFO]       Latest commit: {verified}")
-                except Exception as exc:
-                    verified = ""
-                    print(f"[WARN]       Could not read commit: {exc}")
+                # Determine commit hash via git query
+                verified_commit = get_latest_commit(repo_path) or ""
+                if verified_commit:
+                    print(f"[INFO]       Latest commit: {verified_commit}")
+                else:
+                    print("[WARN]       Could not read commit (not a git repo or no commits).")
 
-                entry = {
+                entry: Dict[str, Any] = {
                     "provider": provider,
                     "account": account,
                     "repository": repo_name,
-                    "verified": {"commit": verified},
+                    "verified": {"commit": verified_commit},
                     "ignore": True,
                 }
 

src/pkgmgr/actions/mirror/git_remote.py

@@ -1,14 +1,49 @@
 from __future__ import annotations
 
 import os
-from typing import List, Optional, Set
+from typing import Optional, Set
 
-from pkgmgr.core.command.run import run_command
-from pkgmgr.core.git import GitError, run_git
+from pkgmgr.core.git.errors import GitError
+from pkgmgr.core.git.commands import (
+    GitAddRemoteError,
+    GitAddRemotePushUrlError,
+    GitSetRemoteUrlError,
+    add_remote,
+    add_remote_push_url,
+    set_remote_url,
+)
+from pkgmgr.core.git.queries import get_remote_push_urls, list_remotes
 
 from .types import MirrorMap, RepoMirrorContext, Repository
 
 
+def _is_git_remote_url(url: str) -> bool:
+    """
+    True only for URLs that should become git remotes / push URLs.
+
+    Accepted:
+      - git@host:owner/repo(.git)                (SCP-like SSH)
+      - ssh://git@host(:port)/owner/repo(.git)   (SSH URL)
+      - https://host/owner/repo.git              (HTTPS git remote)
+      - http://host/owner/repo.git               (rare, but possible)
+    Everything else (e.g. PyPI project page) stays metadata only.
+    """
+    u = (url or "").strip()
+    if not u:
+        return False
+
+    if u.startswith("git@"):
+        return True
+
+    if u.startswith("ssh://"):
+        return True
+
+    if (u.startswith("https://") or u.startswith("http://")) and u.endswith(".git"):
+        return True
+
+    return False
+
+
 def build_default_ssh_url(repo: Repository) -> Optional[str]:
     provider = repo.get("provider")
     account = repo.get("account")
@@ -24,53 +59,48 @@ def build_default_ssh_url(repo: Repository) -> Optional[str]:
     return f"git@{provider}:{account}/{name}.git"
 
 
+def _git_mirrors_only(m: MirrorMap) -> MirrorMap:
+    return {k: v for k, v in m.items() if v and _is_git_remote_url(v)}
+
+
 def determine_primary_remote_url(
     repo: Repository,
     ctx: RepoMirrorContext,
 ) -> Optional[str]:
     """
-    Priority order:
-      1. origin from resolved mirrors
-      2. MIRRORS file order
-      3. config mirrors order
+    Priority order (GIT URLS ONLY):
+      1. origin from resolved mirrors (if it is a git URL)
+      2. first git URL from MIRRORS file (in file order)
+      3. first git URL from config mirrors (in config order)
       4. default SSH URL
     """
     resolved = ctx.resolved_mirrors
-
-    if resolved.get("origin"):
-        return resolved["origin"]
+    origin = resolved.get("origin")
+    if origin and _is_git_remote_url(origin):
+        return origin
 
     for mirrors in (ctx.file_mirrors, ctx.config_mirrors):
         for _, url in mirrors.items():
-            if url:
+            if url and _is_git_remote_url(url):
                 return url
 
     return build_default_ssh_url(repo)
 
 
-def _safe_git_output(args: List[str], cwd: str) -> Optional[str]:
-    try:
-        return run_git(args, cwd=cwd)
-    except GitError:
-        return None
-
-
 def has_origin_remote(repo_dir: str) -> bool:
-    out = _safe_git_output(["remote"], cwd=repo_dir)
-    return bool(out and "origin" in out.split())
+    try:
+        return "origin" in list_remotes(cwd=repo_dir)
+    except GitError:
+        return False
 
 
 def _set_origin_fetch_and_push(repo_dir: str, url: str, preview: bool) -> None:
-    fetch = f"git remote set-url origin {url}"
-    push = f"git remote set-url --push origin {url}"
-
-    if preview:
-        print(f"[PREVIEW] Would run in {repo_dir!r}: {fetch}")
-        print(f"[PREVIEW] Would run in {repo_dir!r}: {push}")
-        return
-
-    run_command(fetch, cwd=repo_dir, preview=False)
-    run_command(push, cwd=repo_dir, preview=False)
+    """
+    Ensure origin has fetch URL and push URL set to the primary URL.
+    Preview is handled by the underlying git runner.
+    """
+    set_remote_url("origin", url, cwd=repo_dir, push=False, preview=preview)
+    set_remote_url("origin", url, cwd=repo_dir, push=True, preview=preview)
 
 
 def _ensure_additional_push_urls(
@@ -79,22 +109,24 @@ def _ensure_additional_push_urls(
     primary: str,
     preview: bool,
 ) -> None:
-    desired: Set[str] = {u for u in mirrors.values() if u and u != primary}
+    """
+    Ensure all *git* mirror URLs (except primary) are configured as additional
+    push URLs for origin.
+
+    Non-git URLs (like PyPI) are ignored and will never land in git config.
+    """
+    git_only = _git_mirrors_only(mirrors)
+    desired: Set[str] = {u for u in git_only.values() if u and u != primary}
     if not desired:
         return
 
-    out = _safe_git_output(
-        ["remote", "get-url", "--push", "--all", "origin"],
-        cwd=repo_dir,
-    )
-    existing = set(out.splitlines()) if out else set()
+    try:
+        existing = get_remote_push_urls("origin", cwd=repo_dir)
+    except GitError:
+        existing = set()
 
     for url in sorted(desired - existing):
-        cmd = f"git remote set-url --add --push origin {url}"
-        if preview:
-            print(f"[PREVIEW] Would run in {repo_dir!r}: {cmd}")
-        else:
-            run_command(cmd, cwd=repo_dir, preview=False)
+        add_remote_push_url("origin", url, cwd=repo_dir, preview=preview)
 
 
 def ensure_origin_remote(
@@ -109,25 +141,26 @@ def ensure_origin_remote(
         return
 
     primary = determine_primary_remote_url(repo, ctx)
-    if not primary:
-        print("[WARN] No primary mirror URL could be determined.")
+    if not primary or not _is_git_remote_url(primary):
+        print("[WARN] No valid git primary mirror URL could be determined.")
         return
 
+    # 1) Ensure origin exists
     if not has_origin_remote(repo_dir):
-        cmd = f"git remote add origin {primary}"
-        if preview:
-            print(f"[PREVIEW] Would run in {repo_dir!r}: {cmd}")
-        else:
-            run_command(cmd, cwd=repo_dir, preview=False)
+        try:
+            add_remote("origin", primary, cwd=repo_dir, preview=preview)
+        except GitAddRemoteError as exc:
+            print(f"[WARN] Failed to add origin remote: {exc}")
+            return  # without origin we cannot reliably proceed
 
-        _set_origin_fetch_and_push(repo_dir, primary, preview)
-
-    _ensure_additional_push_urls(repo_dir, ctx.resolved_mirrors, primary, preview)
-
-
-def is_remote_reachable(url: str, cwd: Optional[str] = None) -> bool:
+    # 2) Ensure origin fetch+push URLs are correct
     try:
-        run_git(["ls-remote", "--exit-code", url], cwd=cwd or os.getcwd())
-        return True
-    except GitError:
-        return False
+        _set_origin_fetch_and_push(repo_dir, primary, preview)
+    except GitSetRemoteUrlError as exc:
+        print(f"[WARN] Failed to set origin URLs: {exc}")
+
+    # 3) Ensure additional push URLs for mirrors (git urls only)
+    try:
+        _ensure_additional_push_urls(repo_dir, ctx.resolved_mirrors, primary, preview)
+    except GitAddRemotePushUrlError as exc:
+        print(f"[WARN] Failed to add additional push URLs: {exc}")

src/pkgmgr/actions/mirror/remote_check.py

@@ -1,21 +0,0 @@
-# src/pkgmgr/actions/mirror/remote_check.py
-from __future__ import annotations
-
-from typing import Tuple
-
-from pkgmgr.core.git import GitError, run_git
-
-
-def probe_mirror(url: str, repo_dir: str) -> Tuple[bool, str]:
-    """
-    Probe a remote mirror URL using `git ls-remote`.
-
-    Returns:
-      (True, "") on success,
-      (False, error_message) on failure.
-    """
-    try:
-        run_git(["ls-remote", url], cwd=repo_dir)
-        return True, ""
-    except GitError as exc:
-        return False, str(exc)

src/pkgmgr/actions/mirror/setup_cmd.py

@@ -2,13 +2,29 @@ from __future__ import annotations
 
 from typing import List
 
+from pkgmgr.core.git.queries import probe_remote_reachable
+
 from .context import build_context
 from .git_remote import ensure_origin_remote, determine_primary_remote_url
-from .remote_check import probe_mirror
 from .remote_provision import ensure_remote_repository
 from .types import Repository
 
 
+def _is_git_remote_url(url: str) -> bool:
+    # Keep the same filtering semantics as in git_remote.py (duplicated on purpose
+    # to keep setup_cmd independent of private helpers).
+    u = (url or "").strip()
+    if not u:
+        return False
+    if u.startswith("git@"):
+        return True
+    if u.startswith("ssh://"):
+        return True
+    if (u.startswith("https://") or u.startswith("http://")) and u.endswith(".git"):
+        return True
+    return False
+
+
 def _setup_local_mirrors_for_repo(
     repo: Repository,
     repositories_base_dir: str,
@@ -48,23 +64,25 @@ def _setup_remote_mirrors_for_repo(
             preview,
         )
 
-    if not ctx.resolved_mirrors:
+    # Probe only git URLs (do not try ls-remote against PyPI etc.)
+    # If there are no mirrors at all, probe the primary git URL.
+    git_mirrors = {k: v for k, v in ctx.resolved_mirrors.items() if _is_git_remote_url(v)}
+
+    if not git_mirrors:
         primary = determine_primary_remote_url(repo, ctx)
-        if not primary:
+        if not primary or not _is_git_remote_url(primary):
+            print("[INFO] No git mirrors to probe.")
+            print()
             return
 
-        ok, msg = probe_mirror(primary, ctx.repo_dir)
+        ok = probe_remote_reachable(primary, cwd=ctx.repo_dir)
         print("[OK]" if ok else "[WARN]", primary)
-        if msg:
-            print(msg)
         print()
         return
 
-    for name, url in ctx.resolved_mirrors.items():
-        ok, msg = probe_mirror(url, ctx.repo_dir)
+    for name, url in git_mirrors.items():
+        ok = probe_remote_reachable(url, cwd=ctx.repo_dir)
         print(f"[OK] {name}: {url}" if ok else f"[WARN] {name}: {url}")
-        if msg:
-            print(msg)
 
     print()
 

src/pkgmgr/actions/publish/git_tags.py

@@ -1,17 +1,10 @@
 from __future__ import annotations
 
-from pkgmgr.core.git import run_git
+from pkgmgr.core.git.queries import get_tags_at_ref
 from pkgmgr.core.version.semver import SemVer, is_semver_tag
 
 
 def head_semver_tags(cwd: str = ".") -> list[str]:
-    out = run_git(["tag", "--points-at", "HEAD"], cwd=cwd)
-    if not out:
-        return []
-
-    tags = [t.strip() for t in out.splitlines() if t.strip()]
+    tags = get_tags_at_ref("HEAD", cwd=cwd)
     tags = [t for t in tags if is_semver_tag(t) and t.startswith("v")]
-    if not tags:
-        return []
-
     return sorted(tags, key=SemVer.parse)

src/pkgmgr/actions/release/files.py

@@ -24,6 +24,8 @@ import tempfile
 from datetime import date, datetime
 from typing import Optional, Tuple
 
+from pkgmgr.core.git.queries import get_config_value
+
 
 # ---------------------------------------------------------------------------
 # Editor helper for interactive changelog messages
@@ -74,10 +76,7 @@ def _open_editor_for_changelog(initial_message: Optional[str] = None) -> str:
         except OSError:
             pass
 
-    lines = [
-        line for line in content.splitlines()
-        if not line.strip().startswith("#")
-    ]
+    lines = [line for line in content.splitlines() if not line.strip().startswith("#")]
     return "\n".join(lines).strip()
 
 
@@ -85,6 +84,7 @@ def _open_editor_for_changelog(initial_message: Optional[str] = None) -> str:
 # File update helpers (pyproject + extra packaging + changelog)
 # ---------------------------------------------------------------------------
 
+
 def update_pyproject_version(
     pyproject_path: str,
     new_version: str,
@@ -365,24 +365,6 @@ def update_changelog(
 # ---------------------------------------------------------------------------
 
 
-def _get_git_config_value(key: str) -> Optional[str]:
-    """
-    Try to read a value from `git config --get <key>`.
-    """
-    try:
-        result = subprocess.run(
-            ["git", "config", "--get", key],
-            capture_output=True,
-            text=True,
-            check=False,
-        )
-    except Exception:
-        return None
-
-    value = result.stdout.strip()
-    return value or None
-
-
 def _get_debian_author() -> Tuple[str, str]:
     """
     Determine the maintainer name/email for debian/changelog entries.
@@ -396,9 +378,9 @@ def _get_debian_author() -> Tuple[str, str]:
         email = os.environ.get("GIT_AUTHOR_EMAIL")
 
     if not name:
-        name = _get_git_config_value("user.name")
+        name = get_config_value("user.name")
     if not email:
-        email = _get_git_config_value("user.email")
+        email = get_config_value("user.email")
 
     if not name:
         name = "Unknown Maintainer"

src/pkgmgr/actions/release/git_ops.py

@@ -1,73 +1,90 @@
 from __future__ import annotations
 
-import subprocess
-
-from pkgmgr.core.git import GitError
+from pkgmgr.core.git.commands import (
+    fetch,
+    pull_ff_only,
+    push,
+    tag_force_annotated,
+)
+from pkgmgr.core.git.queries import get_upstream_ref, list_tags
 
 
-def run_git_command(cmd: str) -> None:
-    print(f"[GIT] {cmd}")
-    try:
-        subprocess.run(
-            cmd,
-            shell=True,
-            check=True,
-            text=True,
-            capture_output=True,
-        )
-    except subprocess.CalledProcessError as exc:
-        print(f"[ERROR] Git command failed: {cmd}")
-        print(f"        Exit code: {exc.returncode}")
-        if exc.stdout:
-            print("\n" + exc.stdout)
-        if exc.stderr:
-            print("\n" + exc.stderr)
-        raise GitError(f"Git command failed: {cmd}") from exc
-
-
-def _capture(cmd: str) -> str:
-    res = subprocess.run(cmd, shell=True, check=False, capture_output=True, text=True)
-    return (res.stdout or "").strip()
-
-
-def ensure_clean_and_synced(preview: bool = False) -> None:
+def ensure_clean_and_synced(*, preview: bool = False) -> None:
     """
     Always run a pull BEFORE modifying anything.
     Uses --ff-only to avoid creating merge commits automatically.
     If no upstream is configured, we skip.
     """
-    upstream = _capture("git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null")
+    upstream = get_upstream_ref()
     if not upstream:
         print("[INFO] No upstream configured for current branch. Skipping pull.")
         return
 
-    if preview:
-        print("[PREVIEW] Would run: git fetch origin --prune --tags --force")
-        print("[PREVIEW] Would run: git pull --ff-only")
-        return
-
     print("[INFO] Syncing with remote before making any changes...")
-    run_git_command("git fetch origin --prune --tags --force")
-    run_git_command("git pull --ff-only")
+
+    # Mirrors old behavior:
+    #   git fetch origin --prune --tags --force
+    #   git pull --ff-only
+    fetch(remote="origin", prune=True, tags=True, force=True, preview=preview)
+    pull_ff_only(preview=preview)
+
+
+def _parse_v_tag(tag: str) -> tuple[int, ...] | None:
+    """
+    Parse tags like 'v1.2.3' into (1, 2, 3).
+    Returns None if parsing is not possible.
+    """
+    if not tag.startswith("v"):
+        return None
+
+    raw = tag[1:]
+    if not raw:
+        return None
+
+    parts = raw.split(".")
+    out: list[int] = []
+    for p in parts:
+        if not p.isdigit():
+            return None
+        out.append(int(p))
+    return tuple(out) if out else None
+
 
 def is_highest_version_tag(tag: str) -> bool:
     """
     Return True if `tag` is the highest version among all tags matching v*.
-    Comparison uses `sort -V` for natural version ordering.
+
+    We avoid shelling out to `sort -V` and implement a small vX.Y.Z parser.
+    Non-parseable v* tags are ignored for version comparison.
     """
-    all_v = _capture("git tag --list 'v*'")
+    all_v = list_tags("v*")
     if not all_v:
-        return True  # No tags yet, so the current tag is the highest
+        return True  # No tags yet -> current is highest by definition
 
-    # Get the latest tag in natural version order
-    latest = _capture("git tag --list 'v*' | sort -V | tail -n1")
-    print(f"[INFO] Latest tag: {latest}, Current tag: {tag}")
-    
-    # Ensure that the current tag is always considered the highest if it's the latest one
-    return tag >= latest  # Use comparison operator to consider all future tags
+    parsed_current = _parse_v_tag(tag)
+    if parsed_current is None:
+        # If the "current" tag isn't parseable, fall back to conservative behavior:
+        # treat it as highest only if it matches the max lexicographically.
+        latest_lex = max(all_v)
+        print(f"[INFO] Latest tag (lex): {latest_lex}, Current tag: {tag}")
+        return tag >= latest_lex
+
+    parsed_all: list[tuple[int, ...]] = []
+    for t in all_v:
+        parsed = _parse_v_tag(t)
+        if parsed is not None:
+            parsed_all.append(parsed)
+
+    if not parsed_all:
+        # No parseable tags -> nothing to compare against
+        return True
+
+    latest = max(parsed_all)
+    print(f"[INFO] Latest tag (parsed): v{'.'.join(map(str, latest))}, Current tag: {tag}")
+    return parsed_current >= latest
 
 
-def update_latest_tag(new_tag: str, preview: bool = False) -> None:
+def update_latest_tag(new_tag: str, *, preview: bool = False) -> None:
     """
     Move the floating 'latest' tag to the newly created release tag.
 
@@ -78,15 +95,10 @@ def update_latest_tag(new_tag: str, preview: bool = False) -> None:
     target_ref = f"{new_tag}^{{}}"
     print(f"[INFO] Updating 'latest' tag to point at {new_tag} (commit {target_ref})...")
 
-    if preview:
-        print(
-            f'[PREVIEW] Would run: git tag -f -a latest {target_ref} '
-            f'-m "Floating latest tag for {new_tag}"'
-        )
-        print("[PREVIEW] Would run: git push origin latest --force")
-        return
-
-    run_git_command(
-        f'git tag -f -a latest {target_ref} -m "Floating latest tag for {new_tag}"'
+    tag_force_annotated(
+        name="latest",
+        target=target_ref,
+        message=f"Floating latest tag for {new_tag}",
+        preview=preview,
     )
-    run_git_command("git push origin latest --force")
+    push("origin", "latest", force=True, preview=preview)

src/pkgmgr/actions/release/versioning.py

@@ -7,7 +7,7 @@ Version discovery and bumping helpers for the release workflow.
 
 from __future__ import annotations
 
-from pkgmgr.core.git import get_tags
+from pkgmgr.core.git.queries import get_tags
 from pkgmgr.core.version.semver import (
     SemVer,
     find_latest_version,

src/pkgmgr/actions/release/workflow.py

@@ -1,4 +1,3 @@
-# src/pkgmgr/actions/release/workflow.py
 from __future__ import annotations
 
 import os
@@ -6,7 +5,9 @@ import sys
 from typing import Optional
 
 from pkgmgr.actions.branch import close_branch
-from pkgmgr.core.git import get_current_branch, GitError
+from pkgmgr.core.git import GitError
+from pkgmgr.core.git.commands import add, commit, push, tag_annotated
+from pkgmgr.core.git.queries import get_current_branch
 from pkgmgr.core.repository.paths import resolve_repo_paths
 
 from .files import (
@@ -21,7 +22,6 @@ from .files import (
 from .git_ops import (
     ensure_clean_and_synced,
     is_highest_version_tag,
-    run_git_command,
     update_latest_tag,
 )
 from .prompts import confirm_proceed_release, should_delete_branch
@@ -126,12 +126,11 @@ def _release_impl(
     existing_files = [p for p in files_to_add if isinstance(p, str) and p and os.path.exists(p)]
 
     if preview:
-        for path in existing_files:
-            print(f"[PREVIEW] Would run: git add {path}")
-        print(f'[PREVIEW] Would run: git commit -am "{commit_msg}"')
-        print(f'[PREVIEW] Would run: git tag -a {new_tag} -m "{tag_msg}"')
-        print(f"[PREVIEW] Would run: git push origin {branch}")
-        print(f"[PREVIEW] Would run: git push origin {new_tag}")
+        add(existing_files, preview=True)
+        commit(commit_msg, all=True, preview=True)
+        tag_annotated(new_tag, tag_msg, preview=True)
+        push("origin", branch, preview=True)
+        push("origin", new_tag, preview=True)
 
         if is_highest_version_tag(new_tag):
             update_latest_tag(new_tag, preview=True)
@@ -145,15 +144,13 @@ def _release_impl(
                 print(f"[PREVIEW] Would ask whether to delete branch {branch} after release.")
         return
 
-    for path in existing_files:
-        run_git_command(f"git add {path}")
-
-    run_git_command(f'git commit -am "{commit_msg}"')
-    run_git_command(f'git tag -a {new_tag} -m "{tag_msg}"')
+    add(existing_files, preview=False)
+    commit(commit_msg, all=True, preview=False)
+    tag_annotated(new_tag, tag_msg, preview=False)
 
     # Push branch and ONLY the newly created version tag (no --tags)
-    run_git_command(f"git push origin {branch}")
-    run_git_command(f"git push origin {new_tag}")
+    push("origin", branch, preview=False)
+    push("origin", new_tag, preview=False)
 
     # Update 'latest' only if this is the highest version tag
     try:

src/pkgmgr/actions/repository/clone.py

@@ -1,103 +1,132 @@
-import subprocess
+from __future__ import annotations
+
 import os
+from typing import Any, Dict, List, Optional
+
+from pkgmgr.core.git.commands import clone as git_clone, GitCloneError
 from pkgmgr.core.repository.dir import get_repo_dir
 from pkgmgr.core.repository.identifier import get_repo_identifier
 from pkgmgr.core.repository.verify import verify_repository
 
+Repository = Dict[str, Any]
+
+
+def _build_clone_url(repo: Repository, clone_mode: str) -> Optional[str]:
+    provider = repo.get("provider")
+    account = repo.get("account")
+    name = repo.get("repository")
+    replacement = repo.get("replacement")
+
+    if clone_mode == "ssh":
+        if not provider or not account or not name:
+            return None
+        return f"git@{provider}:{account}/{name}.git"
+
+    if clone_mode in ("https", "shallow"):
+        if replacement:
+            return f"https://{replacement}.git"
+        if not provider or not account or not name:
+            return None
+        return f"https://{provider}/{account}/{name}.git"
+
+    return None
+
+
 def clone_repos(
-    selected_repos, 
-    repositories_base_dir: str, 
-    all_repos, 
-    preview: bool, 
-    no_verification: bool, 
-    clone_mode: str
-    ):
+    selected_repos: List[Repository],
+    repositories_base_dir: str,
+    all_repos: List[Repository],
+    preview: bool,
+    no_verification: bool,
+    clone_mode: str,
+) -> None:
     for repo in selected_repos:
         repo_identifier = get_repo_identifier(repo, all_repos)
         repo_dir = get_repo_dir(repositories_base_dir, repo)
+
         if os.path.exists(repo_dir):
-            print(f"[INFO] Repository '{repo_identifier}' already exists at '{repo_dir}'. Skipping clone.")
+            print(
+                f"[INFO] Repository '{repo_identifier}' already exists at '{repo_dir}'. Skipping clone."
+            )
             continue
 
         parent_dir = os.path.dirname(repo_dir)
         os.makedirs(parent_dir, exist_ok=True)
-        # Build clone URL based on the clone_mode
-        # Build clone URL based on the clone_mode
-        if clone_mode == "ssh":
-            clone_url = (
-                f"git@{repo.get('provider')}:"
-                f"{repo.get('account')}/"
-                f"{repo.get('repository')}.git"
-            )
-        elif clone_mode in ("https", "shallow"):
-            # Use replacement if defined, otherwise construct from provider/account/repository
-            if repo.get("replacement"):
-                clone_url = f"https://{repo.get('replacement')}.git"
-            else:
-                clone_url = (
-                    f"https://{repo.get('provider')}/"
-                    f"{repo.get('account')}/"
-                    f"{repo.get('repository')}.git"
-                )
-        else:
-            print(f"Unknown clone mode '{clone_mode}'. Aborting clone for {repo_identifier}.")
+
+        clone_url = _build_clone_url(repo, clone_mode)
+        if not clone_url:
+            print(f"[WARNING] Cannot build clone URL for '{repo_identifier}'. Skipping.")
             continue
 
-        # Build base clone command
-        base_clone_cmd = "git clone"
-        if clone_mode == "shallow":
-            # Shallow clone: only latest state via HTTPS, no full history
-            base_clone_cmd += " --depth 1 --single-branch"
+        shallow = clone_mode == "shallow"
+        mode_label = "HTTPS (shallow)" if shallow else clone_mode.upper()
 
-        mode_label = "HTTPS (shallow)" if clone_mode == "shallow" else clone_mode.upper()
         print(
             f"[INFO] Attempting to clone '{repo_identifier}' using {mode_label} "
             f"from {clone_url} into '{repo_dir}'."
         )
 
-        if preview:
-            print(f"[Preview] Would run: {base_clone_cmd} {clone_url} {repo_dir} in {parent_dir}")
-            result = subprocess.CompletedProcess(args=[], returncode=0)
-        else:
-            result = subprocess.run(
-                f"{base_clone_cmd} {clone_url} {repo_dir}",
+        try:
+            args = []
+            if shallow:
+                args += ["--depth", "1", "--single-branch"]
+            args += [clone_url, repo_dir]
+
+            git_clone(
+                args,
                 cwd=parent_dir,
-                shell=True,
+                preview=preview,
             )
-        
-        if result.returncode != 0:
-            # Only offer fallback if the original mode was SSH.
-            if clone_mode == "ssh":
-                print(f"[WARNING] SSH clone failed for '{repo_identifier}' with return code {result.returncode}.")
-                choice = input("Do you want to attempt HTTPS clone instead? (y/N): ").strip().lower()
-                if choice == 'y':
-                    # Attempt HTTPS clone
-                    if repo.get("replacement"):
-                        clone_url = f"https://{repo.get('replacement')}.git"
-                    else:
-                        clone_url = f"https://{repo.get('provider')}/{repo.get('account')}/{repo.get('repository')}.git"
-                    print(f"[INFO] Attempting to clone '{repo_identifier}' using HTTPS from {clone_url} into '{repo_dir}'.")
-                    if preview:
-                        print(f"[Preview] Would run: git clone {clone_url} {repo_dir} in {parent_dir}")
-                        result = subprocess.CompletedProcess(args=[], returncode=0)
-                    else:
-                        result = subprocess.run(f"git clone {clone_url} {repo_dir}", cwd=parent_dir, shell=True)
-                else:
-                    print(f"[INFO] HTTPS clone not attempted for '{repo_identifier}'.")
-                    continue
-            else:
-                # For https mode, do not attempt fallback.
-                print(f"[WARNING] HTTPS clone failed for '{repo_identifier}' with return code {result.returncode}.")
+
+        except GitCloneError as exc:
+            if clone_mode != "ssh":
+                print(f"[WARNING] Clone failed for '{repo_identifier}': {exc}")
                 continue
-        
-        # After cloning, perform verification in local mode.
+
+            print(f"[WARNING] SSH clone failed for '{repo_identifier}': {exc}")
+            choice = input("Do you want to attempt HTTPS clone instead? (y/N): ").strip().lower()
+            if choice != "y":
+                print(f"[INFO] HTTPS clone not attempted for '{repo_identifier}'.")
+                continue
+
+            fallback_url = _build_clone_url(repo, "https")
+            if not fallback_url:
+                print(f"[WARNING] Cannot build HTTPS URL for '{repo_identifier}'.")
+                continue
+
+            print(
+                f"[INFO] Attempting to clone '{repo_identifier}' using HTTPS "
+                f"from {fallback_url} into '{repo_dir}'."
+            )
+
+            try:
+                git_clone(
+                    [fallback_url, repo_dir],
+                    cwd=parent_dir,
+                    preview=preview,
+                )
+            except GitCloneError as exc2:
+                print(f"[WARNING] HTTPS clone failed for '{repo_identifier}': {exc2}")
+                continue
+
         verified_info = repo.get("verified")
-        if verified_info:
-            verified_ok, errors, commit_hash, signing_key = verify_repository(repo, repo_dir, mode="local", no_verification=no_verification)
-            if not no_verification and not verified_ok:
-                print(f"Warning: Verification failed for {repo_identifier} after cloning:")
-                for err in errors:
-                    print(f"  - {err}")
-                choice = input("Proceed anyway? (y/N): ").strip().lower()
-                if choice != "y":
-                    print(f"Skipping repository {repo_identifier} due to failed verification.")
+        if not verified_info:
+            continue
+
+        verified_ok, errors, _commit_hash, _signing_key = verify_repository(
+            repo,
+            repo_dir,
+            mode="local",
+            no_verification=no_verification,
+        )
+
+        if no_verification or verified_ok:
+            continue
+
+        print(f"Warning: Verification failed for {repo_identifier} after cloning:")
+        for err in errors:
+            print(f"  - {err}")
+
+        choice = input("Proceed anyway? (y/N): ").strip().lower()
+        if choice != "y":
+            print(f"Skipping repository {repo_identifier} due to failed verification.")

src/pkgmgr/actions/repository/create.py

@@ -1,257 +0,0 @@
-from __future__ import annotations
-
-import os
-import re
-import subprocess
-from dataclasses import dataclass
-from typing import Any, Dict, Optional, Tuple
-from urllib.parse import urlparse
-
-import yaml
-
-from pkgmgr.actions.mirror.io import write_mirrors_file
-from pkgmgr.actions.mirror.setup_cmd import setup_mirrors
-from pkgmgr.actions.repository.scaffold import render_default_templates
-from pkgmgr.core.command.alias import generate_alias
-from pkgmgr.core.config.save import save_user_config
-
-Repository = Dict[str, Any]
-
-_NAME_RE = re.compile(r"^[a-z0-9_-]+$")
-
-
-@dataclass(frozen=True)
-class RepoParts:
-    host: str
-    port: Optional[str]
-    owner: str
-    name: str
-
-
-def _run(cmd: str, cwd: str, preview: bool) -> None:
-    if preview:
-        print(f"[Preview] Would run in {cwd}: {cmd}")
-        return
-    subprocess.run(cmd, cwd=cwd, shell=True, check=True)
-
-
-def _git_get(key: str) -> str:
-    try:
-        out = subprocess.run(
-            f"git config --get {key}",
-            shell=True,
-            check=False,
-            capture_output=True,
-            text=True,
-        )
-        return (out.stdout or "").strip()
-    except Exception:
-        return ""
-
-
-def _split_host_port(host_with_port: str) -> Tuple[str, Optional[str]]:
-    if ":" in host_with_port:
-        host, port = host_with_port.split(":", 1)
-        return host, port or None
-    return host_with_port, None
-
-
-def _strip_git_suffix(name: str) -> str:
-    return name[:-4] if name.endswith(".git") else name
-
-
-def _parse_git_url(url: str) -> RepoParts:
-    if url.startswith("git@") and "://" not in url:
-        left, right = url.split(":", 1)
-        host = left.split("@", 1)[1]
-        path = right.lstrip("/")
-        owner, name = path.split("/", 1)
-        return RepoParts(host=host, port=None, owner=owner, name=_strip_git_suffix(name))
-
-    parsed = urlparse(url)
-    host = (parsed.hostname or "").strip()
-    port = str(parsed.port) if parsed.port else None
-    path = (parsed.path or "").strip("/")
-
-    if not host or not path or "/" not in path:
-        raise ValueError(f"Could not parse git URL: {url}")
-
-    owner, name = path.split("/", 1)
-    return RepoParts(host=host, port=port, owner=owner, name=_strip_git_suffix(name))
-
-
-def _parse_identifier(identifier: str) -> RepoParts:
-    ident = identifier.strip()
-
-    if "://" in ident or ident.startswith("git@"):
-        return _parse_git_url(ident)
-
-    parts = ident.split("/")
-    if len(parts) != 3:
-        raise ValueError("Identifier must be URL or 'provider(:port)/owner/repo'.")
-
-    host_with_port, owner, name = parts
-    host, port = _split_host_port(host_with_port)
-    return RepoParts(host=host, port=port, owner=owner, name=name)
-
-
-def _ensure_valid_repo_name(name: str) -> None:
-    if not name or not _NAME_RE.fullmatch(name):
-        raise ValueError("Repository name must match: lowercase a-z, 0-9, '_' and '-'.")
-
-
-def _repo_homepage(host: str, owner: str, name: str) -> str:
-    return f"https://{host}/{owner}/{name}"
-
-
-def _build_default_primary_url(parts: RepoParts) -> str:
-    if parts.port:
-        return f"ssh://git@{parts.host}:{parts.port}/{parts.owner}/{parts.name}.git"
-    return f"git@{parts.host}:{parts.owner}/{parts.name}.git"
-
-
-def _write_default_mirrors(repo_dir: str, primary: str, name: str, preview: bool) -> None:
-    mirrors = {"origin": primary, "pypi": f"https://pypi.org/project/{name}/"}
-    write_mirrors_file(repo_dir, mirrors, preview=preview)
-
-
-def _git_init_and_initial_commit(repo_dir: str, preview: bool) -> None:
-    _run("git init", cwd=repo_dir, preview=preview)
-    _run("git add -A", cwd=repo_dir, preview=preview)
-
-    if preview:
-        print(f'[Preview] Would run in {repo_dir}: git commit -m "Initial commit"')
-        return
-
-    subprocess.run('git commit -m "Initial commit"', cwd=repo_dir, shell=True, check=False)
-
-
-def _git_push_main_or_master(repo_dir: str, preview: bool) -> None:
-    _run("git branch -M main", cwd=repo_dir, preview=preview)
-    try:
-        _run("git push -u origin main", cwd=repo_dir, preview=preview)
-        return
-    except subprocess.CalledProcessError:
-        pass
-
-    try:
-        _run("git branch -M master", cwd=repo_dir, preview=preview)
-        _run("git push -u origin master", cwd=repo_dir, preview=preview)
-    except subprocess.CalledProcessError as exc:
-        print(f"[WARN] Push failed: {exc}")
-
-
-def create_repo(
-    identifier: str,
-    config_merged: Dict[str, Any],
-    user_config_path: str,
-    bin_dir: str,
-    *,
-    remote: bool = False,
-    preview: bool = False,
-) -> None:
-    parts = _parse_identifier(identifier)
-    _ensure_valid_repo_name(parts.name)
-
-    directories = config_merged.get("directories") or {}
-    base_dir = os.path.expanduser(str(directories.get("repositories", "~/Repositories")))
-    repo_dir = os.path.join(base_dir, parts.host, parts.owner, parts.name)
-
-    author_name = _git_get("user.name") or "Unknown Author"
-    author_email = _git_get("user.email") or "unknown@example.invalid"
-
-    homepage = _repo_homepage(parts.host, parts.owner, parts.name)
-    primary_url = _build_default_primary_url(parts)
-
-    repositories = config_merged.get("repositories") or []
-    exists = any(
-        (
-            r.get("provider") == parts.host
-            and r.get("account") == parts.owner
-            and r.get("repository") == parts.name
-        )
-        for r in repositories
-    )
-
-    if not exists:
-        new_entry: Repository = {
-            "provider": parts.host,
-            "port": parts.port,
-            "account": parts.owner,
-            "repository": parts.name,
-            "homepage": homepage,
-            "alias": generate_alias(
-                {"repository": parts.name, "provider": parts.host, "account": parts.owner},
-                bin_dir,
-                existing_aliases=set(),
-            ),
-            "verified": {},
-        }
-
-        if os.path.exists(user_config_path):
-            with open(user_config_path, "r", encoding="utf-8") as f:
-                user_config = yaml.safe_load(f) or {}
-        else:
-            user_config = {"repositories": []}
-
-        user_config.setdefault("repositories", [])
-        user_config["repositories"].append(new_entry)
-
-        if preview:
-            print(f"[Preview] Would save user config: {user_config_path}")
-        else:
-            save_user_config(user_config, user_config_path)
-
-        config_merged.setdefault("repositories", []).append(new_entry)
-        repo = new_entry
-        print(f"[INFO] Added repository to configuration: {parts.host}/{parts.owner}/{parts.name}")
-    else:
-        repo = next(
-            r
-            for r in repositories
-            if (
-                r.get("provider") == parts.host
-                and r.get("account") == parts.owner
-                and r.get("repository") == parts.name
-            )
-        )
-        print(f"[INFO] Repository already in configuration: {parts.host}/{parts.owner}/{parts.name}")
-
-    if preview:
-        print(f"[Preview] Would ensure directory exists: {repo_dir}")
-    else:
-        os.makedirs(repo_dir, exist_ok=True)
-
-    tpl_context = {
-        "provider": parts.host,
-        "port": parts.port,
-        "account": parts.owner,
-        "repository": parts.name,
-        "homepage": homepage,
-        "author_name": author_name,
-        "author_email": author_email,
-        "license_text": f"All rights reserved by {author_name}",
-        "primary_remote": primary_url,
-    }
-
-    render_default_templates(repo_dir, context=tpl_context, preview=preview)
-    _git_init_and_initial_commit(repo_dir, preview=preview)
-
-    _write_default_mirrors(repo_dir, primary=primary_url, name=parts.name, preview=preview)
-
-    repo.setdefault("mirrors", {})
-    repo["mirrors"].setdefault("origin", primary_url)
-    repo["mirrors"].setdefault("pypi", f"https://pypi.org/project/{parts.name}/")
-
-    setup_mirrors(
-        selected_repos=[repo],
-        repositories_base_dir=base_dir,
-        all_repos=config_merged.get("repositories", []),
-        preview=preview,
-        local=True,
-        remote=True,
-        ensure_remote=bool(remote),
-    )
-
-    if remote:
-        _git_push_main_or_master(repo_dir, preview=preview)

src/pkgmgr/actions/repository/create/__init__.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from .service import CreateRepoService
+
+RepositoryConfig = Dict[str, Any]
+
+__all__ = [
+    "CreateRepoService",
+    "create_repo",
+]
+
+
+def create_repo(
+    identifier: str,
+    config_merged: RepositoryConfig,
+    user_config_path: str,
+    bin_dir: str,
+    *,
+    remote: bool = False,
+    preview: bool = False,
+) -> None:
+    CreateRepoService(
+        config_merged=config_merged,
+        user_config_path=user_config_path,
+        bin_dir=bin_dir,
+    ).run(identifier=identifier, preview=preview, remote=remote)

src/pkgmgr/actions/repository/create/config_writer.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import os
+from typing import Dict, Any, Set
+
+import yaml
+
+from pkgmgr.core.command.alias import generate_alias
+from pkgmgr.core.config.save import save_user_config
+
+Repository = Dict[str, Any]
+
+
+class ConfigRepoWriter:
+    def __init__(
+        self,
+        *,
+        config_merged: Dict[str, Any],
+        user_config_path: str,
+        bin_dir: str,
+    ):
+        self.config_merged = config_merged
+        self.user_config_path = user_config_path
+        self.bin_dir = bin_dir
+
+    def ensure_repo_entry(
+        self,
+        *,
+        host: str,
+        port: str | None,
+        owner: str,
+        name: str,
+        homepage: str,
+        preview: bool,
+    ) -> Repository:
+        repositories = self.config_merged.setdefault("repositories", [])
+
+        for repo in repositories:
+            if (
+                repo.get("provider") == host
+                and repo.get("account") == owner
+                and repo.get("repository") == name
+            ):
+                return repo
+
+        existing_aliases: Set[str] = {
+            str(r.get("alias")) for r in repositories if r.get("alias")
+        }
+
+        repo: Repository = {
+            "provider": host,
+            "port": port,
+            "account": owner,
+            "repository": name,
+            "homepage": homepage,
+            "alias": generate_alias(
+                {
+                    "repository": name,
+                    "provider": host,
+                    "account": owner,
+                },
+                self.bin_dir,
+                existing_aliases=existing_aliases,
+            ),
+            "verified": {},
+        }
+
+        if preview:
+            print(f"[Preview] Would add repository to config: {repo}")
+            return repo
+
+        if os.path.exists(self.user_config_path):
+            with open(self.user_config_path, "r", encoding="utf-8") as f:
+                user_cfg = yaml.safe_load(f) or {}
+        else:
+            user_cfg = {}
+
+        user_cfg.setdefault("repositories", []).append(repo)
+        save_user_config(user_cfg, self.user_config_path)
+
+        repositories.append(repo)
+        print(f"[INFO] Added repository to configuration: {host}/{owner}/{name}")
+
+        return repo

src/pkgmgr/actions/repository/create/git_bootstrap.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from pkgmgr.core.git.commands import (
+    GitCommitError,
+    GitPushUpstreamError,
+    add_all,
+    branch_move,
+    commit,
+    init,
+    push_upstream,
+)
+
+
+class GitBootstrapper:
+    def init_repo(self, repo_dir: str, preview: bool) -> None:
+        init(cwd=repo_dir, preview=preview)
+        add_all(cwd=repo_dir, preview=preview)
+        try:
+            commit("Initial commit", cwd=repo_dir, preview=preview)
+        except GitCommitError as exc:
+            print(f"[WARN] Initial commit failed (continuing): {exc}")
+
+    def push_default_branch(self, repo_dir: str, preview: bool) -> None:
+        try:
+            branch_move("main", cwd=repo_dir, preview=preview)
+            push_upstream("origin", "main", cwd=repo_dir, preview=preview)
+            return
+        except GitPushUpstreamError:
+            pass
+
+        try:
+            branch_move("master", cwd=repo_dir, preview=preview)
+            push_upstream("origin", "master", cwd=repo_dir, preview=preview)
+        except GitPushUpstreamError as exc:
+            print(f"[WARN] Push failed: {exc}")

src/pkgmgr/actions/repository/create/mirrors.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from pkgmgr.actions.mirror.io import write_mirrors_file
+from pkgmgr.actions.mirror.setup_cmd import setup_mirrors
+
+Repository = Dict[str, Any]
+
+
+class MirrorBootstrapper:
+    """
+    MIRRORS is the single source of truth.
+
+    We write defaults to MIRRORS and then call mirror setup which will
+    configure git remotes based on MIRRORS content (but only for git URLs).
+    """
+
+    def write_defaults(
+        self,
+        *,
+        repo_dir: str,
+        primary: str,
+        name: str,
+        preview: bool,
+    ) -> None:
+        mirrors = {
+            # preferred SSH url is supplied by CreateRepoPlanner.primary_remote
+            "origin": primary,
+            # metadata only: must NEVER be configured as a git remote
+            "pypi": f"https://pypi.org/project/{name}/",
+        }
+        write_mirrors_file(repo_dir, mirrors, preview=preview)
+
+    def setup(
+        self,
+        *,
+        repo: Repository,
+        repositories_base_dir: str,
+        all_repos: list[Repository],
+        preview: bool,
+        remote: bool,
+    ) -> None:
+        # IMPORTANT: do NOT set repo["mirrors"] here.
+        # MIRRORS file is the single source of truth.
+        setup_mirrors(
+            selected_repos=[repo],
+            repositories_base_dir=repositories_base_dir,
+            all_repos=all_repos,
+            preview=preview,
+            local=True,
+            remote=True,
+            ensure_remote=remote,
+        )

src/pkgmgr/actions/repository/create/model.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class RepoParts:
+    host: str
+    port: Optional[str]
+    owner: str
+    name: str

src/pkgmgr/actions/repository/create/parser.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import re
+from typing import Tuple
+from urllib.parse import urlparse
+
+from .model import RepoParts
+
+_NAME_RE = re.compile(r"^[a-z0-9_-]+$")
+
+
+def parse_identifier(identifier: str) -> RepoParts:
+    ident = identifier.strip()
+
+    if "://" in ident or ident.startswith("git@"):
+        return _parse_git_url(ident)
+
+    parts = ident.split("/")
+    if len(parts) != 3:
+        raise ValueError("Identifier must be URL or 'provider(:port)/owner/repo'.")
+
+    host_with_port, owner, name = parts
+    host, port = _split_host_port(host_with_port)
+    _ensure_valid_repo_name(name)
+
+    return RepoParts(host=host, port=port, owner=owner, name=name)
+
+
+def _parse_git_url(url: str) -> RepoParts:
+    if url.startswith("git@") and "://" not in url:
+        left, right = url.split(":", 1)
+        host = left.split("@", 1)[1]
+        owner, name = right.lstrip("/").split("/", 1)
+        name = _strip_git_suffix(name)
+        _ensure_valid_repo_name(name)
+        return RepoParts(host=host, port=None, owner=owner, name=name)
+
+    parsed = urlparse(url)
+    host = parsed.hostname or ""
+    port = str(parsed.port) if parsed.port else None
+    path = (parsed.path or "").strip("/")
+
+    if not host or "/" not in path:
+        raise ValueError(f"Could not parse git URL: {url}")
+
+    owner, name = path.split("/", 1)
+    name = _strip_git_suffix(name)
+    _ensure_valid_repo_name(name)
+
+    return RepoParts(host=host, port=port, owner=owner, name=name)
+
+
+def _split_host_port(host: str) -> Tuple[str, str | None]:
+    if ":" in host:
+        h, p = host.split(":", 1)
+        return h, p or None
+    return host, None
+
+
+def _strip_git_suffix(name: str) -> str:
+    return name[:-4] if name.endswith(".git") else name
+
+
+def _ensure_valid_repo_name(name: str) -> None:
+    if not _NAME_RE.fullmatch(name):
+        raise ValueError(
+            "Repository name must match: lowercase a-z, 0-9, '_' and '-'."
+        )

src/pkgmgr/actions/repository/create/planner.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import os
+from typing import Dict, Any
+
+from .model import RepoParts
+
+
+class CreateRepoPlanner:
+    def __init__(self, parts: RepoParts, repositories_base_dir: str):
+        self.parts = parts
+        self.repositories_base_dir = os.path.expanduser(repositories_base_dir)
+
+    @property
+    def repo_dir(self) -> str:
+        return os.path.join(
+            self.repositories_base_dir,
+            self.parts.host,
+            self.parts.owner,
+            self.parts.name,
+        )
+
+    @property
+    def homepage(self) -> str:
+        return f"https://{self.parts.host}/{self.parts.owner}/{self.parts.name}"
+
+    @property
+    def primary_remote(self) -> str:
+        if self.parts.port:
+            return (
+                f"ssh://git@{self.parts.host}:{self.parts.port}/"
+                f"{self.parts.owner}/{self.parts.name}.git"
+            )
+        return f"git@{self.parts.host}:{self.parts.owner}/{self.parts.name}.git"
+
+    def template_context(
+        self,
+        *,
+        author_name: str,
+        author_email: str,
+    ) -> Dict[str, Any]:
+        return {
+            "provider": self.parts.host,
+            "port": self.parts.port,
+            "account": self.parts.owner,
+            "repository": self.parts.name,
+            "homepage": self.homepage,
+            "author_name": author_name,
+            "author_email": author_email,
+            "license_text": f"All rights reserved by {author_name}",
+            "primary_remote": self.primary_remote,
+        }

src/pkgmgr/actions/repository/create/service.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import os
+from typing import Dict, Any
+
+from pkgmgr.core.git.queries import get_config_value
+
+from .parser import parse_identifier
+from .planner import CreateRepoPlanner
+from .config_writer import ConfigRepoWriter
+from .templates import TemplateRenderer
+from .git_bootstrap import GitBootstrapper
+from .mirrors import MirrorBootstrapper
+
+
+class CreateRepoService:
+    def __init__(
+        self,
+        *,
+        config_merged: Dict[str, Any],
+        user_config_path: str,
+        bin_dir: str,
+    ):
+        self.config_merged = config_merged
+        self.user_config_path = user_config_path
+        self.bin_dir = bin_dir
+
+        self.templates = TemplateRenderer()
+        self.git = GitBootstrapper()
+        self.mirrors = MirrorBootstrapper()
+
+    def run(
+        self,
+        *,
+        identifier: str,
+        preview: bool,
+        remote: bool,
+    ) -> None:
+        parts = parse_identifier(identifier)
+
+        base_dir = self.config_merged.get("directories", {}).get(
+            "repositories", "~/Repositories"
+        )
+
+        planner = CreateRepoPlanner(parts, base_dir)
+
+        writer = ConfigRepoWriter(
+            config_merged=self.config_merged,
+            user_config_path=self.user_config_path,
+            bin_dir=self.bin_dir,
+        )
+
+        repo = writer.ensure_repo_entry(
+            host=parts.host,
+            port=parts.port,
+            owner=parts.owner,
+            name=parts.name,
+            homepage=planner.homepage,
+            preview=preview,
+        )
+
+        if preview:
+            print(f"[Preview] Would ensure directory exists: {planner.repo_dir}")
+        else:
+            os.makedirs(planner.repo_dir, exist_ok=True)
+
+        author_name = get_config_value("user.name") or "Unknown Author"
+        author_email = get_config_value("user.email") or "unknown@example.invalid"
+
+        self.templates.render(
+            repo_dir=planner.repo_dir,
+            context=planner.template_context(
+                author_name=author_name,
+                author_email=author_email,
+            ),
+            preview=preview,
+        )
+
+        self.git.init_repo(planner.repo_dir, preview=preview)
+
+        self.mirrors.write_defaults(
+            repo_dir=planner.repo_dir,
+            primary=planner.primary_remote,
+            name=parts.name,
+            preview=preview,
+        )
+
+        self.mirrors.setup(
+            repo=repo,
+            repositories_base_dir=os.path.expanduser(base_dir),
+            all_repos=self.config_merged.get("repositories", []),
+            preview=preview,
+            remote=remote,
+        )
+
+        if remote:
+            self.git.push_default_branch(planner.repo_dir, preview=preview)

src/pkgmgr/actions/repository/create/templates.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Dict, Any
+
+from pkgmgr.core.git.queries import get_repo_root
+
+try:
+    from jinja2 import Environment, FileSystemLoader, StrictUndefined
+except Exception as exc:  # pragma: no cover
+    Environment = None  # type: ignore
+    FileSystemLoader = None  # type: ignore
+    StrictUndefined = None  # type: ignore
+    _JINJA_IMPORT_ERROR = exc
+else:
+    _JINJA_IMPORT_ERROR = None
+
+
+class TemplateRenderer:
+    def __init__(self) -> None:
+        self.templates_dir = self._resolve_templates_dir()
+
+    def render(
+        self,
+        *,
+        repo_dir: str,
+        context: Dict[str, Any],
+        preview: bool,
+    ) -> None:
+        if preview:
+            self._preview()
+            return
+
+        if Environment is None:
+            raise RuntimeError(
+                "Jinja2 is required but not available. "
+                f"Import error: {_JINJA_IMPORT_ERROR}"
+            )
+
+        env = Environment(
+            loader=FileSystemLoader(self.templates_dir),
+            undefined=StrictUndefined,
+            autoescape=False,
+            keep_trailing_newline=True,
+        )
+
+        for root, _, files in os.walk(self.templates_dir):
+            for fn in files:
+                if not fn.endswith(".j2"):
+                    continue
+
+                abs_src = os.path.join(root, fn)
+                rel_src = os.path.relpath(abs_src, self.templates_dir)
+                rel_out = rel_src[:-3]
+                abs_out = os.path.join(repo_dir, rel_out)
+
+                os.makedirs(os.path.dirname(abs_out), exist_ok=True)
+                template = env.get_template(rel_src)
+                rendered = template.render(**context)
+
+                with open(abs_out, "w", encoding="utf-8") as f:
+                    f.write(rendered)
+
+    def _preview(self) -> None:
+        for root, _, files in os.walk(self.templates_dir):
+            for fn in files:
+                if fn.endswith(".j2"):
+                    rel = os.path.relpath(
+                        os.path.join(root, fn), self.templates_dir
+                    )
+                    print(f"[Preview] Would render template: {rel} -> {rel[:-3]}")
+
+    @staticmethod
+    def _resolve_templates_dir() -> str:
+        here = Path(__file__).resolve().parent
+        root = get_repo_root(cwd=str(here))
+        if not root:
+            raise RuntimeError("Could not determine repository root for templates.")
+        return os.path.join(root, "templates", "default")

src/pkgmgr/actions/repository/pull.py

@@ -1,25 +1,30 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
+from __future__ import annotations
 
 import os
-import subprocess
 import sys
+from typing import List, Dict, Any
 
+from pkgmgr.core.git.commands import pull_args, GitPullArgsError
 from pkgmgr.core.repository.dir import get_repo_dir
 from pkgmgr.core.repository.identifier import get_repo_identifier
 from pkgmgr.core.repository.verify import verify_repository
 
+Repository = Dict[str, Any]
+
 
 def pull_with_verification(
-    selected_repos,
-    repositories_base_dir,
-    all_repos,
-    extra_args,
-    no_verification,
+    selected_repos: List[Repository],
+    repositories_base_dir: str,
+    all_repos: List[Repository],
+    extra_args: List[str],
+    no_verification: bool,
     preview: bool,
 ) -> None:
     """
     Execute `git pull` for each repository with verification.
+
+    - If verification fails and verification is enabled, prompt user to continue.
+    - Uses core.git.commands.pull_args() (no raw subprocess usage).
     """
     for repo in selected_repos:
         repo_identifier = get_repo_identifier(repo, all_repos)
@@ -37,12 +42,7 @@ def pull_with_verification(
             no_verification=no_verification,
         )
 
-        if (
-            not preview
-            and not no_verification
-            and verified_info
-            and not verified_ok
-        ):
+        if not preview and not no_verification and verified_info and not verified_ok:
             print(f"Warning: Verification failed for {repo_identifier}:")
             for err in errors:
                 print(f"  - {err}")
@@ -50,17 +50,10 @@ def pull_with_verification(
             if choice != "y":
                 continue
 
-        args_part = " ".join(extra_args) if extra_args else ""
-        full_cmd = f"git pull{(' ' + args_part) if args_part else ''}"
-
-        if preview:
-            print(f"[Preview] In '{repo_dir}': {full_cmd}")
-        else:
-            print(f"Running in '{repo_dir}': {full_cmd}")
-            result = subprocess.run(full_cmd, cwd=repo_dir, shell=True, check=False)
-            if result.returncode != 0:
-                print(
-                    f"'git pull' for {repo_identifier} failed "
-                    f"with exit code {result.returncode}."
-                )
-                sys.exit(result.returncode)
+        try:
+            pull_args(extra_args, cwd=repo_dir, preview=preview)
+        except GitPullArgsError as exc:
+            # Keep behavior consistent with previous implementation:
+            # stop on first failure and propagate return code as generic failure.
+            print(str(exc))
+            sys.exit(1)

src/pkgmgr/actions/repository/scaffold.py

@@ -1,105 +0,0 @@
-from __future__ import annotations
-
-import os
-import subprocess
-from pathlib import Path
-from typing import Any, Dict, Optional
-
-try:
-    from jinja2 import Environment, FileSystemLoader, StrictUndefined
-except Exception as exc:  # pragma: no cover
-    Environment = None  # type: ignore[assignment]
-    FileSystemLoader = None  # type: ignore[assignment]
-    StrictUndefined = None  # type: ignore[assignment]
-    _JINJA_IMPORT_ERROR = exc
-else:
-    _JINJA_IMPORT_ERROR = None
-
-
-def _repo_root_from_here(anchor: Optional[Path] = None) -> str:
-    """
-    Prefer git root (robust in editable installs / different layouts).
-    Fallback to a conservative relative parent lookup.
-    """
-    here = (anchor or Path(__file__)).resolve().parent
-    try:
-        r = subprocess.run(
-            ["git", "rev-parse", "--show-toplevel"],
-            cwd=str(here),
-            check=False,
-            capture_output=True,
-            text=True,
-        )
-        if r.returncode == 0:
-            top = (r.stdout or "").strip()
-            if top:
-                return top
-    except Exception:
-        pass
-
-    # Fallback: src/pkgmgr/actions/repository/scaffold.py -> <repo root> = parents[5]
-    p = (anchor or Path(__file__)).resolve()
-    if len(p.parents) < 6:
-        raise RuntimeError(f"Unexpected path depth for: {p}")
-    return str(p.parents[5])
-
-
-def _templates_dir() -> str:
-    return os.path.join(_repo_root_from_here(), "templates", "default")
-
-
-def render_default_templates(
-    repo_dir: str,
-    *,
-    context: Dict[str, Any],
-    preview: bool,
-) -> None:
-    """
-    Render templates/default/*.j2 into repo_dir.
-    Keeps create.py clean: create.py calls this function only.
-    """
-    tpl_dir = _templates_dir()
-    if not os.path.isdir(tpl_dir):
-        raise RuntimeError(f"Templates directory not found: {tpl_dir}")
-
-    # Preview mode: do not require Jinja2 at all. We only print planned outputs.
-    if preview:
-        for root, _, files in os.walk(tpl_dir):
-            for fn in files:
-                if not fn.endswith(".j2"):
-                    continue
-                abs_src = os.path.join(root, fn)
-                rel_src = os.path.relpath(abs_src, tpl_dir)
-                rel_out = rel_src[:-3]
-                print(f"[Preview] Would render template: {rel_src} -> {rel_out}")
-        return
-
-    if Environment is None or FileSystemLoader is None or StrictUndefined is None:
-        raise RuntimeError(
-            "Jinja2 is required for repo templates but is not available. "
-            f"Import error: {_JINJA_IMPORT_ERROR}"
-        )
-
-    env = Environment(
-        loader=FileSystemLoader(tpl_dir),
-        undefined=StrictUndefined,
-        autoescape=False,
-        keep_trailing_newline=True,
-    )
-
-    for root, _, files in os.walk(tpl_dir):
-        for fn in files:
-            if not fn.endswith(".j2"):
-                continue
-
-            abs_src = os.path.join(root, fn)
-            rel_src = os.path.relpath(abs_src, tpl_dir)
-            rel_out = rel_src[:-3]
-            abs_out = os.path.join(repo_dir, rel_out)
-
-            os.makedirs(os.path.dirname(abs_out), exist_ok=True)
-            template = env.get_template(rel_src)
-            rendered = template.render(**context)
-
-            with open(abs_out, "w", encoding="utf-8") as f:
-                f.write(rendered)

src/pkgmgr/cli/commands/changelog.py

@@ -7,7 +7,7 @@ from typing import Any, Dict, List, Optional, Tuple
 from pkgmgr.cli.context import CLIContext
 from pkgmgr.core.repository.dir import get_repo_dir
 from pkgmgr.core.repository.identifier import get_repo_identifier
-from pkgmgr.core.git import get_tags
+from pkgmgr.core.git.queries import get_tags
 from pkgmgr.core.version.semver import extract_semver_from_tags
 from pkgmgr.actions.changelog import generate_changelog
 

src/pkgmgr/cli/commands/version.py

@@ -7,7 +7,7 @@ from typing import Any, Dict, List, Optional, Tuple
 from pkgmgr.cli.context import CLIContext
 from pkgmgr.core.repository.dir import get_repo_dir
 from pkgmgr.core.repository.identifier import get_repo_identifier
-from pkgmgr.core.git import get_tags
+from pkgmgr.core.git.queries import get_tags
 from pkgmgr.core.version.semver import SemVer, find_latest_version
 from pkgmgr.core.version.installed import (
     get_installed_python_version,

src/pkgmgr/core/credentials/__init__.py

@@ -1,4 +1,3 @@
-# src/pkgmgr/core/credentials/__init__.py
 """Credential resolution for provider APIs."""
 
 from .resolver import ResolutionOptions, TokenResolver

src/pkgmgr/core/credentials/providers/__init__.py

@@ -3,9 +3,11 @@
 from .env import EnvTokenProvider
 from .keyring import KeyringTokenProvider
 from .prompt import PromptTokenProvider
+from .gh import GhTokenProvider
 
 __all__ = [
     "EnvTokenProvider",
     "KeyringTokenProvider",
     "PromptTokenProvider",
+    "GhTokenProvider",
 ]

src/pkgmgr/core/credentials/providers/gh.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import shutil
+import subprocess
+from dataclasses import dataclass
+from typing import Optional
+
+from ..types import TokenRequest, TokenResult
+
+
+@dataclass(frozen=True)
+class GhTokenProvider:
+    """
+    Resolve a GitHub token via GitHub CLI (`gh auth token`).
+
+    This does NOT persist anything; it only reads what `gh` already knows.
+    """
+    source_name: str = "gh"
+
+    def get(self, request: TokenRequest) -> Optional[TokenResult]:
+        # Only meaningful for GitHub-like providers
+        kind = (request.provider_kind or "").strip().lower()
+        if kind not in ("github", "github.com"):
+            return None
+
+        if not shutil.which("gh"):
+            return None
+
+        host = (request.host or "").strip() or "github.com"
+
+        try:
+            out = subprocess.check_output(
+                ["gh", "auth", "token", "--hostname", host],
+                stderr=subprocess.STDOUT,
+                text=True,
+            ).strip()
+        except Exception:
+            return None
+
+        if not out:
+            return None
+
+        return TokenResult(token=out, source=self.source_name)

src/pkgmgr/core/credentials/resolver.py

@@ -6,9 +6,11 @@ from dataclasses import dataclass
 from typing import Optional
 
 from .providers.env import EnvTokenProvider
+from .providers.gh import GhTokenProvider
 from .providers.keyring import KeyringTokenProvider
 from .providers.prompt import PromptTokenProvider
 from .types import KeyringUnavailableError, NoCredentialsError, TokenRequest, TokenResult
+from .validate import validate_token
 
 
 @dataclass(frozen=True)
@@ -21,10 +23,24 @@ class ResolutionOptions:
 
 
 class TokenResolver:
-    """Resolve tokens from multiple sources (ENV -> Keyring -> Prompt)."""
+    """
+    Resolve tokens for provider APIs using the following policy:
+
+    0) ENV (explicit user intent) -> return as-is (do NOT persist)
+    1) GitHub CLI (gh)            -> if available and token validates, return
+    2) Keyring                    -> if token validates, return; if invalid and
+                                    interactive prompting is allowed, prompt and
+                                    OVERWRITE the keyring entry
+    3) Prompt                     -> prompt and (optionally) store in keyring
+
+    Notes:
+    - Keyring requires python-keyring.
+    - Token validation is provider-specific (currently GitHub cloud).
+    """
 
     def __init__(self) -> None:
         self._env = EnvTokenProvider()
+        self._gh = GhTokenProvider()
         self._keyring = KeyringTokenProvider()
         self._prompt = PromptTokenProvider()
         self._warned_keyring: bool = False
@@ -48,6 +64,33 @@ class TokenResolver:
         print("         sudo dnf install python3-keyring", file=sys.stderr)
         print("", file=sys.stderr)
 
+    def _prompt_and_maybe_store(
+        self,
+        request: TokenRequest,
+        opts: ResolutionOptions,
+    ) -> Optional[TokenResult]:
+        """
+        Prompt for a token and optionally store it in keyring.
+        If keyring is unavailable, still return the token for this run.
+        """
+        if not (opts.interactive and opts.allow_prompt):
+            return None
+
+        prompt_res = self._prompt.get(request)
+        if not prompt_res:
+            return None
+
+        if opts.save_prompt_token_to_keyring:
+            try:
+                self._keyring.set(request, prompt_res.token)  # overwrite is fine
+            except KeyringUnavailableError as exc:
+                self._warn_keyring_unavailable(exc)
+            except Exception:
+                # If keyring cannot store, still use token for this run.
+                pass
+
+        return prompt_res
+
     def get_token(
         self,
         provider_kind: str,
@@ -58,16 +101,29 @@ class TokenResolver:
         opts = options or ResolutionOptions()
         request = TokenRequest(provider_kind=provider_kind, host=host, owner=owner)
 
-        # 1) ENV
+        # 0) ENV (highest priority; explicit user intent)
         env_res = self._env.get(request)
         if env_res:
+            # Do NOT validate or persist env tokens automatically.
             return env_res
 
-        # 2) Keyring
+        # 1) GitHub CLI (gh) (auto-read; validate)
+        gh_res = self._gh.get(request)
+        if gh_res and validate_token(request.provider_kind, request.host, gh_res.token):
+            return gh_res
+
+        # 2) Keyring (validate; if invalid -> prompt + overwrite)
         try:
             kr_res = self._keyring.get(request)
             if kr_res:
-                return kr_res
+                if validate_token(request.provider_kind, request.host, kr_res.token):
+                    return kr_res
+
+                # Token exists but seems invalid -> re-prompt and overwrite keyring.
+                renewed = self._prompt_and_maybe_store(request, opts)
+                if renewed:
+                    return renewed
+
         except KeyringUnavailableError as exc:
             # Show a helpful warning once, then continue (prompt fallback).
             self._warn_keyring_unavailable(exc)
@@ -76,21 +132,12 @@ class TokenResolver:
             pass
 
         # 3) Prompt (optional)
-        if opts.interactive and opts.allow_prompt:
-            prompt_res = self._prompt.get(request)
-            if prompt_res:
-                if opts.save_prompt_token_to_keyring:
-                    try:
-                        self._keyring.set(request, prompt_res.token)
-                    except KeyringUnavailableError as exc:
-                        self._warn_keyring_unavailable(exc)
-                    except Exception:
-                        # If keyring cannot store, still use token for this run.
-                        pass
-                return prompt_res
+        prompt_res = self._prompt_and_maybe_store(request, opts)
+        if prompt_res:
+            return prompt_res
 
         raise NoCredentialsError(
             f"No token available for {provider_kind}@{host}"
             + (f" (owner: {owner})" if owner else "")
-            + ". Provide it via environment variable or keyring."
+            + ". Provide it via environment variable, keyring, or gh auth."
         )

src/pkgmgr/core/credentials/store_keys.py

@@ -44,6 +44,7 @@ def env_var_candidates(provider_kind: str, host: str, owner: Optional[str]) -> l
     candidates.append(f"PKGMGR_{kind}_TOKEN")
     candidates.append(f"PKGMGR_TOKEN_{kind}")
     candidates.append("PKGMGR_TOKEN")
+    
     return candidates
 
 

src/pkgmgr/core/credentials/validate.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import urllib.request
+import json
+
+
+def validate_token(provider_kind: str, host: str, token: str) -> bool:
+    """
+    Return True if token appears valid for the provider.
+    Currently implemented for GitHub only.
+    """
+    kind = (provider_kind or "").strip().lower()
+    host = (host or "").strip() or "github.com"
+    token = (token or "").strip()
+    if not token:
+        return False
+
+    if kind in ("github", "github.com") and host.lower() == "github.com":
+        req = urllib.request.Request(
+            "https://api.github.com/user",
+            headers={
+                "Authorization": f"Bearer {token}",
+                "Accept": "application/vnd.github+json",
+                "User-Agent": "pkgmgr",
+            },
+            method="GET",
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=10) as resp:
+                if resp.status != 200:
+                    return False
+                # Optional: parse to ensure body is JSON
+                _ = json.loads(resp.read().decode("utf-8"))
+                return True
+        except Exception:
+            return False
+
+    # Unknown provider: don't hard-fail validation (conservative default)
+    # If you prefer strictness: return False here.
+    return True

src/pkgmgr/core/git/__init__.py

@@ -1,5 +1,7 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
+from __future__ import annotations
+
+from .errors import GitError
+from .run import run
 
 """
 Lightweight helper functions around Git commands.
@@ -9,84 +11,7 @@ logic (release, version, changelog) does not have to deal with the
 details of subprocess handling.
 """
 
-from __future__ import annotations
-
-import subprocess
-from typing import List, Optional
-
-
-class GitError(RuntimeError):
-    """Raised when a Git command fails in an unexpected way."""
-
-
-def run_git(args: List[str], cwd: str = ".") -> str:
-    """
-    Run a Git command and return its stdout as a stripped string.
-
-    Raises GitError if the command fails.
-    """
-    cmd = ["git"] + args
-    try:
-        result = subprocess.run(
-            cmd,
-            cwd=cwd,
-            check=True,
-            stdout=subprocess.PIPE,
-            stderr=subprocess.PIPE,
-            text=True,
-        )
-    except subprocess.CalledProcessError as exc:
-        raise GitError(
-            f"Git command failed in {cwd!r}: {' '.join(cmd)}\n"
-            f"Exit code: {exc.returncode}\n"
-            f"STDOUT:\n{exc.stdout}\n"
-            f"STDERR:\n{exc.stderr}"
-        ) from exc
-
-    return result.stdout.strip()
-
-
-def get_tags(cwd: str = ".") -> List[str]:
-    """
-    Return a list of all tags in the repository in `cwd`.
-
-    If there are no tags, an empty list is returned.
-    """
-    try:
-        output = run_git(["tag"], cwd=cwd)
-    except GitError as exc:
-        # If the repo has no tags or is not a git repo, surface a clear error.
-        # You can decide later if you want to treat this differently.
-        if "not a git repository" in str(exc):
-            raise
-        # No tags: stdout may just be empty; treat this as empty list.
-        return []
-
-    if not output:
-        return []
-
-    return [line.strip() for line in output.splitlines() if line.strip()]
-
-
-def get_head_commit(cwd: str = ".") -> Optional[str]:
-    """
-    Return the current HEAD commit hash, or None if it cannot be determined.
-    """
-    try:
-        output = run_git(["rev-parse", "HEAD"], cwd=cwd)
-    except GitError:
-        return None
-    return output or None
-
-
-def get_current_branch(cwd: str = ".") -> Optional[str]:
-    """
-    Return the current branch name, or None if it cannot be determined.
-
-    Note: In detached HEAD state this will return 'HEAD'.
-    """
-    try:
-        output = run_git(["rev-parse", "--abbrev-ref", "HEAD"], cwd=cwd)
-    except GitError:
-        return None
-    return output or None
+__all__ = [
+    "GitError",
+    "run",
+]

src/pkgmgr/core/git/commands/__init__.py

@@ -0,0 +1,72 @@
+# src/pkgmgr/core/git/commands/__init__.py
+from __future__ import annotations
+
+from .add import GitAddError, add
+from .add_all import GitAddAllError, add_all
+from .add_remote import GitAddRemoteError, add_remote
+from .add_remote_push_url import GitAddRemotePushUrlError, add_remote_push_url
+from .branch_move import GitBranchMoveError, branch_move
+from .checkout import GitCheckoutError, checkout
+from .clone import GitCloneError, clone
+from .commit import GitCommitError, commit
+from .create_branch import GitCreateBranchError, create_branch
+from .delete_local_branch import GitDeleteLocalBranchError, delete_local_branch
+from .delete_remote_branch import GitDeleteRemoteBranchError, delete_remote_branch
+from .fetch import GitFetchError, fetch
+from .init import GitInitError, init
+from .merge_no_ff import GitMergeError, merge_no_ff
+from .pull import GitPullError, pull
+from .pull_args import GitPullArgsError, pull_args  # <-- add
+from .pull_ff_only import GitPullFfOnlyError, pull_ff_only
+from .push import GitPushError, push
+from .push_upstream import GitPushUpstreamError, push_upstream
+from .set_remote_url import GitSetRemoteUrlError, set_remote_url
+from .tag_annotated import GitTagAnnotatedError, tag_annotated
+from .tag_force_annotated import GitTagForceAnnotatedError, tag_force_annotated
+
+__all__ = [
+    "add",
+    "add_all",
+    "fetch",
+    "checkout",
+    "pull",
+    "pull_args",  # <-- add
+    "pull_ff_only",
+    "merge_no_ff",
+    "push",
+    "commit",
+    "delete_local_branch",
+    "delete_remote_branch",
+    "create_branch",
+    "push_upstream",
+    "add_remote",
+    "set_remote_url",
+    "add_remote_push_url",
+    "tag_annotated",
+    "tag_force_annotated",
+    "clone",
+    "init",
+    "branch_move",
+    "GitAddError",
+    "GitAddAllError",
+    "GitFetchError",
+    "GitCheckoutError",
+    "GitPullError",
+    "GitPullArgsError",  # <-- add
+    "GitPullFfOnlyError",
+    "GitMergeError",
+    "GitPushError",
+    "GitCommitError",
+    "GitDeleteLocalBranchError",
+    "GitDeleteRemoteBranchError",
+    "GitCreateBranchError",
+    "GitPushUpstreamError",
+    "GitAddRemoteError",
+    "GitSetRemoteUrlError",
+    "GitAddRemotePushUrlError",
+    "GitTagAnnotatedError",
+    "GitTagForceAnnotatedError",
+    "GitCloneError",
+    "GitInitError",
+    "GitBranchMoveError",
+]

src/pkgmgr/core/git/commands/add.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from typing import Iterable, List, Sequence, Union
+
+from ..errors import GitError, GitCommandError
+from ..run import run
+
+
+class GitAddError(GitCommandError):
+    """Raised when `git add` fails."""
+
+
+PathLike = Union[str, Sequence[str], Iterable[str]]
+
+
+def _normalize_paths(paths: PathLike) -> List[str]:
+    if isinstance(paths, str):
+        return [paths]
+    return [p for p in paths]
+
+
+def add(
+    paths: PathLike,
+    *,
+    cwd: str = ".",
+    preview: bool = False,
+) -> None:
+    """
+    Stage one or multiple paths.
+
+    Equivalent to:
+      git add <path...>
+    """
+    normalized = _normalize_paths(paths)
+    if not normalized:
+        return
+
+    try:
+        run(["add", *normalized], cwd=cwd, preview=preview)
+    except GitError as exc:
+        raise GitAddError(
+            f"Failed to add paths to staging area: {normalized!r}.",
+            cwd=cwd,
+        ) from exc

src/pkgmgr/core/git/commands/add_all.py

@@ -0,0 +1,22 @@
+# src/pkgmgr/core/git/commands/add_all.py
+from __future__ import annotations
+
+from ..errors import GitError, GitCommandError
+from ..run import run
+
+
+class GitAddAllError(GitCommandError):
+    """Raised when `git add -A` fails."""
+
+
+def add_all(*, cwd: str = ".", preview: bool = False) -> None:
+    """
+    Stage all changes (tracked + untracked).
+
+    Equivalent to:
+      git add -A
+    """
+    try:
+        run(["add", "-A"], cwd=cwd, preview=preview)
+    except GitError as exc:
+        raise GitAddAllError("Failed to stage all changes with `git add -A`.", cwd=cwd) from exc

src/pkgmgr/core/git/commands/add_remote.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from ..errors import GitError, GitCommandError
+from ..run import run
+
+
+class GitAddRemoteError(GitCommandError):
+    """Raised when adding a remote fails."""
+
+
+def add_remote(
+    name: str,
+    url: str,
+    *,
+    cwd: str = ".",
+    preview: bool = False,
+) -> None:
+    """
+    Add a new remote.
+
+    Equivalent to:
+      git remote add <name> <url>
+    """
+    try:
+        run(
+            ["remote", "add", name, url],
+            cwd=cwd,
+            preview=preview,
+        )
+    except GitError as exc:
+        raise GitAddRemoteError(
+            f"Failed to add remote {name!r} with URL {url!r}.",
+            cwd=cwd,
+        ) from exc

src/pkgmgr/core/git/commands/add_remote_push_url.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from ..errors import GitError, GitCommandError
+from ..run import run
+
+
+class GitAddRemotePushUrlError(GitCommandError):
+    """Raised when adding an additional push URL to a remote fails."""
+
+
+def add_remote_push_url(
+    remote: str,
+    url: str,
+    *,
+    cwd: str = ".",
+    preview: bool = False,
+) -> None:
+    """
+    Add an additional push URL to a remote.
+
+    Equivalent to:
+      git remote set-url --add --push <remote> <url>
+    """
+    try:
+        run(
+            ["remote", "set-url", "--add", "--push", remote, url],
+            cwd=cwd,
+            preview=preview,
+        )
+    except GitError as exc:
+        raise GitAddRemotePushUrlError(
+            f"Failed to add push url {url!r} to remote {remote!r}.",
+            cwd=cwd,
+        ) from exc

src/pkgmgr/core/git/commands/branch_move.py

@@ -0,0 +1,22 @@
+# src/pkgmgr/core/git/commands/branch_move.py
+from __future__ import annotations
+
+from ..errors import GitError, GitCommandError
+from ..run import run
+
+
+class GitBranchMoveError(GitCommandError):
+    """Raised when renaming/moving a branch fails."""
+
+
+def branch_move(branch: str, *, cwd: str = ".", preview: bool = False) -> None:
+    """
+    Rename the current branch to `branch`, creating it if needed.
+
+    Equivalent to:
+      git branch -M <branch>
+    """
+    try:
+        run(["branch", "-M", branch], cwd=cwd, preview=preview)
+    except GitError as exc:
+        raise GitBranchMoveError(f"Failed to move/rename current branch to {branch!r}.", cwd=cwd) from exc

src/pkgmgr/core/git/commands/checkout.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from ..errors import GitError, GitCommandError
+from ..run import run
+
+
+class GitCheckoutError(GitCommandError):
+    """Raised when checking out a branch fails."""
+
+
+def checkout(branch: str, cwd: str = ".") -> None:
+    try:
+        run(["checkout", branch], cwd=cwd)
+    except GitError as exc:
+        raise GitCheckoutError(
+            f"Failed to checkout branch {branch!r}.",
+            cwd=cwd,
+        ) from exc

src/pkgmgr/core/git/commands/clone.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from typing import List
+
+from ..errors import GitError, GitCommandError
+from ..run import run
+
+
+class GitCloneError(GitCommandError):
+    """Raised when `git clone` fails."""
+
+
+def clone(
+    args: List[str],
+    *,
+    cwd: str = ".",
+    preview: bool = False,
+) -> None:
+    """
+    Execute `git clone` with caller-provided arguments.
+
+    Examples:
+      ["https://example.com/repo.git", "/path/to/dir"]
+      ["--depth", "1", "--single-branch", url, dest]
+    """
+    try:
+        run(["clone", *args], cwd=cwd, preview=preview)
+    except GitError as exc:
+        raise GitCloneError(
+            f"Git clone failed with args={args!r}.",
+            cwd=cwd,
+        ) from exc

src/pkgmgr/core/git/commands/commit.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from ..errors import GitError, GitCommandError
+from ..run import run
+
+
+class GitCommitError(GitCommandError):
+    """Raised when `git commit` fails."""
+
+
+def commit(
+    message: str,
+    *,
+    cwd: str = ".",
+    all: bool = False,
+    preview: bool = False,
+) -> None:
+    """
+    Create a commit.
+
+    Equivalent to:
+      git commit -m "<message>"
+    or (if all=True):
+      git commit -am "<message>"
+    """
+    args = ["commit"]
+    if all:
+        args.append("-a")
+    args += ["-m", message]
+
+    try:
+        run(args, cwd=cwd, preview=preview)
+    except GitError as exc:
+        raise GitCommitError(
+            "Failed to create commit.",
+            cwd=cwd,
+        ) from exc

src/pkgmgr/core/git/commands/create_branch.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from ..errors import GitError, GitCommandError
+from ..run import run
+
+
+class GitCreateBranchError(GitCommandError):
+    """Raised when creating a new branch fails."""
+
+
+def create_branch(branch: str, base: str, cwd: str = ".") -> None:
+    """
+    Create a new branch from a base branch.
+
+    Equivalent to: git checkout -b <branch> <base>
+    """
+    try:
+        run(["checkout", "-b", branch, base], cwd=cwd)
+    except GitError as exc:
+        raise GitCreateBranchError(
+            f"Failed to create branch {branch!r} from base {base!r}.",
+            cwd=cwd,
+        ) from exc

src/pkgmgr/core/git/commands/delete_local_branch.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from ..errors import GitError, GitCommandError
+from ..run import run
+
+
+class GitDeleteLocalBranchError(GitCommandError):
+    """Raised when deleting a local branch fails."""
+
+
+def delete_local_branch(branch: str, cwd: str = ".", force: bool = False) -> None:
+    flag = "-D" if force else "-d"
+    try:
+        run(["branch", flag, branch], cwd=cwd)
+    except GitError as exc:
+        raise GitDeleteLocalBranchError(
+            f"Failed to delete local branch {branch!r} (flag {flag}).",
+            cwd=cwd,
+        ) from exc

src/pkgmgr/core/git/commands/delete_remote_branch.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from ..errors import GitError, GitCommandError
+from ..run import run
+
+
+class GitDeleteRemoteBranchError(GitCommandError):
+    """Raised when deleting a remote branch fails."""
+
+
+def delete_remote_branch(remote: str, branch: str, cwd: str = ".") -> None:
+    try:
+        run(["push", remote, "--delete", branch], cwd=cwd)
+    except GitError as exc:
+        raise GitDeleteRemoteBranchError(
+            f"Failed to delete remote branch {branch!r} on {remote!r}.",
+            cwd=cwd,
+        ) from exc

src/pkgmgr/core/git/commands/fetch.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from ..errors import GitError, GitCommandError
+from ..run import run
+
+
+class GitFetchError(GitCommandError):
+    """Raised when fetching from a remote fails."""
+
+
+def fetch(
+    remote: str = "origin",
+    *,
+    prune: bool = False,
+    tags: bool = False,
+    force: bool = False,
+    cwd: str = ".",
+    preview: bool = False,
+) -> None:
+    """
+    Fetch from a remote, optionally with prune/tags/force.
+
+    Equivalent to:
+      git fetch <remote> [--prune] [--tags] [--force]
+    """
+    args = ["fetch", remote]
+    if prune:
+        args.append("--prune")
+    if tags:
+        args.append("--tags")
+    if force:
+        args.append("--force")
+
+    try:
+        run(args, cwd=cwd, preview=preview)
+    except GitError as exc:
+        raise GitFetchError(
+            f"Failed to fetch from remote {remote!r}.",
+            cwd=cwd,
+        ) from exc

src/pkgmgr/core/git/commands/init.py

@@ -0,0 +1,22 @@
+# src/pkgmgr/core/git/commands/init.py
+from __future__ import annotations
+
+from ..errors import GitError, GitCommandError
+from ..run import run
+
+
+class GitInitError(GitCommandError):
+    """Raised when `git init` fails."""
+
+
+def init(*, cwd: str = ".", preview: bool = False) -> None:
+    """
+    Initialize a repository.
+
+    Equivalent to:
+      git init
+    """
+    try:
+        run(["init"], cwd=cwd, preview=preview)
+    except GitError as exc:
+        raise GitInitError("Failed to initialize git repository.", cwd=cwd) from exc

src/pkgmgr/core/git/commands/merge_no_ff.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from ..errors import GitError, GitCommandError
+from ..run import run
+
+
+class GitMergeError(GitCommandError):
+    """Raised when merging a branch fails."""
+
+
+def merge_no_ff(branch: str, cwd: str = ".") -> None:
+    try:
+        run(["merge", "--no-ff", branch], cwd=cwd)
+    except GitError as exc:
+        raise GitMergeError(
+            f"Failed to merge branch {branch!r} with --no-ff.",
+            cwd=cwd,
+        ) from exc

src/pkgmgr/core/git/commands/pull.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from ..errors import GitError, GitCommandError
+from ..run import run
+
+
+class GitPullError(GitCommandError):
+    """Raised when pulling from a remote branch fails."""
+
+
+def pull(remote: str, branch: str, cwd: str = ".") -> None:
+    try:
+        run(["pull", remote, branch], cwd=cwd)
+    except GitError as exc:
+        raise GitPullError(
+            f"Failed to pull {remote!r}/{branch!r}.",
+            cwd=cwd,
+        ) from exc

src/pkgmgr/core/git/commands/pull_args.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from typing import List
+
+from ..errors import GitError, GitCommandError
+from ..run import run
+
+
+class GitPullArgsError(GitCommandError):
+    """Raised when `git pull` with arbitrary args fails."""
+
+
+def pull_args(
+    args: List[str] | None = None,
+    *,
+    cwd: str = ".",
+    preview: bool = False,
+) -> None:
+    """
+    Execute `git pull` with caller-provided arguments.
+
+    Examples:
+      []                          -> git pull
+      ["--ff-only"]               -> git pull --ff-only
+      ["--rebase"]                -> git pull --rebase
+      ["origin", "main"]          -> git pull origin main
+    """
+    extra = args or []
+    try:
+        run(["pull", *extra], cwd=cwd, preview=preview)
+    except GitError as exc:
+        raise GitPullArgsError(
+            f"Failed to run `git pull` with args={extra!r}.",
+            cwd=cwd,
+        ) from exc

src/pkgmgr/core/git/commands/pull_ff_only.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from ..errors import GitError, GitCommandError
+from ..run import run
+
+
+class GitPullFfOnlyError(GitCommandError):
+    """Raised when pulling with --ff-only fails."""
+
+
+def pull_ff_only(*, cwd: str = ".", preview: bool = False) -> None:
+    """
+    Pull using fast-forward only.
+
+    Equivalent to:
+      git pull --ff-only
+    """
+    try:
+        run(["pull", "--ff-only"], cwd=cwd, preview=preview)
+    except GitError as exc:
+        raise GitPullFfOnlyError(
+            "Failed to pull with --ff-only.",
+            cwd=cwd,
+        ) from exc

src/pkgmgr/core/git/commands/push.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from ..errors import GitError, GitCommandError
+from ..run import run
+
+
+class GitPushError(GitCommandError):
+    """Raised when pushing to a remote fails."""
+
+
+def push(
+    remote: str,
+    ref: str,
+    *,
+    force: bool = False,
+    cwd: str = ".",
+    preview: bool = False,
+) -> None:
+    """
+    Push a ref to a remote, optionally forced.
+
+    Equivalent to:
+      git push <remote> <ref> [--force]
+    """
+    args = ["push", remote, ref]
+    if force:
+        args.append("--force")
+
+    try:
+        run(args, cwd=cwd, preview=preview)
+    except GitError as exc:
+        raise GitPushError(
+            f"Failed to push ref {ref!r} to remote {remote!r}.",
+            cwd=cwd,
+        ) from exc

src/pkgmgr/core/git/commands/push_upstream.py

@@ -0,0 +1,31 @@
+# src/pkgmgr/core/git/commands/push_upstream.py
+from __future__ import annotations
+
+from ..errors import GitError, GitCommandError
+from ..run import run
+
+
+class GitPushUpstreamError(GitCommandError):
+    """Raised when pushing a branch with upstream tracking fails."""
+
+
+def push_upstream(
+    remote: str,
+    branch: str,
+    *,
+    cwd: str = ".",
+    preview: bool = False,
+) -> None:
+    """
+    Push a branch and set upstream tracking.
+
+    Equivalent to:
+      git push -u <remote> <branch>
+    """
+    try:
+        run(["push", "-u", remote, branch], cwd=cwd, preview=preview)
+    except GitError as exc:
+        raise GitPushUpstreamError(
+            f"Failed to push branch {branch!r} to {remote!r} with upstream tracking.",
+            cwd=cwd,
+        ) from exc

src/pkgmgr/core/git/commands/set_remote_url.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from ..errors import GitError, GitCommandError
+from ..run import run
+
+
+class GitSetRemoteUrlError(GitCommandError):
+    """Raised when setting a remote URL fails."""
+
+
+def set_remote_url(
+    remote: str,
+    url: str,
+    *,
+    cwd: str = ".",
+    push: bool = False,
+    preview: bool = False,
+) -> None:
+    """
+    Set the fetch or push URL of a remote.
+
+    Equivalent to:
+      git remote set-url <remote> <url>
+    or:
+      git remote set-url --push <remote> <url>
+    """
+    args = ["remote", "set-url"]
+    if push:
+        args.append("--push")
+    args += [remote, url]
+
+    try:
+        run(
+            args,
+            cwd=cwd,
+            preview=preview,
+        )
+    except GitError as exc:
+        mode = "push" if push else "fetch"
+        raise GitSetRemoteUrlError(
+            f"Failed to set {mode} url for remote {remote!r} to {url!r}.",
+            cwd=cwd,
+        ) from exc

src/pkgmgr/core/git/commands/tag_annotated.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from ..errors import GitError, GitCommandError
+from ..run import run
+
+
+class GitTagAnnotatedError(GitCommandError):
+    """Raised when creating an annotated tag fails."""
+
+
+def tag_annotated(
+    tag: str,
+    message: str,
+    *,
+    cwd: str = ".",
+    preview: bool = False,
+) -> None:
+    """
+    Create an annotated tag.
+
+    Equivalent to:
+      git tag -a <tag> -m "<message>"
+    """
+    try:
+        run(["tag", "-a", tag, "-m", message], cwd=cwd, preview=preview)
+    except GitError as exc:
+        raise GitTagAnnotatedError(
+            f"Failed to create annotated tag {tag!r}.",
+            cwd=cwd,
+        ) from exc

src/pkgmgr/core/git/commands/tag_force_annotated.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from ..errors import GitError, GitCommandError
+from ..run import run
+
+
+class GitTagForceAnnotatedError(GitCommandError):
+    """Raised when forcing an annotated tag fails."""
+
+
+def tag_force_annotated(
+    name: str,
+    target: str,
+    message: str,
+    *,
+    cwd: str = ".",
+    preview: bool = False,
+) -> None:
+    """
+    Force-create an annotated tag pointing at a given target.
+
+    Equivalent to:
+      git tag -f -a <name> <target> -m "<message>"
+    """
+    try:
+        run(["tag", "-f", "-a", name, target, "-m", message], cwd=cwd, preview=preview)
+    except GitError as exc:
+        raise GitTagForceAnnotatedError(
+            f"Failed to force annotated tag {name!r} at {target!r}.",
+            cwd=cwd,
+        ) from exc

src/pkgmgr/core/git/errors.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+
+class GitError(RuntimeError):
+    """Base error raised for Git related failures."""
+
+
+class GitCommandError(GitError):
+    """
+    Base class for state-changing git command failures.
+
+    Use subclasses to provide stable error types for callers.
+    """
+    def __init__(self, message: str, *, cwd: str = ".") -> None:
+        super().__init__(message)
+        self.cwd = cwd

src/pkgmgr/core/git/queries/__init__.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from .get_current_branch import get_current_branch
+from .get_head_commit import get_head_commit
+from .get_latest_commit import get_latest_commit
+from .get_tags import get_tags
+from .resolve_base_branch import GitBaseBranchNotFoundError, resolve_base_branch
+from .list_remotes import list_remotes
+from .get_remote_push_urls import get_remote_push_urls
+from .probe_remote_reachable import probe_remote_reachable
+from .get_changelog import get_changelog, GitChangelogQueryError
+from .get_tags_at_ref import get_tags_at_ref, GitTagsAtRefQueryError
+from .get_config_value import get_config_value
+from .get_upstream_ref import get_upstream_ref
+from .list_tags import list_tags
+from .get_repo_root import get_repo_root
+
+__all__ = [
+    "get_current_branch",
+    "get_head_commit",
+    "get_latest_commit",
+    "get_tags",
+    "resolve_base_branch",
+    "GitBaseBranchNotFoundError",
+    "list_remotes",
+    "get_remote_push_urls",
+    "probe_remote_reachable",
+    "get_changelog",
+    "GitChangelogQueryError",
+    "get_tags_at_ref",
+    "GitTagsAtRefQueryError",
+    "get_config_value",
+    "get_upstream_ref",
+    "list_tags",
+    "get_repo_root",
+]

src/pkgmgr/core/git/queries/get_changelog.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from ..errors import GitError
+from ..run import run
+
+
+class GitChangelogQueryError(GitError):
+    """Raised when querying the git changelog fails."""
+
+
+def get_changelog(
+    *,
+    cwd: str,
+    from_ref: Optional[str] = None,
+    to_ref: Optional[str] = None,
+    include_merges: bool = False,
+) -> str:
+    """
+    Return a plain-text changelog between two Git refs.
+
+    Uses:
+      git log --pretty=format:%h %d %s [--no-merges] <range>
+
+    Raises:
+      GitChangelogQueryError on failure.
+    """
+    if to_ref is None:
+        to_ref = "HEAD"
+
+    rev_range = f"{from_ref}..{to_ref}" if from_ref else to_ref
+
+    cmd = ["log", "--pretty=format:%h %d %s"]
+    if not include_merges:
+        cmd.append("--no-merges")
+    cmd.append(rev_range)
+
+    try:
+        return run(cmd, cwd=cwd)
+    except GitError as exc:
+        raise GitChangelogQueryError(
+            f"Failed to query changelog for range {rev_range!r}.",
+        ) from exc

src/pkgmgr/core/git/queries/get_config_value.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from ..errors import GitError
+from ..run import run
+
+
+def _is_missing_key_error(exc: GitError) -> bool:
+    msg = str(exc).lower()
+
+    # Ensure we only swallow the expected case for THIS command.
+    if "git config --get" not in msg:
+        return False
+
+    # 'git config --get' returns exit code 1 when the key is not set.
+    return "exit code: 1" in msg
+
+def get_config_value(key: str, *, cwd: str = ".") -> Optional[str]:
+    """
+    Return a value from `git config --get <key>`, or None if not set.
+
+    We keep core.git.run() strict (check=True) and interpret the known
+    'not set' exit-code case here.
+    """
+    try:
+        output = run(["config", "--get", key], cwd=cwd)
+    except GitError as exc:
+        if _is_missing_key_error(exc):
+            return None
+        raise
+
+    output = output.strip()
+    return output or None

src/pkgmgr/core/git/queries/get_current_branch.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from typing import Optional
+from ..errors import GitError
+from ..run import run
+
+
+def get_current_branch(cwd: str = ".") -> Optional[str]:
+    """
+    Return the current branch name, or None if it cannot be determined.
+
+    Note: In detached HEAD state this will return 'HEAD'.
+    """
+    try:
+        output = run(["rev-parse", "--abbrev-ref", "HEAD"], cwd=cwd)
+    except GitError:
+        return None
+    return output or None

src/pkgmgr/core/git/queries/get_head_commit.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from ..errors import GitError
+from ..run import run
+
+
+def get_head_commit(cwd: str = ".") -> Optional[str]:
+    """
+    Return the current HEAD commit hash, or None if it cannot be determined.
+    """
+    try:
+        output = run(["rev-parse", "HEAD"], cwd=cwd)
+    except GitError:
+        return None
+    return output or None

src/pkgmgr/core/git/queries/get_latest_commit.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from ..errors import GitError
+from ..run import run
+
+
+def get_latest_commit(cwd: str = ".") -> Optional[str]:
+    """
+    Return the latest commit hash for the repository in `cwd`.
+
+    Equivalent to:
+      git log -1 --format=%H
+
+    Returns:
+      The commit hash string, or None if it cannot be determined
+      (e.g. not a git repo, no commits, or other git failure).
+    """
+    try:
+        output = run(["log", "-1", "--format=%H"], cwd=cwd)
+    except GitError:
+        return None
+
+    output = output.strip()
+    return output or None

src/pkgmgr/core/git/queries/get_remote_push_urls.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import Set
+
+from ..run import run
+
+
+def get_remote_push_urls(remote: str, cwd: str = ".") -> Set[str]:
+    """
+    Return all push URLs configured for a remote.
+
+    Equivalent to:
+      git remote get-url --push --all <remote>
+
+    Raises GitError if the command fails.
+    """
+    output = run(["remote", "get-url", "--push", "--all", remote], cwd=cwd)
+    if not output:
+        return set()
+    return {line.strip() for line in output.splitlines() if line.strip()}

src/pkgmgr/core/git/queries/get_repo_root.py

@@ -0,0 +1,23 @@
+# src/pkgmgr/core/git/queries/get_repo_root.py
+from __future__ import annotations
+
+from typing import Optional
+
+from ..errors import GitError
+from ..run import run
+
+
+def get_repo_root(*, cwd: str = ".") -> Optional[str]:
+    """
+    Return the git repository root directory (top-level), or None if not available.
+
+    Equivalent to:
+      git rev-parse --show-toplevel
+    """
+    try:
+        out = run(["rev-parse", "--show-toplevel"], cwd=cwd)
+    except GitError:
+        return None
+
+    out = out.strip()
+    return out or None

src/pkgmgr/core/git/queries/get_tags.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from typing import List
+
+from ..errors import GitError
+from ..run import run
+
+
+def get_tags(cwd: str = ".") -> List[str]:
+    """
+    Return a list of all tags in the repository in `cwd`.
+
+    If there are no tags, an empty list is returned.
+    """
+    try:
+        output = run(["tag"], cwd=cwd)
+    except GitError as exc:
+        # If the repo is not a git repo, surface a clear error.
+        if "not a git repository" in str(exc):
+            raise
+        # Otherwise, treat as "no tags" (e.g., empty stdout).
+        return []
+
+    if not output:
+        return []
+
+    return [line.strip() for line in output.splitlines() if line.strip()]

src/pkgmgr/core/git/queries/get_tags_at_ref.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from typing import List
+
+from ..errors import GitError
+from ..run import run
+
+
+class GitTagsAtRefQueryError(GitError):
+    """Raised when querying tags for a ref fails."""
+
+
+def get_tags_at_ref(ref: str, *, cwd: str = ".") -> List[str]:
+    """
+    Return all git tags pointing at a given ref.
+
+    Equivalent to:
+      git tag --points-at <ref>
+    """
+    try:
+        output = run(["tag", "--points-at", ref], cwd=cwd)
+    except GitError as exc:
+        raise GitTagsAtRefQueryError(
+            f"Failed to query tags at ref {ref!r}.",
+        ) from exc
+
+    if not output:
+        return []
+
+    return [line.strip() for line in output.splitlines() if line.strip()]

src/pkgmgr/core/git/queries/get_upstream_ref.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from ..errors import GitError
+from ..run import run
+
+
+def get_upstream_ref(*, cwd: str = ".") -> Optional[str]:
+    """
+    Return the configured upstream ref for the current branch, or None if none.
+
+    Equivalent to:
+      git rev-parse --abbrev-ref --symbolic-full-name @{u}
+    """
+    try:
+        out = run(
+            ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"],
+            cwd=cwd,
+        )
+    except GitError:
+        return None
+
+    out = out.strip()
+    return out or None

src/pkgmgr/core/git/queries/list_remotes.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from typing import List
+
+from ..run import run
+
+
+def list_remotes(cwd: str = ".") -> List[str]:
+    """
+    Return a list of configured git remotes (e.g. ['origin', 'upstream']).
+
+    Raises GitError if the command fails.
+    """
+    output = run(["remote"], cwd=cwd)
+    if not output:
+        return []
+    return [line.strip() for line in output.splitlines() if line.strip()]

src/pkgmgr/core/git/queries/list_tags.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from typing import List
+
+from ..run import run
+
+
+def list_tags(pattern: str = "*", *, cwd: str = ".") -> List[str]:
+    """
+    List tags matching a pattern.
+
+    Equivalent to:
+      git tag --list <pattern>
+    """
+    out = run(["tag", "--list", pattern], cwd=cwd)
+    if not out:
+        return []
+    return [line.strip() for line in out.splitlines() if line.strip()]

src/pkgmgr/core/git/queries/probe_remote_reachable.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from ..errors import GitError
+from ..run import run
+
+
+def probe_remote_reachable(url: str, cwd: str = ".") -> bool:
+    """
+    Check whether a remote URL is reachable.
+
+    Equivalent to:
+      git ls-remote --exit-code <url>
+
+    Returns:
+      True if reachable, False otherwise.
+    """
+    try:
+        run(["ls-remote", "--exit-code", url], cwd=cwd)
+        return True
+    except GitError:
+        return False

src/pkgmgr/core/git/queries/resolve_base_branch.py

@@ -0,0 +1,66 @@
+# src/pkgmgr/core/git/queries/resolve_base_branch.py
+from __future__ import annotations
+
+from ..errors import GitError
+from ..run import run
+
+
+class GitBaseBranchNotFoundError(GitError):
+    """Raised when neither preferred nor fallback base branch exists."""
+
+
+def _is_branch_missing_error(exc: GitError) -> bool:
+    """
+    Heuristic: Detect errors that indicate the branch/ref does not exist.
+
+    We intentionally *do not* swallow other errors like:
+      - not a git repository
+      - permission issues
+      - corrupted repository
+    """
+    msg = str(exc).lower()
+
+    # Common git messages when verifying a non-existing ref/branch.
+    patterns = [
+        "needed a single revision",
+        "unknown revision or path not in the working tree",
+        "not a valid object name",
+        "ambiguous argument",
+        "bad revision",
+        "fatal: invalid object name",
+        "fatal: ambiguous argument",
+    ]
+
+    return any(p in msg for p in patterns)
+
+
+def resolve_base_branch(
+    preferred: str = "main",
+    fallback: str = "master",
+    cwd: str = ".",
+) -> str:
+    """
+    Resolve the base branch to use.
+
+    Try `preferred` first (default: main),
+    fall back to `fallback` (default: master).
+
+    Raises GitBaseBranchNotFoundError if neither exists.
+    Raises GitError for other git failures (e.g., not a git repository).
+    """
+    last_missing_error: GitError | None = None
+
+    for candidate in (preferred, fallback):
+        try:
+            run(["rev-parse", "--verify", candidate], cwd=cwd)
+            return candidate
+        except GitError as exc:
+            if _is_branch_missing_error(exc):
+                last_missing_error = exc
+                continue
+            raise  # anything else is a real problem -> bubble up
+
+    # Both candidates missing -> raise specific error
+    raise GitBaseBranchNotFoundError(
+        f"Neither {preferred!r} nor {fallback!r} exist in this repository."
+    ) from last_missing_error

src/pkgmgr/core/git/run.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import subprocess
+from typing import List
+
+from .errors import GitError
+
+
+def run(
+    args: List[str],
+    *,
+    cwd: str = ".",
+    preview: bool = False,
+) -> str:
+    """
+    Run a Git command and return its stdout as a stripped string.
+
+    If preview=True, the command is printed but NOT executed.
+
+    Raises GitError if execution fails.
+    """
+    cmd = ["git"] + args
+    cmd_str = " ".join(cmd)
+
+    if preview:
+        print(f"[PREVIEW] Would run in {cwd!r}: {cmd_str}")
+        return ""
+
+    try:
+        result = subprocess.run(
+            cmd,
+            cwd=cwd,
+            check=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+        )
+    except subprocess.CalledProcessError as exc:
+        raise GitError(
+            f"Git command failed in {cwd!r}: {cmd_str}\n"
+            f"Exit code: {exc.returncode}\n"
+            f"STDOUT:\n{exc.stdout}\n"
+            f"STDERR:\n{exc.stderr}"
+        ) from exc
+
+    return result.stdout.strip()

tests/e2e/test_repos_create_preview_output.py

@@ -1,42 +0,0 @@
-from __future__ import annotations
-
-import io
-import unittest
-from contextlib import redirect_stdout
-from unittest.mock import patch
-
-from pkgmgr.actions.repository.create import create_repo
-
-
-class TestE2ECreateRepoPreviewOutput(unittest.TestCase):
-    def test_create_repo_preview_prints_expected_steps(self) -> None:
-        cfg = {"directories": {"repositories": "/tmp/Repositories"}, "repositories": []}
-
-        out = io.StringIO()
-        with (
-            redirect_stdout(out),
-            patch("pkgmgr.actions.repository.create.os.path.exists", return_value=False),
-            patch("pkgmgr.actions.repository.create.generate_alias", return_value="repo"),
-            patch("pkgmgr.actions.repository.create.save_user_config"),
-            patch("pkgmgr.actions.repository.create.os.makedirs"),
-            patch("pkgmgr.actions.repository.create.render_default_templates"),
-            patch("pkgmgr.actions.repository.create.write_mirrors_file"),
-            patch("pkgmgr.actions.repository.create.setup_mirrors"),
-            patch("pkgmgr.actions.repository.create.subprocess.run"),
-        ):
-            create_repo(
-                "github.com/acme/repo",
-                cfg,
-                "/tmp/user.yml",
-                "/tmp/bin",
-                remote=False,
-                preview=True,
-            )
-
-        s = out.getvalue()
-        self.assertIn("[Preview] Would save user config:", s)
-        self.assertIn("[Preview] Would ensure directory exists:", s)
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/integration/test_mirror_commands.py

@@ -27,18 +27,10 @@ from unittest.mock import MagicMock, PropertyMock, patch
 
 
 class TestIntegrationMirrorCommands(unittest.TestCase):
-    """
-    Integration tests for `pkgmgr mirror` commands.
-    """
+    """Integration tests for `pkgmgr mirror` commands."""
 
     def _run_pkgmgr(self, args: List[str], extra_env: Optional[Dict[str, str]] = None) -> str:
-        """
-        Execute pkgmgr with the given arguments and return captured output.
-
-        - Treat SystemExit(0) or SystemExit(None) as success.
-        - Any other exit code is considered a test failure.
-        - Mirror commands are patched to avoid network/destructive operations.
-        """
+        """Execute pkgmgr with the given arguments and return captured output."""
         original_argv = list(sys.argv)
         original_env = dict(os.environ)
         buffer = io.StringIO()
@@ -64,8 +56,7 @@ class TestIntegrationMirrorCommands(unittest.TestCase):
             try:
                 importlib.import_module(module_name)
             except ModuleNotFoundError:
-                # If the module truly doesn't exist, create=True may still allow patching
-                # in some cases, but dotted resolution can still fail. Best-effort.
+                # Best-effort: allow patch(create=True) even if a symbol moved.
                 pass
             return patch(target, create=True, **kwargs)
 
@@ -95,10 +86,9 @@ class TestIntegrationMirrorCommands(unittest.TestCase):
                 stack.enter_context(_p("pkgmgr.actions.mirror.setup_cmd.build_context", return_value=dummy_ctx))
                 stack.enter_context(_p("pkgmgr.actions.mirror.remote_provision.build_context", return_value=dummy_ctx))
 
-                # Deterministic remote probing (covers setup + likely check implementations)
-                stack.enter_context(_p("pkgmgr.actions.mirror.remote_check.probe_mirror", return_value=(True, "")))
-                stack.enter_context(_p("pkgmgr.actions.mirror.setup_cmd.probe_mirror", return_value=(True, "")))
-                stack.enter_context(_p("pkgmgr.actions.mirror.git_remote.is_remote_reachable", return_value=True))
+                # Deterministic remote probing (new refactor: probe_remote_reachable)
+                stack.enter_context(_p("pkgmgr.core.git.queries.probe_remote_reachable", return_value=True))
+                stack.enter_context(_p("pkgmgr.actions.mirror.setup_cmd.probe_remote_reachable", return_value=True))
 
                 # setup_cmd imports ensure_origin_remote directly:
                 stack.enter_context(_p("pkgmgr.actions.mirror.setup_cmd.ensure_origin_remote", return_value=None))
@@ -113,9 +103,6 @@ class TestIntegrationMirrorCommands(unittest.TestCase):
                     )
                 )
 
-                # Extra safety: if anything calls remote_check.run_git directly, make it inert
-                stack.enter_context(_p("pkgmgr.actions.mirror.remote_check.run_git", return_value="dummy"))
-
                 with redirect_stdout(buffer), redirect_stderr(buffer):
                     try:
                         runpy.run_module("pkgmgr", run_name="__main__")
@@ -134,10 +121,6 @@ class TestIntegrationMirrorCommands(unittest.TestCase):
             os.environ.clear()
             os.environ.update(original_env)
 
-    # ------------------------------------------------------------
-    # Tests
-    # ------------------------------------------------------------
-
     def test_mirror_help(self) -> None:
         output = self._run_pkgmgr(["mirror", "--help"])
         self.assertIn("usage:", output.lower())

tests/integration/test_repos_create_preview_output.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import io
+import unittest
+from contextlib import redirect_stdout
+from unittest.mock import patch
+
+from pkgmgr.actions.repository.create import create_repo
+
+
+class TestCreateRepoPreviewOutput(unittest.TestCase):
+    def test_create_repo_preview_prints_expected_steps(self) -> None:
+        cfg = {"directories": {"repositories": "/tmp/Repositories"}, "repositories": []}
+
+        out = io.StringIO()
+        with (
+            redirect_stdout(out),
+            patch(
+                "pkgmgr.actions.repository.create.config_writer.generate_alias",
+                return_value="repo",
+            ),
+            patch(
+                "pkgmgr.actions.repository.create.config_writer.save_user_config",
+            ),
+            patch(
+                "pkgmgr.actions.repository.create.config_writer.os.path.exists",
+                return_value=False,
+            ),
+            patch(
+                "pkgmgr.actions.repository.create.service.os.makedirs",
+            ),
+            patch(
+                "pkgmgr.actions.repository.create.templates.TemplateRenderer._resolve_templates_dir",
+                return_value="/tpl",
+            ),
+            patch(
+                "pkgmgr.actions.repository.create.templates.os.walk",
+                return_value=[("/tpl", [], ["README.md.j2"])],
+            ),
+            patch(
+                "pkgmgr.actions.repository.create.git_bootstrap.init",
+            ),
+            patch(
+                "pkgmgr.actions.repository.create.git_bootstrap.add_all",
+            ),
+            patch(
+                "pkgmgr.actions.repository.create.git_bootstrap.commit",
+            ),
+            patch(
+                "pkgmgr.actions.repository.create.mirrors.write_mirrors_file",
+            ),
+            patch(
+                "pkgmgr.actions.repository.create.mirrors.setup_mirrors",
+            ),
+            patch(
+                "pkgmgr.actions.repository.create.service.get_config_value",
+                return_value=None,
+            ),
+        ):
+            create_repo(
+                "github.com/acme/repo",
+                cfg,
+                "/tmp/user.yml",
+                "/tmp/bin",
+                remote=False,
+                preview=True,
+            )
+
+        s = out.getvalue()
+        self.assertIn("[Preview] Would add repository to config:", s)
+        self.assertIn("[Preview] Would ensure directory exists:", s)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/integration/test_repos_create_pypi_not_in_git_config.py

@@ -0,0 +1,115 @@
+# tests/integration/test_repos_create_pypi_not_in_git_config.py
+from __future__ import annotations
+
+import os
+import subprocess
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+from pkgmgr.actions.repository.create import create_repo
+
+
+class TestCreateRepoPypiNotInGitConfig(unittest.TestCase):
+    def test_create_repo_writes_pypi_to_mirrors_but_not_git_config(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            tmp_path = Path(tmp)
+
+            # Repositories base dir used by create flow
+            repos_base = tmp_path / "Repositories"
+            user_cfg = tmp_path / "user.yml"
+            bin_dir = tmp_path / "bin"
+            bin_dir.mkdir(parents=True, exist_ok=True)
+
+            cfg = {
+                "directories": {"repositories": str(repos_base)},
+                "repositories": [],
+            }
+
+            # Provide a minimal templates directory so TemplateRenderer can run
+            tpl_dir = tmp_path / "tpl"
+            tpl_dir.mkdir(parents=True, exist_ok=True)
+            (tpl_dir / "README.md.j2").write_text(
+                "# {{ repository }}\n", encoding="utf-8"
+            )
+
+            # Expected repo dir for identifier github.com/acme/repo
+            repo_dir = repos_base / "github.com" / "acme" / "repo"
+
+            with (
+                # Avoid any real network calls during mirror "remote probing"
+                patch(
+                    "pkgmgr.actions.mirror.setup_cmd.probe_remote_reachable",
+                    return_value=True,
+                ),
+                # Force templates to come from our temp directory
+                patch(
+                    "pkgmgr.actions.repository.create.templates.TemplateRenderer._resolve_templates_dir",
+                    return_value=str(tpl_dir),
+                ),
+                # Make git commit deterministic without depending on global git config
+                patch.dict(
+                    os.environ,
+                    {
+                        "GIT_AUTHOR_NAME": "Test Author",
+                        "GIT_AUTHOR_EMAIL": "author@example.invalid",
+                        "GIT_COMMITTER_NAME": "Test Author",
+                        "GIT_COMMITTER_EMAIL": "author@example.invalid",
+                    },
+                    clear=False,
+                ),
+            ):
+                create_repo(
+                    "github.com/acme/repo",
+                    cfg,
+                    str(user_cfg),
+                    str(bin_dir),
+                    remote=False,
+                    preview=False,
+                )
+
+            # --- Assertions: MIRRORS file ---
+            mirrors_file = repo_dir / "MIRRORS"
+            self.assertTrue(mirrors_file.exists(), "MIRRORS file was not created")
+
+            mirrors_content = mirrors_file.read_text(encoding="utf-8")
+            self.assertIn(
+                "pypi https://pypi.org/project/repo/",
+                mirrors_content,
+                "PyPI mirror entry must exist in MIRRORS",
+            )
+            self.assertIn(
+                "origin git@github.com:acme/repo.git",
+                mirrors_content,
+                "origin SSH URL must exist in MIRRORS",
+            )
+
+            # --- Assertions: git config must NOT contain PyPI ---
+            git_config = repo_dir / ".git" / "config"
+            self.assertTrue(git_config.exists(), ".git/config was not created")
+
+            git_config_content = git_config.read_text(encoding="utf-8")
+            self.assertNotIn(
+                "pypi.org/project",
+                git_config_content,
+                "PyPI must never be written into git config",
+            )
+
+            # --- Assertions: origin remote exists and points to SSH ---
+            remotes = subprocess.check_output(
+                ["git", "-C", str(repo_dir), "remote"],
+                text=True,
+            ).splitlines()
+
+            self.assertIn("origin", remotes, "origin remote was not created")
+
+            remote_v = subprocess.check_output(
+                ["git", "-C", str(repo_dir), "remote", "-v"],
+                text=True,
+            )
+            self.assertIn("git@github.com:acme/repo.git", remote_v)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/integration/test_token_resolver_flow.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+import unittest
+from unittest.mock import patch
+
+from pkgmgr.core.credentials.resolver import TokenResolver
+from pkgmgr.core.credentials.types import TokenResult
+
+
+class TestTokenResolverIntegration(unittest.TestCase):
+    def test_full_resolution_flow_with_invalid_gh_and_keyring_then_prompt(self) -> None:
+        """
+        Full integration scenario:
+
+        - ENV provides nothing
+        - GitHub CLI (gh) is available and returns a token, but it is INVALID
+        - Keyring contains a token, but it is INVALID
+        - Interactive prompt provides a NEW token
+        - New token is ACCEPTED and OVERWRITES the keyring entry
+        """
+
+        resolver = TokenResolver()
+
+        # ------------------------------------------------------------------
+        # 1) ENV: empty
+        # ------------------------------------------------------------------
+        with patch.dict("os.environ", {}, clear=True):
+
+            # ------------------------------------------------------------------
+            # 2) GH CLI is available
+            # ------------------------------------------------------------------
+            with patch(
+                "pkgmgr.core.credentials.providers.gh.shutil.which",
+                return_value="/usr/bin/gh",
+            ):
+                with patch(
+                    "pkgmgr.core.credentials.providers.gh.subprocess.check_output",
+                    return_value="gh-invalid-token\n",
+                ):
+
+                    # ------------------------------------------------------------------
+                    # 3) Keyring returns an existing (invalid) token
+                    # ------------------------------------------------------------------
+                    with patch(
+                        "pkgmgr.core.credentials.providers.keyring._import_keyring"
+                    ) as mock_import_keyring:
+
+                        mock_keyring = mock_import_keyring.return_value
+                        mock_keyring.get_password.return_value = "keyring-invalid-token"
+
+                        # ------------------------------------------------------------------
+                        # 4) Prompt is allowed and returns a NEW token
+                        # ------------------------------------------------------------------
+                        with patch(
+                            "pkgmgr.core.credentials.providers.prompt.sys.stdin.isatty",
+                            return_value=True,
+                        ):
+                            with patch(
+                                "pkgmgr.core.credentials.providers.prompt.getpass",
+                                return_value="new-valid-token",
+                            ):
+
+                                # ------------------------------------------------------------------
+                                # 5) Validation logic:
+                                #    - gh token invalid
+                                #    - keyring token invalid
+                                #    - prompt token is NOT validated (by design)
+                                # ------------------------------------------------------------------
+                                def validate_side_effect(
+                                    provider_kind: str,
+                                    host: str,
+                                    token: str,
+                                ) -> bool:
+                                    return False  # gh + keyring invalid
+
+                                with patch(
+                                    "pkgmgr.core.credentials.resolver.validate_token",
+                                    side_effect=validate_side_effect,
+                                ) as validate_mock:
+
+                                    result = resolver.get_token(
+                                        provider_kind="github",
+                                        host="github.com",
+                                    )
+
+        # ----------------------------------------------------------------------
+        # Assertions
+        # ----------------------------------------------------------------------
+        self.assertIsInstance(result, TokenResult)
+        self.assertEqual(result.token, "new-valid-token")
+        self.assertEqual(result.source, "prompt")
+
+        # validate_token was called ONLY for gh and keyring
+        validated_tokens = [call.args[2] for call in validate_mock.call_args_list]
+        self.assertIn("gh-invalid-token", validated_tokens)
+        self.assertIn("keyring-invalid-token", validated_tokens)
+        self.assertNotIn("new-valid-token", validated_tokens)
+
+        # Keyring must be overwritten with the new token
+        mock_keyring.set_password.assert_called_once()
+        service, username, stored_token = mock_keyring.set_password.call_args.args
+        self.assertEqual(stored_token, "new-valid-token")
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/pkgmgr/actions/branch/__init__.py

@@ -1,33 +0,0 @@
-import unittest
-from unittest.mock import patch
-
-from pkgmgr.actions.branch.utils import _resolve_base_branch
-from pkgmgr.core.git import GitError
-
-
-class TestResolveBaseBranch(unittest.TestCase):
-    @patch("pkgmgr.actions.branch.utils.run_git")
-    def test_resolves_preferred(self, run_git):
-        run_git.return_value = None
-        result = _resolve_base_branch("main", "master", cwd=".")
-        self.assertEqual(result, "main")
-        run_git.assert_called_with(["rev-parse", "--verify", "main"], cwd=".")
-
-    @patch("pkgmgr.actions.branch.utils.run_git")
-    def test_resolves_fallback(self, run_git):
-        run_git.side_effect = [
-            GitError("main missing"),
-            None,
-        ]
-        result = _resolve_base_branch("main", "master", cwd=".")
-        self.assertEqual(result, "master")
-
-    @patch("pkgmgr.actions.branch.utils.run_git")
-    def test_raises_when_no_branch_exists(self, run_git):
-        run_git.side_effect = GitError("missing")
-        with self.assertRaises(RuntimeError):
-            _resolve_base_branch("main", "master", cwd=".")
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/unit/pkgmgr/actions/branch/test_close_branch.py

@@ -2,54 +2,129 @@ import unittest
 from unittest.mock import patch
 
 from pkgmgr.actions.branch.close_branch import close_branch
-from pkgmgr.core.git import GitError
+from pkgmgr.core.git.errors import GitError
+from pkgmgr.core.git.commands import GitDeleteRemoteBranchError
 
 
 class TestCloseBranch(unittest.TestCase):
-    @patch("pkgmgr.actions.branch.close_branch.input", return_value="y")
+    @patch("builtins.input", return_value="y")
     @patch("pkgmgr.actions.branch.close_branch.get_current_branch", return_value="feature-x")
-    @patch("pkgmgr.actions.branch.close_branch._resolve_base_branch", return_value="main")
-    @patch("pkgmgr.actions.branch.close_branch.run_git")
-    def test_close_branch_happy_path(self, run_git, resolve, current, input_mock):
+    @patch("pkgmgr.actions.branch.close_branch.resolve_base_branch", return_value="main")
+    @patch("pkgmgr.actions.branch.close_branch.fetch")
+    @patch("pkgmgr.actions.branch.close_branch.checkout")
+    @patch("pkgmgr.actions.branch.close_branch.pull")
+    @patch("pkgmgr.actions.branch.close_branch.merge_no_ff")
+    @patch("pkgmgr.actions.branch.close_branch.push")
+    @patch("pkgmgr.actions.branch.close_branch.delete_local_branch")
+    @patch("pkgmgr.actions.branch.close_branch.delete_remote_branch")
+    def test_close_branch_happy_path(
+        self,
+        delete_remote_branch,
+        delete_local_branch,
+        push,
+        merge_no_ff,
+        pull,
+        checkout,
+        fetch,
+        _resolve,
+        _current,
+        _input_mock,
+    ) -> None:
         close_branch(None, cwd=".")
-        expected = [
-            (["fetch", "origin"],),
-            (["checkout", "main"],),
-            (["pull", "origin", "main"],),
-            (["merge", "--no-ff", "feature-x"],),
-            (["push", "origin", "main"],),
-            (["branch", "-d", "feature-x"],),
-            (["push", "origin", "--delete", "feature-x"],),
-        ]
-        actual = [call.args for call in run_git.call_args_list]
-        self.assertEqual(actual, expected)
+        fetch.assert_called_once_with("origin", cwd=".")
+        checkout.assert_called_once_with("main", cwd=".")
+        pull.assert_called_once_with("origin", "main", cwd=".")
+        merge_no_ff.assert_called_once_with("feature-x", cwd=".")
+        push.assert_called_once_with("origin", "main", cwd=".")
+        delete_local_branch.assert_called_once_with("feature-x", cwd=".", force=False)
+        delete_remote_branch.assert_called_once_with("origin", "feature-x", cwd=".")
 
     @patch("pkgmgr.actions.branch.close_branch.get_current_branch", return_value="main")
-    @patch("pkgmgr.actions.branch.close_branch._resolve_base_branch", return_value="main")
-    def test_refuses_to_close_base_branch(self, resolve, current):
+    @patch("pkgmgr.actions.branch.close_branch.resolve_base_branch", return_value="main")
+    def test_refuses_to_close_base_branch(self, _resolve, _current) -> None:
         with self.assertRaises(RuntimeError):
             close_branch(None)
 
-    @patch("pkgmgr.actions.branch.close_branch.input", return_value="n")
+    @patch("builtins.input", return_value="n")
     @patch("pkgmgr.actions.branch.close_branch.get_current_branch", return_value="feature-x")
-    @patch("pkgmgr.actions.branch.close_branch._resolve_base_branch", return_value="main")
-    @patch("pkgmgr.actions.branch.close_branch.run_git")
-    def test_close_branch_aborts_on_no(self, run_git, resolve, current, input_mock):
+    @patch("pkgmgr.actions.branch.close_branch.resolve_base_branch", return_value="main")
+    @patch("pkgmgr.actions.branch.close_branch.fetch")
+    def test_close_branch_aborts_on_no(self, fetch, _resolve, _current, _input_mock) -> None:
         close_branch(None, cwd=".")
-        run_git.assert_not_called()
+        fetch.assert_not_called()
 
+    @patch("builtins.input")
     @patch("pkgmgr.actions.branch.close_branch.get_current_branch", return_value="feature-x")
-    @patch("pkgmgr.actions.branch.close_branch._resolve_base_branch", return_value="main")
-    @patch("pkgmgr.actions.branch.close_branch.run_git")
-    def test_close_branch_force_skips_prompt(self, run_git, resolve, current):
+    @patch("pkgmgr.actions.branch.close_branch.resolve_base_branch", return_value="main")
+    @patch("pkgmgr.actions.branch.close_branch.fetch")
+    @patch("pkgmgr.actions.branch.close_branch.checkout")
+    @patch("pkgmgr.actions.branch.close_branch.pull")
+    @patch("pkgmgr.actions.branch.close_branch.merge_no_ff")
+    @patch("pkgmgr.actions.branch.close_branch.push")
+    @patch("pkgmgr.actions.branch.close_branch.delete_local_branch")
+    @patch("pkgmgr.actions.branch.close_branch.delete_remote_branch")
+    def test_close_branch_force_skips_prompt(
+        self,
+        delete_remote_branch,
+        delete_local_branch,
+        push,
+        merge_no_ff,
+        pull,
+        checkout,
+        fetch,
+        _resolve,
+        _current,
+        input_mock,
+    ) -> None:
         close_branch(None, cwd=".", force=True)
-        self.assertGreater(len(run_git.call_args_list), 0)
+
+        # no interactive prompt when forced
+        input_mock.assert_not_called()
+
+        # workflow still runs (but is mocked)
+        fetch.assert_called_once_with("origin", cwd=".")
+        checkout.assert_called_once_with("main", cwd=".")
+        pull.assert_called_once_with("origin", "main", cwd=".")
+        merge_no_ff.assert_called_once_with("feature-x", cwd=".")
+        push.assert_called_once_with("origin", "main", cwd=".")
+        delete_local_branch.assert_called_once_with("feature-x", cwd=".", force=False)
+        delete_remote_branch.assert_called_once_with("origin", "feature-x", cwd=".")
 
     @patch("pkgmgr.actions.branch.close_branch.get_current_branch", side_effect=GitError("fail"))
-    def test_close_branch_errors_if_cannot_detect_branch(self, current):
+    def test_close_branch_errors_if_cannot_detect_branch(self, _current) -> None:
         with self.assertRaises(RuntimeError):
             close_branch(None)
 
+    @patch("builtins.input", return_value="y")
+    @patch("pkgmgr.actions.branch.close_branch.get_current_branch", return_value="feature-x")
+    @patch("pkgmgr.actions.branch.close_branch.resolve_base_branch", return_value="main")
+    @patch("pkgmgr.actions.branch.close_branch.fetch")
+    @patch("pkgmgr.actions.branch.close_branch.checkout")
+    @patch("pkgmgr.actions.branch.close_branch.pull")
+    @patch("pkgmgr.actions.branch.close_branch.merge_no_ff")
+    @patch("pkgmgr.actions.branch.close_branch.push")
+    @patch("pkgmgr.actions.branch.close_branch.delete_local_branch")
+    @patch(
+        "pkgmgr.actions.branch.close_branch.delete_remote_branch",
+        side_effect=GitDeleteRemoteBranchError("boom", cwd="."),
+    )
+    def test_close_branch_remote_delete_failure_is_wrapped(
+        self,
+        _delete_remote_branch,
+        _delete_local_branch,
+        _push,
+        _merge_no_ff,
+        _pull,
+        _checkout,
+        _fetch,
+        _resolve,
+        _current,
+        _input_mock,
+    ) -> None:
+        with self.assertRaises(RuntimeError) as ctx:
+            close_branch(None, cwd=".")
+        self.assertIn("remote deletion failed", str(ctx.exception))
+
 
 if __name__ == "__main__":
     unittest.main()

tests/unit/pkgmgr/actions/branch/test_drop_branch.py

@@ -2,49 +2,79 @@ import unittest
 from unittest.mock import patch
 
 from pkgmgr.actions.branch.drop_branch import drop_branch
-from pkgmgr.core.git import GitError
+from pkgmgr.core.git.errors import GitError
+from pkgmgr.core.git.commands import GitDeleteRemoteBranchError
 
 
 class TestDropBranch(unittest.TestCase):
-    @patch("pkgmgr.actions.branch.drop_branch.input", return_value="y")
+    @patch("builtins.input", return_value="y")
     @patch("pkgmgr.actions.branch.drop_branch.get_current_branch", return_value="feature-x")
-    @patch("pkgmgr.actions.branch.drop_branch._resolve_base_branch", return_value="main")
-    @patch("pkgmgr.actions.branch.drop_branch.run_git")
-    def test_drop_branch_happy_path(self, run_git, resolve, current, input_mock):
+    @patch("pkgmgr.actions.branch.drop_branch.resolve_base_branch", return_value="main")
+    @patch("pkgmgr.actions.branch.drop_branch.delete_local_branch")
+    @patch("pkgmgr.actions.branch.drop_branch.delete_remote_branch")
+    def test_drop_branch_happy_path(self, delete_remote, delete_local, _resolve, _current, _input_mock) -> None:
         drop_branch(None, cwd=".")
-        expected = [
-            (["branch", "-d", "feature-x"],),
-            (["push", "origin", "--delete", "feature-x"],),
-        ]
-        actual = [call.args for call in run_git.call_args_list]
-        self.assertEqual(actual, expected)
+        delete_local.assert_called_once_with("feature-x", cwd=".", force=False)
+        delete_remote.assert_called_once_with("origin", "feature-x", cwd=".")
 
     @patch("pkgmgr.actions.branch.drop_branch.get_current_branch", return_value="main")
-    @patch("pkgmgr.actions.branch.drop_branch._resolve_base_branch", return_value="main")
-    def test_refuses_to_drop_base_branch(self, resolve, current):
+    @patch("pkgmgr.actions.branch.drop_branch.resolve_base_branch", return_value="main")
+    def test_refuses_to_drop_base_branch(self, _resolve, _current) -> None:
         with self.assertRaises(RuntimeError):
             drop_branch(None)
 
-    @patch("pkgmgr.actions.branch.drop_branch.input", return_value="n")
+    @patch("builtins.input", return_value="n")
     @patch("pkgmgr.actions.branch.drop_branch.get_current_branch", return_value="feature-x")
-    @patch("pkgmgr.actions.branch.drop_branch._resolve_base_branch", return_value="main")
-    @patch("pkgmgr.actions.branch.drop_branch.run_git")
-    def test_drop_branch_aborts_on_no(self, run_git, resolve, current, input_mock):
+    @patch("pkgmgr.actions.branch.drop_branch.resolve_base_branch", return_value="main")
+    @patch("pkgmgr.actions.branch.drop_branch.delete_local_branch")
+    def test_drop_branch_aborts_on_no(self, delete_local, _resolve, _current, _input_mock) -> None:
         drop_branch(None, cwd=".")
-        run_git.assert_not_called()
+        delete_local.assert_not_called()
 
+    @patch("builtins.input")
     @patch("pkgmgr.actions.branch.drop_branch.get_current_branch", return_value="feature-x")
-    @patch("pkgmgr.actions.branch.drop_branch._resolve_base_branch", return_value="main")
-    @patch("pkgmgr.actions.branch.drop_branch.run_git")
-    def test_drop_branch_force_skips_prompt(self, run_git, resolve, current):
+    @patch("pkgmgr.actions.branch.drop_branch.resolve_base_branch", return_value="main")
+    @patch("pkgmgr.actions.branch.drop_branch.delete_local_branch")
+    @patch("pkgmgr.actions.branch.drop_branch.delete_remote_branch")
+    def test_drop_branch_force_skips_prompt(
+        self,
+        delete_remote,
+        delete_local,
+        _resolve,
+        _current,
+        input_mock,
+    ) -> None:
         drop_branch(None, cwd=".", force=True)
-        self.assertGreater(len(run_git.call_args_list), 0)
+
+        input_mock.assert_not_called()
+        delete_local.assert_called_once_with("feature-x", cwd=".", force=False)
+        delete_remote.assert_called_once_with("origin", "feature-x", cwd=".")
 
     @patch("pkgmgr.actions.branch.drop_branch.get_current_branch", side_effect=GitError("fail"))
-    def test_drop_branch_errors_if_no_branch_detected(self, current):
+    def test_drop_branch_errors_if_no_branch_detected(self, _current) -> None:
         with self.assertRaises(RuntimeError):
             drop_branch(None)
 
+    @patch("builtins.input", return_value="y")
+    @patch("pkgmgr.actions.branch.drop_branch.get_current_branch", return_value="feature-x")
+    @patch("pkgmgr.actions.branch.drop_branch.resolve_base_branch", return_value="main")
+    @patch("pkgmgr.actions.branch.drop_branch.delete_local_branch")
+    @patch(
+        "pkgmgr.actions.branch.drop_branch.delete_remote_branch",
+        side_effect=GitDeleteRemoteBranchError("boom", cwd="."),
+    )
+    def test_drop_branch_remote_delete_failure_is_wrapped(
+        self,
+        _delete_remote,
+        _delete_local,
+        _resolve,
+        _current,
+        _input_mock,
+    ) -> None:
+        with self.assertRaises(RuntimeError) as ctx:
+            drop_branch(None, cwd=".")
+        self.assertIn("remote deletion failed", str(ctx.exception))
+
 
 if __name__ == "__main__":
     unittest.main()

tests/unit/pkgmgr/actions/branch/test_open_branch.py

@@ -5,29 +5,55 @@ from pkgmgr.actions.branch.open_branch import open_branch
 
 
 class TestOpenBranch(unittest.TestCase):
-    @patch("pkgmgr.actions.branch.open_branch._resolve_base_branch", return_value="main")
-    @patch("pkgmgr.actions.branch.open_branch.run_git")
-    def test_open_branch_executes_git_commands(self, run_git, resolve):
+    @patch("pkgmgr.actions.branch.open_branch.resolve_base_branch", return_value="main")
+    @patch("pkgmgr.actions.branch.open_branch.fetch")
+    @patch("pkgmgr.actions.branch.open_branch.checkout")
+    @patch("pkgmgr.actions.branch.open_branch.pull")
+    @patch("pkgmgr.actions.branch.open_branch.create_branch")
+    @patch("pkgmgr.actions.branch.open_branch.push_upstream")
+    def test_open_branch_executes_git_commands(
+        self,
+        push_upstream,
+        create_branch,
+        pull,
+        checkout,
+        fetch,
+        _resolve,
+    ) -> None:
         open_branch("feature-x", base_branch="main", cwd=".")
-        expected_calls = [
-            (["fetch", "origin"],),
-            (["checkout", "main"],),
-            (["pull", "origin", "main"],),
-            (["checkout", "-b", "feature-x"],),
-            (["push", "-u", "origin", "feature-x"],),
-        ]
-        actual = [call.args for call in run_git.call_args_list]
-        self.assertEqual(actual, expected_calls)
+
+        fetch.assert_called_once_with("origin", cwd=".")
+        checkout.assert_called_once_with("main", cwd=".")
+        pull.assert_called_once_with("origin", "main", cwd=".")
+        create_branch.assert_called_once_with("feature-x", "main", cwd=".")
+        push_upstream.assert_called_once_with("origin", "feature-x", cwd=".")
 
     @patch("builtins.input", return_value="auto-branch")
-    @patch("pkgmgr.actions.branch.open_branch._resolve_base_branch", return_value="main")
-    @patch("pkgmgr.actions.branch.open_branch.run_git")
-    def test_open_branch_prompts_for_name(self, run_git, resolve, input_mock):
+    @patch("pkgmgr.actions.branch.open_branch.resolve_base_branch", return_value="main")
+    @patch("pkgmgr.actions.branch.open_branch.fetch")
+    @patch("pkgmgr.actions.branch.open_branch.checkout")
+    @patch("pkgmgr.actions.branch.open_branch.pull")
+    @patch("pkgmgr.actions.branch.open_branch.create_branch")
+    @patch("pkgmgr.actions.branch.open_branch.push_upstream")
+    def test_open_branch_prompts_for_name(
+        self,
+        push_upstream,
+        create_branch,
+        pull,
+        checkout,
+        fetch,
+        _resolve,
+        _input_mock,
+    ) -> None:
         open_branch(None)
-        calls = [call.args for call in run_git.call_args_list]
-        self.assertEqual(calls[3][0][0], "checkout")  # verify git executed normally
 
-    def test_open_branch_rejects_empty_name(self):
+        fetch.assert_called_once_with("origin", cwd=".")
+        checkout.assert_called_once_with("main", cwd=".")
+        pull.assert_called_once_with("origin", "main", cwd=".")
+        create_branch.assert_called_once_with("auto-branch", "main", cwd=".")
+        push_upstream.assert_called_once_with("origin", "auto-branch", cwd=".")
+
+    def test_open_branch_rejects_empty_name(self) -> None:
         with patch("builtins.input", return_value=""):
             with self.assertRaises(RuntimeError):
                 open_branch(None)

tests/unit/pkgmgr/actions/mirror/test_git_remote.py

@@ -21,46 +21,34 @@ class TestMirrorGitRemote(unittest.TestCase):
         )
 
     def test_build_default_ssh_url(self) -> None:
-        repo = {
-            "provider": "github.com",
-            "account": "alice",
-            "repository": "repo",
-        }
-        self.assertEqual(
-            build_default_ssh_url(repo),
-            "git@github.com:alice/repo.git",
-        )
-
-    def test_determine_primary_prefers_origin(self) -> None:
         repo = {"provider": "github.com", "account": "alice", "repository": "repo"}
-        ctx = self._ctx(config={"origin": "git@github.com:alice/repo.git"})
-        self.assertEqual(
-            determine_primary_remote_url(repo, ctx),
-            "git@github.com:alice/repo.git",
-        )
+        self.assertEqual(build_default_ssh_url(repo), "git@github.com:alice/repo.git")
 
-    def test_determine_primary_uses_file_order(self) -> None:
+    def test_determine_primary_prefers_origin_in_resolved(self) -> None:
+        # resolved_mirrors = config + file (file wins), so put origin in file.
         repo = {"provider": "github.com", "account": "alice", "repository": "repo"}
-        ctx = self._ctx(
-            file={
-                "first": "git@a/first.git",
-                "second": "git@a/second.git",
-            }
-        )
-        self.assertEqual(
-            determine_primary_remote_url(repo, ctx),
-            "git@a/first.git",
-        )
+        ctx = self._ctx(file={"origin": "git@github.com:alice/repo.git"})
+        self.assertEqual(determine_primary_remote_url(repo, ctx), "git@github.com:alice/repo.git")
+
+    def test_determine_primary_falls_back_to_file_order(self) -> None:
+        repo = {"provider": "github.com", "account": "alice", "repository": "repo"}
+        ctx = self._ctx(file={"first": "git@a/first.git", "second": "git@a/second.git"})
+        self.assertEqual(determine_primary_remote_url(repo, ctx), "git@a/first.git")
+
+    def test_determine_primary_falls_back_to_config_order(self) -> None:
+        repo = {"provider": "github.com", "account": "alice", "repository": "repo"}
+        ctx = self._ctx(config={"cfg1": "git@c/one.git", "cfg2": "git@c/two.git"})
+        self.assertEqual(determine_primary_remote_url(repo, ctx), "git@c/one.git")
 
     def test_determine_primary_fallback_default(self) -> None:
         repo = {"provider": "github.com", "account": "alice", "repository": "repo"}
         ctx = self._ctx()
-        self.assertEqual(
-            determine_primary_remote_url(repo, ctx),
-            "git@github.com:alice/repo.git",
-        )
+        self.assertEqual(determine_primary_remote_url(repo, ctx), "git@github.com:alice/repo.git")
 
-    @patch("pkgmgr.actions.mirror.git_remote._safe_git_output")
-    def test_has_origin_remote(self, m_out) -> None:
-        m_out.return_value = "origin\nupstream\n"
+    @patch("pkgmgr.actions.mirror.git_remote.list_remotes", return_value=["origin", "backup"])
+    def test_has_origin_remote_true(self, _m_list) -> None:
         self.assertTrue(has_origin_remote("/tmp/repo"))
+
+    @patch("pkgmgr.actions.mirror.git_remote.list_remotes", return_value=["backup"])
+    def test_has_origin_remote_false(self, _m_list) -> None:
+        self.assertFalse(has_origin_remote("/tmp/repo"))

tests/unit/pkgmgr/actions/mirror/test_git_remote_primary_push.py

@@ -10,6 +10,8 @@ from pkgmgr.actions.mirror.types import RepoMirrorContext
 class TestGitRemotePrimaryPush(unittest.TestCase):
     def test_origin_created_and_extra_push_added(self) -> None:
         repo = {"provider": "github.com", "account": "alice", "repository": "repo"}
+
+        # Use file_mirrors so ctx.resolved_mirrors contains both, no setattr (frozen dataclass!)
         ctx = RepoMirrorContext(
             identifier="repo",
             repo_dir="/tmp/repo",
@@ -20,31 +22,44 @@ class TestGitRemotePrimaryPush(unittest.TestCase):
             },
         )
 
-        executed: list[str] = []
+        with patch("os.path.isdir", return_value=True):
+            with patch("pkgmgr.actions.mirror.git_remote.has_origin_remote", return_value=False), patch(
+                "pkgmgr.actions.mirror.git_remote.add_remote"
+            ) as m_add_remote, patch(
+                "pkgmgr.actions.mirror.git_remote.set_remote_url"
+            ) as m_set_remote_url, patch(
+                "pkgmgr.actions.mirror.git_remote.get_remote_push_urls", return_value=set()
+            ), patch(
+                "pkgmgr.actions.mirror.git_remote.add_remote_push_url"
+            ) as m_add_push:
+                ensure_origin_remote(repo, ctx, preview=False)
 
-        def fake_run(cmd: str, cwd: str, preview: bool) -> None:
-            executed.append(cmd)
-
-        def fake_git(args, cwd):
-            if args == ["remote"]:
-                return ""
-            if args == ["remote", "get-url", "--push", "--all", "origin"]:
-                return "git@github.com:alice/repo.git\n"
-            return ""
-
-        with patch("os.path.isdir", return_value=True), patch(
-            "pkgmgr.actions.mirror.git_remote.run_command", side_effect=fake_run
-        ), patch(
-            "pkgmgr.actions.mirror.git_remote._safe_git_output", side_effect=fake_git
-        ):
-            ensure_origin_remote(repo, ctx, preview=False)
-
-        self.assertEqual(
-            executed,
-            [
-                "git remote add origin git@github.com:alice/repo.git",
-                "git remote set-url origin git@github.com:alice/repo.git",
-                "git remote set-url --push origin git@github.com:alice/repo.git",
-                "git remote set-url --add --push origin git@github.com:alice/repo-backup.git",
-            ],
+        # determine_primary_remote_url falls back to file order (primary first)
+        m_add_remote.assert_called_once_with(
+            "origin",
+            "git@github.com:alice/repo.git",
+            cwd="/tmp/repo",
+            preview=False,
+        )
+
+        m_set_remote_url.assert_any_call(
+            "origin",
+            "git@github.com:alice/repo.git",
+            cwd="/tmp/repo",
+            push=False,
+            preview=False,
+        )
+        m_set_remote_url.assert_any_call(
+            "origin",
+            "git@github.com:alice/repo.git",
+            cwd="/tmp/repo",
+            push=True,
+            preview=False,
+        )
+
+        m_add_push.assert_called_once_with(
+            "origin",
+            "git@github.com:alice/repo-backup.git",
+            cwd="/tmp/repo",
+            preview=False,
         )

tests/unit/pkgmgr/actions/mirror/test_remote_check.py

@@ -1,52 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-
-from __future__ import annotations
-
-import unittest
-from unittest.mock import patch
-
-from pkgmgr.actions.mirror.remote_check import probe_mirror
-from pkgmgr.core.git import GitError
-
-
-class TestRemoteCheck(unittest.TestCase):
-    """
-    Unit tests for non-destructive remote probing (git ls-remote).
-    """
-
-    @patch("pkgmgr.actions.mirror.remote_check.run_git")
-    def test_probe_mirror_success_returns_true_and_empty_message(self, mock_run_git) -> None:
-        mock_run_git.return_value = "dummy-output"
-
-        ok, message = probe_mirror(
-            "ssh://git@code.example.org:2201/alice/repo.git",
-            "/tmp/some-repo",
-        )
-
-        self.assertTrue(ok)
-        self.assertEqual(message, "")
-        mock_run_git.assert_called_once_with(
-            ["ls-remote", "ssh://git@code.example.org:2201/alice/repo.git"],
-            cwd="/tmp/some-repo",
-        )
-
-    @patch("pkgmgr.actions.mirror.remote_check.run_git")
-    def test_probe_mirror_failure_returns_false_and_error_message(self, mock_run_git) -> None:
-        mock_run_git.side_effect = GitError("Git command failed (simulated)")
-
-        ok, message = probe_mirror(
-            "ssh://git@code.example.org:2201/alice/repo.git",
-            "/tmp/some-repo",
-        )
-
-        self.assertFalse(ok)
-        self.assertIn("Git command failed", message)
-        mock_run_git.assert_called_once_with(
-            ["ls-remote", "ssh://git@code.example.org:2201/alice/repo.git"],
-            cwd="/tmp/some-repo",
-        )
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/unit/pkgmgr/actions/mirror/test_setup_cmd.py

@@ -8,16 +8,10 @@ from pkgmgr.actions.mirror.types import RepoMirrorContext
 
 
 class TestMirrorSetupCmd(unittest.TestCase):
-    def _ctx(
-        self,
-        *,
-        repo_dir: str = "/tmp/repo",
-        resolved: dict[str, str] | None = None,
-    ) -> RepoMirrorContext:
-        # RepoMirrorContext derives resolved via property (config + file)
-        # We feed mirrors via file_mirrors to keep insertion order realistic.
+    def _ctx(self, *, repo_dir: str = "/tmp/repo", resolved: dict[str, str] | None = None) -> RepoMirrorContext:
+        # resolved_mirrors is a @property combining config+file. Put it into file_mirrors.
         return RepoMirrorContext(
-            identifier="repo-id",
+            identifier="repo",
             repo_dir=repo_dir,
             config_mirrors={},
             file_mirrors=resolved or {},
@@ -26,7 +20,8 @@ class TestMirrorSetupCmd(unittest.TestCase):
     @patch("pkgmgr.actions.mirror.setup_cmd.build_context")
     @patch("pkgmgr.actions.mirror.setup_cmd.ensure_origin_remote")
     def test_setup_mirrors_local_calls_ensure_origin_remote(self, m_ensure, m_ctx) -> None:
-        m_ctx.return_value = self._ctx(repo_dir="/tmp/repo", resolved={"primary": "git@x/y.git"})
+        ctx = self._ctx(repo_dir="/tmp/repo", resolved={"primary": "git@x/y.git"})
+        m_ctx.return_value = ctx
 
         repos = [{"provider": "github.com", "account": "alice", "repository": "repo"}]
         setup_mirrors(
@@ -39,24 +34,21 @@ class TestMirrorSetupCmd(unittest.TestCase):
             ensure_remote=False,
         )
 
-        self.assertEqual(m_ensure.call_count, 1)
+        # ensure_origin_remote(repo, ctx, preview) is called positionally in your code
+        m_ensure.assert_called_once()
         args, kwargs = m_ensure.call_args
 
-        # ensure_origin_remote(repo, ctx, preview) may be positional or kw.
-        # Accept both to avoid coupling tests to call style.
-        if "preview" in kwargs:
-            self.assertTrue(kwargs["preview"])
-        else:
-            # args: (repo, ctx, preview)
-            self.assertTrue(args[2])
+        self.assertEqual(args[0], repos[0])
+        self.assertIs(args[1], ctx)
+        self.assertEqual(kwargs.get("preview", args[2] if len(args) >= 3 else None), True)
 
     @patch("pkgmgr.actions.mirror.setup_cmd.build_context")
-    @patch("pkgmgr.actions.mirror.setup_cmd.probe_mirror")
     @patch("pkgmgr.actions.mirror.setup_cmd.determine_primary_remote_url")
-    def test_setup_mirrors_remote_no_mirrors_probes_primary(self, m_primary, m_probe, m_ctx) -> None:
+    @patch("pkgmgr.actions.mirror.setup_cmd.probe_remote_reachable")
+    def test_setup_mirrors_remote_no_mirrors_probes_primary(self, m_probe, m_primary, m_ctx) -> None:
         m_ctx.return_value = self._ctx(repo_dir="/tmp/repo", resolved={})
         m_primary.return_value = "git@github.com:alice/repo.git"
-        m_probe.return_value = (True, "")
+        m_probe.return_value = True
 
         repos = [{"provider": "github.com", "account": "alice", "repository": "repo"}]
         setup_mirrors(
@@ -70,10 +62,10 @@ class TestMirrorSetupCmd(unittest.TestCase):
         )
 
         m_primary.assert_called()
-        m_probe.assert_called_with("git@github.com:alice/repo.git", "/tmp/repo")
+        m_probe.assert_called_once_with("git@github.com:alice/repo.git", cwd="/tmp/repo")
 
     @patch("pkgmgr.actions.mirror.setup_cmd.build_context")
-    @patch("pkgmgr.actions.mirror.setup_cmd.probe_mirror")
+    @patch("pkgmgr.actions.mirror.setup_cmd.probe_remote_reachable")
     def test_setup_mirrors_remote_with_mirrors_probes_each(self, m_probe, m_ctx) -> None:
         m_ctx.return_value = self._ctx(
             repo_dir="/tmp/repo",
@@ -82,7 +74,7 @@ class TestMirrorSetupCmd(unittest.TestCase):
                 "backup": "ssh://git@git.veen.world:2201/alice/repo.git",
             },
         )
-        m_probe.return_value = (True, "")
+        m_probe.return_value = True
 
         repos = [{"provider": "github.com", "account": "alice", "repository": "repo"}]
         setup_mirrors(
@@ -96,6 +88,8 @@ class TestMirrorSetupCmd(unittest.TestCase):
         )
 
         self.assertEqual(m_probe.call_count, 2)
+        m_probe.assert_any_call("git@github.com:alice/repo.git", cwd="/tmp/repo")
+        m_probe.assert_any_call("ssh://git@git.veen.world:2201/alice/repo.git", cwd="/tmp/repo")
 
 
 if __name__ == "__main__":

tests/unit/pkgmgr/actions/publish/test_git_tags.py

@@ -1,4 +1,3 @@
-
 import unittest
 from unittest.mock import patch
 
@@ -6,15 +5,10 @@ from pkgmgr.actions.publish.git_tags import head_semver_tags
 
 
 class TestHeadSemverTags(unittest.TestCase):
-    @patch("pkgmgr.actions.publish.git_tags.run_git")
-    def test_no_tags(self, mock_run_git):
-        mock_run_git.return_value = ""
+    @patch("pkgmgr.actions.publish.git_tags.get_tags_at_ref", return_value=[])
+    def test_no_tags(self, _mock_get_tags_at_ref) -> None:
         self.assertEqual(head_semver_tags(), [])
 
-    @patch("pkgmgr.actions.publish.git_tags.run_git")
-    def test_filters_and_sorts_semver(self, mock_run_git):
-        mock_run_git.return_value = "v1.0.0\nv2.0.0\nfoo\n"
-        self.assertEqual(
-            head_semver_tags(),
-            ["v1.0.0", "v2.0.0"],
-        )
+    @patch("pkgmgr.actions.publish.git_tags.get_tags_at_ref", return_value=["v2.0.0", "nope", "v1.0.0", "v1.2.0"])
+    def test_filters_and_sorts_semver(self, _mock_get_tags_at_ref) -> None:
+        self.assertEqual(head_semver_tags(), ["v1.0.0", "v1.2.0", "v2.0.0"])

tests/unit/pkgmgr/actions/release/test_git_ops.py

@@ -1,198 +0,0 @@
-from __future__ import annotations
-
-import unittest
-from unittest.mock import patch
-
-from pkgmgr.core.git import GitError
-from pkgmgr.actions.release.git_ops import (
-    ensure_clean_and_synced,
-    is_highest_version_tag,
-    run_git_command,
-    update_latest_tag,
-)
-
-
-class TestRunGitCommand(unittest.TestCase):
-    @patch("pkgmgr.actions.release.git_ops.subprocess.run")
-    def test_run_git_command_success(self, mock_run) -> None:
-        run_git_command("git status")
-        mock_run.assert_called_once()
-        args, kwargs = mock_run.call_args
-        self.assertIn("git status", args[0])
-        self.assertTrue(kwargs.get("check"))
-        self.assertTrue(kwargs.get("capture_output"))
-        self.assertTrue(kwargs.get("text"))
-
-    @patch("pkgmgr.actions.release.git_ops.subprocess.run")
-    def test_run_git_command_failure_raises_git_error(self, mock_run) -> None:
-        from subprocess import CalledProcessError
-
-        mock_run.side_effect = CalledProcessError(
-            returncode=1,
-            cmd="git status",
-            output="stdout",
-            stderr="stderr",
-        )
-
-        with self.assertRaises(GitError):
-            run_git_command("git status")
-
-
-class TestEnsureCleanAndSynced(unittest.TestCase):
-    def _fake_run(self, cmd: str, *args, **kwargs):
-        class R:
-            def __init__(self, stdout: str = "", stderr: str = "", returncode: int = 0):
-                self.stdout = stdout
-                self.stderr = stderr
-                self.returncode = returncode
-
-        # upstream detection
-        if "git rev-parse --abbrev-ref --symbolic-full-name @{u}" in cmd:
-            return R(stdout="origin/main")
-
-        # fetch/pull should be invoked in real mode
-        if cmd == "git fetch --prune --tags":
-            return R(stdout="")
-        if cmd == "git pull --ff-only":
-            return R(stdout="Already up to date.")
-
-        return R(stdout="")
-
-    @patch("pkgmgr.actions.release.git_ops.subprocess.run")
-    def test_ensure_clean_and_synced_preview_does_not_run_git_commands(self, mock_run) -> None:
-        def fake(cmd: str, *args, **kwargs):
-            class R:
-                def __init__(self, stdout: str = ""):
-                    self.stdout = stdout
-                    self.stderr = ""
-                    self.returncode = 0
-
-            if "git rev-parse --abbrev-ref --symbolic-full-name @{u}" in cmd:
-                return R(stdout="origin/main")
-            return R(stdout="")
-
-        mock_run.side_effect = fake
-
-        ensure_clean_and_synced(preview=True)
-
-        called_cmds = [c.args[0] for c in mock_run.call_args_list]
-        self.assertTrue(any("git rev-parse" in c for c in called_cmds))
-        self.assertFalse(any(c == "git fetch --prune --tags" for c in called_cmds))
-        self.assertFalse(any(c == "git pull --ff-only" for c in called_cmds))
-
-    @patch("pkgmgr.actions.release.git_ops.subprocess.run")
-    def test_ensure_clean_and_synced_no_upstream_skips(self, mock_run) -> None:
-        def fake(cmd: str, *args, **kwargs):
-            class R:
-                def __init__(self, stdout: str = ""):
-                    self.stdout = stdout
-                    self.stderr = ""
-                    self.returncode = 0
-
-            if "git rev-parse --abbrev-ref --symbolic-full-name @{u}" in cmd:
-                return R(stdout="")  # no upstream
-            return R(stdout="")
-
-        mock_run.side_effect = fake
-
-        ensure_clean_and_synced(preview=False)
-
-        called_cmds = [c.args[0] for c in mock_run.call_args_list]
-        self.assertTrue(any("git rev-parse" in c for c in called_cmds))
-        self.assertFalse(any(c == "git fetch --prune --tags" for c in called_cmds))
-        self.assertFalse(any(c == "git pull --ff-only" for c in called_cmds))
-
-    @patch("pkgmgr.actions.release.git_ops.subprocess.run")
-    def test_ensure_clean_and_synced_real_runs_fetch_and_pull(self, mock_run) -> None:
-        mock_run.side_effect = self._fake_run
-
-        ensure_clean_and_synced(preview=False)
-
-        called_cmds = [c.args[0] for c in mock_run.call_args_list]
-        self.assertIn("git fetch origin --prune --tags --force", called_cmds)
-        self.assertIn("git pull --ff-only", called_cmds)
-
-
-
-class TestIsHighestVersionTag(unittest.TestCase):
-    @patch("pkgmgr.actions.release.git_ops.subprocess.run")
-    def test_is_highest_version_tag_no_tags_true(self, mock_run) -> None:
-        def fake(cmd: str, *args, **kwargs):
-            class R:
-                def __init__(self, stdout: str = ""):
-                    self.stdout = stdout
-                    self.stderr = ""
-                    self.returncode = 0
-
-            if "git tag --list" in cmd and "'v*'" in cmd:
-                return R(stdout="")  # no tags
-            return R(stdout="")
-
-        mock_run.side_effect = fake
-
-        self.assertTrue(is_highest_version_tag("v1.0.0"))
-
-        # ensure at least the list command was queried
-        called_cmds = [c.args[0] for c in mock_run.call_args_list]
-        self.assertTrue(any("git tag --list" in c for c in called_cmds))
-
-    @patch("pkgmgr.actions.release.git_ops.subprocess.run")
-    def test_is_highest_version_tag_compares_sort_v(self, mock_run) -> None:
-        """
-        This test is aligned with the CURRENT implementation:
-
-            return tag >= latest
-
-        which is a *string comparison*, not a semantic version compare.
-        Therefore, a candidate like v1.2.0 is lexicographically >= v1.10.0
-        (because '2' > '1' at the first differing char after 'v1.').
-        """
-        def fake(cmd: str, *args, **kwargs):
-            class R:
-                def __init__(self, stdout: str = ""):
-                    self.stdout = stdout
-                    self.stderr = ""
-                    self.returncode = 0
-
-            if cmd.strip() == "git tag --list 'v*'":
-                return R(stdout="v1.0.0\nv1.2.0\nv1.10.0\n")
-            if "git tag --list 'v*'" in cmd and "sort -V" in cmd and "tail -n1" in cmd:
-                return R(stdout="v1.10.0")
-            return R(stdout="")
-
-        mock_run.side_effect = fake
-
-        # With the current implementation (string >=), both of these are True.
-        self.assertTrue(is_highest_version_tag("v1.10.0"))
-        self.assertTrue(is_highest_version_tag("v1.2.0"))
-
-        # And a clearly lexicographically smaller candidate should be False.
-        # Example: "v1.0.0" < "v1.10.0"
-        self.assertFalse(is_highest_version_tag("v1.0.0"))
-
-        # Ensure both capture commands were executed
-        called_cmds = [c.args[0] for c in mock_run.call_args_list]
-        self.assertTrue(any(cmd == "git tag --list 'v*'" for cmd in called_cmds))
-        self.assertTrue(any("sort -V" in cmd and "tail -n1" in cmd for cmd in called_cmds))
-
-
-class TestUpdateLatestTag(unittest.TestCase):
-    @patch("pkgmgr.actions.release.git_ops.run_git_command")
-    def test_update_latest_tag_preview_does_not_call_git(self, mock_run_git_command) -> None:
-        update_latest_tag("v1.2.3", preview=True)
-        mock_run_git_command.assert_not_called()
-
-    @patch("pkgmgr.actions.release.git_ops.run_git_command")
-    def test_update_latest_tag_real_calls_git(self, mock_run_git_command) -> None:
-        update_latest_tag("v1.2.3", preview=False)
-
-        calls = [c.args[0] for c in mock_run_git_command.call_args_list]
-        self.assertIn(
-            'git tag -f -a latest v1.2.3^{} -m "Floating latest tag for v1.2.3"',
-            calls,
-        )
-        self.assertIn("git push origin latest --force", calls)
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/unit/pkgmgr/actions/release/test_git_ops_ensure_clean_and_synced.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import unittest
+from unittest.mock import patch
+
+from pkgmgr.actions.release.git_ops import ensure_clean_and_synced
+
+
+class TestEnsureCleanAndSynced(unittest.TestCase):
+    @patch("pkgmgr.actions.release.git_ops.pull_ff_only")
+    @patch("pkgmgr.actions.release.git_ops.fetch")
+    @patch("pkgmgr.actions.release.git_ops.get_upstream_ref")
+    def test_no_upstream_skips(
+        self,
+        mock_get_upstream_ref,
+        mock_fetch,
+        mock_pull_ff_only,
+    ) -> None:
+        mock_get_upstream_ref.return_value = None
+
+        ensure_clean_and_synced(preview=False)
+
+        mock_fetch.assert_not_called()
+        mock_pull_ff_only.assert_not_called()
+
+    @patch("pkgmgr.actions.release.git_ops.pull_ff_only")
+    @patch("pkgmgr.actions.release.git_ops.fetch")
+    @patch("pkgmgr.actions.release.git_ops.get_upstream_ref")
+    def test_preview_calls_commands_with_preview_true(
+        self,
+        mock_get_upstream_ref,
+        mock_fetch,
+        mock_pull_ff_only,
+    ) -> None:
+        mock_get_upstream_ref.return_value = "origin/main"
+
+        ensure_clean_and_synced(preview=True)
+
+        mock_fetch.assert_called_once_with(
+            remote="origin",
+            prune=True,
+            tags=True,
+            force=True,
+            preview=True,
+        )
+        mock_pull_ff_only.assert_called_once_with(preview=True)
+
+    @patch("pkgmgr.actions.release.git_ops.pull_ff_only")
+    @patch("pkgmgr.actions.release.git_ops.fetch")
+    @patch("pkgmgr.actions.release.git_ops.get_upstream_ref")
+    def test_real_calls_commands_with_preview_false(
+        self,
+        mock_get_upstream_ref,
+        mock_fetch,
+        mock_pull_ff_only,
+    ) -> None:
+        mock_get_upstream_ref.return_value = "origin/main"
+
+        ensure_clean_and_synced(preview=False)
+
+        mock_fetch.assert_called_once_with(
+            remote="origin",
+            prune=True,
+            tags=True,
+            force=True,
+            preview=False,
+        )
+        mock_pull_ff_only.assert_called_once_with(preview=False)

tests/unit/pkgmgr/actions/release/test_git_ops_is_highest_version_tag.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import unittest
+from unittest.mock import patch
+
+from pkgmgr.actions.release.git_ops import is_highest_version_tag
+
+
+class TestIsHighestVersionTag(unittest.TestCase):
+    @patch("pkgmgr.actions.release.git_ops.list_tags")
+    def test_no_tags_returns_true(self, mock_list_tags) -> None:
+        mock_list_tags.return_value = []
+        self.assertTrue(is_highest_version_tag("v1.0.0"))
+        mock_list_tags.assert_called_once_with("v*")
+
+    @patch("pkgmgr.actions.release.git_ops.list_tags")
+    def test_parseable_semver_compares_correctly(self, mock_list_tags) -> None:
+        # Highest is v1.10.0 (semantic compare)
+        mock_list_tags.return_value = ["v1.0.0", "v1.2.0", "v1.10.0"]
+
+        self.assertTrue(is_highest_version_tag("v1.10.0"))
+        self.assertFalse(is_highest_version_tag("v1.2.0"))
+        self.assertFalse(is_highest_version_tag("v1.0.0"))
+
+    @patch("pkgmgr.actions.release.git_ops.list_tags")
+    def test_ignores_non_parseable_v_tags_for_semver_compare(self, mock_list_tags) -> None:
+        mock_list_tags.return_value = ["v1.2.0", "v1.10.0", "v1.2.0-rc1", "vfoo"]
+
+        self.assertTrue(is_highest_version_tag("v1.10.0"))
+        self.assertFalse(is_highest_version_tag("v1.2.0"))
+
+    @patch("pkgmgr.actions.release.git_ops.list_tags")
+    def test_current_tag_not_parseable_falls_back_to_lex_compare(self, mock_list_tags) -> None:
+        mock_list_tags.return_value = ["v1.9.0", "v1.10.0"]
+
+        # prerelease must NOT outrank the final release
+        self.assertFalse(is_highest_version_tag("v1.10.0-rc1"))
+        self.assertFalse(is_highest_version_tag("v1.0.0-rc1"))
+
+