gpt-5.2: fix tests and imports after git queries split

https://chatgpt.com/share/694135eb-10a8-800f-8b12-968612f605c7

Gemini
https://ai.studio/apps/drive/1QO9MaEklm2zZMDZ6XPP0LStuAooXs1NO

.github/workflows/ci.yml

@@ -28,8 +28,8 @@ jobs:
   test-virgin-root:
     uses: ./.github/workflows/test-virgin-root.yml
 
-  codesniffer-shellcheck:
-    uses: ./.github/workflows/codesniffer-shellcheck.yml
+  lint-shell:
+    uses: ./.github/workflows/lint-shell.yml
 
-  codesniffer-ruff:
-    uses: ./.github/workflows/codesniffer-ruff.yml
+  lint-python:
+    uses: ./.github/workflows/lint-python.yml

.github/workflows/lint-python.yml

@@ -4,7 +4,7 @@ on:
   workflow_call:
 
 jobs:
-  codesniffer-ruff:
+  lint-python:
     runs-on: ubuntu-latest
 
     steps:

.github/workflows/lint-shell.yml

@@ -4,7 +4,7 @@ on:
   workflow_call:
 
 jobs:
-  codesniffer-shellcheck:
+  lint-shell:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4

.github/workflows/mark-stable.yml

@@ -29,16 +29,16 @@ jobs:
   test-virgin-root:
     uses: ./.github/workflows/test-virgin-root.yml
 
-  codesniffer-shellcheck:
-    uses: ./.github/workflows/codesniffer-shellcheck.yml
+  lint-shell:
+    uses: ./.github/workflows/lint-shell.yml
 
-  codesniffer-ruff:
-    uses: ./.github/workflows/codesniffer-ruff.yml
+  lint-python:
+    uses: ./.github/workflows/lint-python.yml
 
   mark-stable:
     needs:
-      - codesniffer-shellcheck
-      - codesniffer-ruff
+      - lint-shell
+      - lint-python
       - test-unit
       - test-integration
       - test-env-nix

.github/workflows/publish-containers.yml

@@ -19,7 +19,6 @@ jobs:
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
-          fetch-tags: true
 
       - name: Checkout workflow_run commit and refresh tags
         run: |
@@ -35,22 +34,30 @@ jobs:
           SHA="$(git rev-parse HEAD)"
 
           V_TAG="$(git tag --points-at "${SHA}" --list 'v*' | sort -V | tail -n1)"
-          [[ -n "$V_TAG" ]] || { echo "No version tag found"; exit 1; }
+          if [[ -z "${V_TAG}" ]]; then
+            echo "No version tag found for ${SHA}. Skipping publish."
+            echo "should_publish=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
           VERSION="${V_TAG#v}"
 
           STABLE_SHA="$(git rev-parse -q --verify refs/tags/stable^{commit} 2>/dev/null || true)"
           IS_STABLE=false
           [[ -n "${STABLE_SHA}" && "${STABLE_SHA}" == "${SHA}" ]] && IS_STABLE=true
 
+          echo "should_publish=true" >> "$GITHUB_OUTPUT"
           echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
           echo "is_stable=${IS_STABLE}" >> "$GITHUB_OUTPUT"
 
       - name: Set up Docker Buildx
+        if: ${{ steps.info.outputs.should_publish == 'true' }}
         uses: docker/setup-buildx-action@v3
         with:
           use: true
 
       - name: Login to GHCR
+        if: ${{ steps.info.outputs.should_publish == 'true' }}
         uses: docker/login-action@v3
         with:
           registry: ghcr.io
@@ -58,6 +65,7 @@ jobs:
           password: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Publish all images
+        if: ${{ steps.info.outputs.should_publish == 'true' }}
         run: |
           set -euo pipefail
           OWNER="${{ github.repository_owner }}" \

CHANGELOG.md

@@ -1,3 +1,54 @@
+## [1.8.0] - 2025-12-15
+
+* *** 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.
+- **Repository Scaffolding**: The process for creating new repositories has been improved. You can now use templates to scaffold repositories with a preview and automatic mirror setup.
+
+*** Bug Fixes: ***
+- **Pip Installation**: Pip is now installed automatically on all supported systems. This includes `python-pip` for Arch and `python3-pip` for CentOS, Debian, Fedora, and Ubuntu, ensuring that pip is available for Python package installations.
+- **Pacman Keyring**: Fixed an issue on Arch Linux where package installation would fail due to missing keys. The pacman keyring is now properly initialized before installing packages.
+
+
+## [1.7.2] - 2025-12-15
+
+* * Git mirrors are now resolved consistently (origin → MIRRORS file → config → default).
+* The `origin` remote is always enforced to use the primary URL for both fetch and push.
+* Additional mirrors are added as extra push targets without duplication.
+* Local and remote mirror setup behaves more predictably and consistently.
+* Improved test coverage ensures stable origin and push URL handling.
+
+
+## [1.7.1] - 2025-12-14
+
+* Patched package-manager to kpmx to publish on pypi
+
+
+## [1.7.0] - 2025-12-14
+
+* * New *pkgmgr publish* command to publish repository artifacts to PyPI based on the *MIRRORS* file.
+* Automatically selects the current repository when no explicit selection is given.
+* Publishes only when a semantic version tag is present on *HEAD*; otherwise skips with a clear info message.
+* Supports non-interactive mode for CI environments via *--non-interactive*.
+
+
+## [1.6.4] - 2025-12-14
+
+* * Improved reliability of Nix installs and updates, including automatic resolution of profile conflicts and better handling of GitHub 403 rate limits.
+* More stable launcher behavior in packaged and virtual-env setups.
+* Enhanced mirror and remote handling: repository owner/name are derived from URLs, with smoother provisioning and clearer credential handling.
+* More reliable releases and artifacts due to safer CI behavior when no version tag is present.
+
+
+## [1.6.3] - 2025-12-14
+
+* ***Fixed:*** Corrected repository path resolution so release and version logic consistently use the canonical packaging/* layout, preventing changelog and packaging files from being read or updated from incorrect locations.
+
+
+## [1.6.2] - 2025-12-14
+
+* **pkgmgr version** now also shows the installed pkgmgr version when run outside a repository.
+
+
 ## [1.6.1] - 2025-12-14
 
 * * Added automatic retry handling for GitHub 403 / rate-limit errors during Nix flake installs (Fibonacci backoff with jitter).

MIRRORS

@@ -1,3 +1,4 @@
 git@github.com:kevinveenbirkenbach/package-manager.git
 ssh://git@git.veen.world:2201/kevinveenbirkenbach/pkgmgr.git
-ssh://git@code.cymais.cloud:2201/kevinveenbirkenbach/pkgmgr.git
+ssh://git@code.infinito.nexus:2201/kevinveenbirkenbach/pkgmgr.git
+https://pypi.org/project/kpmx/

Makefile

@@ -44,7 +44,7 @@ install:
 # ------------------------------------------------------------
 
 # Default: keep current auto-detection behavior
-setup: setup-nix setup-venv
+setup: setup-venv
 
 # Explicit: developer setup (Python venv + shell RC + install)
 setup-venv: setup-nix

flake.nix

@@ -32,7 +32,7 @@
         rec {
           pkgmgr = pyPkgs.buildPythonApplication {
             pname   = "package-manager";
-            version = "1.6.1";
+            version = "1.8.0";
 
             # Use the git repo as source
             src = ./.;
@@ -49,6 +49,7 @@
             # Runtime dependencies (matches [project.dependencies] in pyproject.toml)
             propagatedBuildInputs = [
               pyPkgs.pyyaml
+              pyPkgs.jinja2
               pyPkgs.pip
             ];
 
@@ -78,6 +79,7 @@
           pythonWithDeps = python.withPackages (ps: [
             ps.pip
             ps.pyyaml
+            ps.jinja2
           ]);
         in
         {

packaging/arch/PKGBUILD

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

packaging/debian/changelog

@@ -1,3 +1,55 @@
+package-manager (1.8.0-1) unstable; urgency=medium
+
+  * *** 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.
+- **Repository Scaffolding**: The process for creating new repositories has been improved. You can now use templates to scaffold repositories with a preview and automatic mirror setup.
+
+*** Bug Fixes: ***
+- **Pip Installation**: Pip is now installed automatically on all supported systems. This includes `python-pip` for Arch and `python3-pip` for CentOS, Debian, Fedora, and Ubuntu, ensuring that pip is available for Python package installations.
+- **Pacman Keyring**: Fixed an issue on Arch Linux where package installation would fail due to missing keys. The pacman keyring is now properly initialized before installing packages.
+
+ -- Kevin Veen-Birkenbach <kevin@veen.world>  Mon, 15 Dec 2025 13:37:42 +0100
+
+package-manager (1.7.2-1) unstable; urgency=medium
+
+  * * Git mirrors are now resolved consistently (origin → MIRRORS file → config → default).
+* The `origin` remote is always enforced to use the primary URL for both fetch and push.
+* Additional mirrors are added as extra push targets without duplication.
+* Local and remote mirror setup behaves more predictably and consistently.
+* Improved test coverage ensures stable origin and push URL handling.
+
+ -- Kevin Veen-Birkenbach <kevin@veen.world>  Mon, 15 Dec 2025 00:53:26 +0100
+
+package-manager (1.7.1-1) unstable; urgency=medium
+
+  * Patched package-manager to kpmx to publish on pypi
+
+ -- Kevin Veen-Birkenbach <kevin@veen.world>  Sun, 14 Dec 2025 21:19:11 +0100
+
+package-manager (1.7.0-1) unstable; urgency=medium
+
+  * * New *pkgmgr publish* command to publish repository artifacts to PyPI based on the *MIRRORS* file.
+* Automatically selects the current repository when no explicit selection is given.
+* Publishes only when a semantic version tag is present on *HEAD*; otherwise skips with a clear info message.
+* Supports non-interactive mode for CI environments via *--non-interactive*.
+
+ -- Kevin Veen-Birkenbach <kevin@veen.world>  Sun, 14 Dec 2025 21:10:06 +0100
+
+package-manager (1.6.4-1) unstable; urgency=medium
+
+  * * Improved reliability of Nix installs and updates, including automatic resolution of profile conflicts and better handling of GitHub 403 rate limits.
+* More stable launcher behavior in packaged and virtual-env setups.
+* Enhanced mirror and remote handling: repository owner/name are derived from URLs, with smoother provisioning and clearer credential handling.
+* More reliable releases and artifacts due to safer CI behavior when no version tag is present.
+
+ -- Kevin Veen-Birkenbach <kevin@veen.world>  Sun, 14 Dec 2025 19:33:07 +0100
+
+package-manager (1.6.3-1) unstable; urgency=medium
+
+  * ***Fixed:*** Corrected repository path resolution so release and version logic consistently use the canonical packaging/* layout, preventing changelog and packaging files from being read or updated from incorrect locations.
+
+ -- Kevin Veen-Birkenbach <kevin@veen.world>  Sun, 14 Dec 2025 13:39:52 +0100
+
 package-manager (0.9.1-1) unstable; urgency=medium
 
   * * Refactored installer: new `venv-create.sh`, cleaner root/user setup flow, updated README with architecture map.

packaging/fedora/package-manager.spec

@@ -1,5 +1,5 @@
 Name:           package-manager
-Version:        0.9.1
+Version:        1.8.0
 Release:        1%{?dist}
 Summary:        Wrapper that runs Kevin's package-manager via Nix flake
 
@@ -74,6 +74,40 @@ echo ">>> package-manager removed. Nix itself was not removed."
 /usr/lib/package-manager/
 
 %changelog
+* 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.
+- **Repository Scaffolding**: The process for creating new repositories has been improved. You can now use templates to scaffold repositories with a preview and automatic mirror setup.
+
+*** Bug Fixes: ***
+- **Pip Installation**: Pip is now installed automatically on all supported systems. This includes `python-pip` for Arch and `python3-pip` for CentOS, Debian, Fedora, and Ubuntu, ensuring that pip is available for Python package installations.
+- **Pacman Keyring**: Fixed an issue on Arch Linux where package installation would fail due to missing keys. The pacman keyring is now properly initialized before installing packages.
+
+* Mon Dec 15 2025 Kevin Veen-Birkenbach <kevin@veen.world> - 1.7.2-1
+- * Git mirrors are now resolved consistently (origin → MIRRORS file → config → default).
+* The `origin` remote is always enforced to use the primary URL for both fetch and push.
+* Additional mirrors are added as extra push targets without duplication.
+* Local and remote mirror setup behaves more predictably and consistently.
+* Improved test coverage ensures stable origin and push URL handling.
+
+* Sun Dec 14 2025 Kevin Veen-Birkenbach <kevin@veen.world> - 1.7.1-1
+- Patched package-manager to kpmx to publish on pypi
+
+* Sun Dec 14 2025 Kevin Veen-Birkenbach <kevin@veen.world> - 1.7.0-1
+- * New *pkgmgr publish* command to publish repository artifacts to PyPI based on the *MIRRORS* file.
+* Automatically selects the current repository when no explicit selection is given.
+* Publishes only when a semantic version tag is present on *HEAD*; otherwise skips with a clear info message.
+* Supports non-interactive mode for CI environments via *--non-interactive*.
+
+* Sun Dec 14 2025 Kevin Veen-Birkenbach <kevin@veen.world> - 1.6.4-1
+- * Improved reliability of Nix installs and updates, including automatic resolution of profile conflicts and better handling of GitHub 403 rate limits.
+* More stable launcher behavior in packaged and virtual-env setups.
+* Enhanced mirror and remote handling: repository owner/name are derived from URLs, with smoother provisioning and clearer credential handling.
+* More reliable releases and artifacts due to safer CI behavior when no version tag is present.
+
+* Sun Dec 14 2025 Kevin Veen-Birkenbach <kevin@veen.world> - 1.6.3-1
+- ***Fixed:*** Corrected repository path resolution so release and version logic consistently use the canonical packaging/* layout, preventing changelog and packaging files from being read or updated from incorrect locations.
+
 * Wed Dec 10 2025 Kevin Veen-Birkenbach <kevin@veen.world> - 0.9.1-1
 - * Refactored installer: new `venv-create.sh`, cleaner root/user setup flow, updated README with architecture map.
 * Split virgin tests into root/user workflows; stabilized Nix installer across distros; improved test scripts with dynamic distro selection and isolated Nix stores.

pyproject.toml

@@ -6,8 +6,8 @@ requires = [
 build-backend = "setuptools.build_meta"
 
 [project]
-name = "package-manager"
-version = "1.6.1"
+name = "kpmx"
+version = "1.8.0"
 description = "Kevin's package-manager tool (pkgmgr)"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -19,7 +19,9 @@ authors = [
 
 # Base runtime dependencies
 dependencies = [
-  "PyYAML>=6.0"
+  "PyYAML>=6.0",
+  "tomli; python_version < \"3.11\"",
+  "jinja2>=3.1"
 ]
 
 [project.urls]

scripts/installation/arch/dependencies.sh

@@ -6,6 +6,13 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 echo "[arch/dependencies] Installing Arch build dependencies..."
 
 pacman -Syu --noconfirm
+
+if ! pacman-key --list-sigs &>/dev/null; then
+    echo "[arch/dependencies] Initializing pacman keyring..."
+    pacman-key --init
+    pacman-key --populate archlinux
+fi
+
 pacman -S --noconfirm --needed \
   base-devel \
   git \
@@ -13,6 +20,7 @@ pacman -S --noconfirm --needed \
   curl \
   ca-certificates \
   python \
+  python-pip \
   xz
 
 pacman -Scc --noconfirm

scripts/installation/centos/dependencies.sh

@@ -14,6 +14,7 @@ dnf -y install \
   curl-minimal \
   ca-certificates \
   python3 \
+  python3-pip \
   sudo \
   xz
 

scripts/installation/debian/dependencies.sh

@@ -15,6 +15,7 @@ DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
   ca-certificates \
   python3 \
   python3-venv \
+  python3-pip \
   xz-utils
 
 rm -rf /var/lib/apt/lists/*

scripts/installation/fedora/dependencies.sh

@@ -14,6 +14,7 @@ dnf -y install \
   curl \
   ca-certificates \
   python3 \
+  python3-pip \
   xz
 
 dnf clean all

scripts/installation/ubuntu/dependencies.sh

@@ -17,6 +17,7 @@ DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
   make \
   python3 \
   python3-venv \
+  python3-pip \
   ca-certificates \
   xz-utils
 

scripts/launcher.sh

@@ -2,6 +2,16 @@
 set -euo pipefail
 
 FLAKE_DIR="/usr/lib/package-manager"
+NIX_LIB_DIR="${FLAKE_DIR}/nix/lib"
+RETRY_LIB="${NIX_LIB_DIR}/retry_403.sh"
+
+# ---------------------------------------------------------------------------
+# Hard requirement: retry helper must exist (fail if missing)
+# ---------------------------------------------------------------------------
+if [[ ! -f "${RETRY_LIB}" ]]; then
+  echo "[launcher] ERROR: Required retry helper not found: ${RETRY_LIB}" >&2
+  exit 1
+fi
 
 # ---------------------------------------------------------------------------
 # Try to ensure that "nix" is on PATH (common locations + container user)
@@ -32,9 +42,13 @@ if ! command -v nix >/dev/null 2>&1; then
 fi
 
 # ---------------------------------------------------------------------------
-# Primary path: use Nix flake if available
+# Primary path: use Nix flake if available (with GitHub 403 retry)
 # ---------------------------------------------------------------------------
-if command -v nix >/dev/null 2>&1; then
+if declare -F run_with_github_403_retry >/dev/null; then
+  # shellcheck source=./scripts/nix/lib/retry_403.sh
+  source "${RETRY_LIB}"
+  exec run_with_github_403_retry nix run "${FLAKE_DIR}#pkgmgr" -- "$@"
+else
   exec nix run "${FLAKE_DIR}#pkgmgr" -- "$@"
 fi
 

scripts/test/test-env-virtual.sh

@@ -1,32 +1,49 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-IMAGE="pkgmgr-$PKGMGR_DISTRO"
+IMAGE="pkgmgr-${PKGMGR_DISTRO}"
 
 echo
 echo "------------------------------------------------------------"
-echo ">>> Testing VENV: $IMAGE"
+echo ">>> Testing VENV: ${IMAGE}"
 echo "------------------------------------------------------------"
+
 echo "[test-env-virtual] Inspect image metadata:"
-docker image inspect "$IMAGE" | sed -n '1,40p'
-
-echo "[test-env-virtual] Running: docker run --rm --entrypoint pkgmgr $IMAGE --help"
+docker image inspect "${IMAGE}" | sed -n '1,40p'
 echo
 
-# Run the command and capture the output
+# ------------------------------------------------------------
+# Run VENV-based pkgmgr test inside container
+# ------------------------------------------------------------
 if OUTPUT=$(docker run --rm \
-        -e REINSTALL_PKGMGR=1 \
-        -v "pkgmgr_nix_store_${PKGMGR_DISTRO}:/nix" \
-        -v "$(pwd):/src" \
-        -v "pkgmgr_nix_cache_${PKGMGR_DISTRO}:/root/.cache/nix" \
-        "$IMAGE" 2>&1); then
+    -e REINSTALL_PKGMGR=1 \
+    -v "$(pwd):/src" \
+    -w /src \
+    "${IMAGE}" \
+    bash -lc '
+        set -euo pipefail
+
+        echo "[test-env-virtual] Installing pkgmgr (distro package)..."
+        make install
+
+        echo "[test-env-virtual] Setting up Python venv..."
+        make setup-venv
+
+        echo "[test-env-virtual] Activating venv..."
+        . "$HOME/.venvs/pkgmgr/bin/activate"
+
+        echo "[test-env-virtual] Using pkgmgr from:"
+        command -v pkgmgr
+        pkgmgr --help
+    ' 2>&1); then
+
     echo "$OUTPUT"
     echo
-    echo "[test-env-virtual] SUCCESS: $IMAGE responded to 'pkgmgr --help'"
+    echo "[test-env-virtual] SUCCESS: venv-based pkgmgr works in ${IMAGE}"
 
 else
     echo "$OUTPUT"
     echo
-    echo "[test-env-virtual] ERROR: $IMAGE failed to run 'pkgmgr --help'"
+    echo "[test-env-virtual] ERROR: venv-based pkgmgr failed in ${IMAGE}"
     exit 1
-fi
+fi

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/install/__init__.py

@@ -16,7 +16,7 @@ Responsibilities:
 from __future__ import annotations
 
 import os
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, Tuple
 
 from pkgmgr.core.repository.identifier import get_repo_identifier
 from pkgmgr.core.repository.dir import get_repo_dir
@@ -93,6 +93,7 @@ def _verify_repo(
     repo_dir: str,
     no_verification: bool,
     identifier: str,
+    silent: bool,
 ) -> bool:
     """
     Verify a repository using the configured verification data.
@@ -111,10 +112,15 @@ def _verify_repo(
         print(f"Warning: Verification failed for {identifier}:")
         for err in errors:
             print(f"  - {err}")
-        choice = input("Continue anyway? [y/N]: ").strip().lower()
-        if choice != "y":
-            print(f"Skipping installation for {identifier}.")
-            return False
+
+        if silent:
+            # Non-interactive mode: continue with a warning.
+            print(f"[Warning] Continuing despite verification failure for {identifier} (--silent).")
+        else:
+            choice = input("Continue anyway? [y/N]: ").strip().lower()
+            if choice != "y":
+                print(f"Skipping installation for {identifier}.")
+                return False
 
     return True
 
@@ -163,6 +169,8 @@ def install_repos(
     clone_mode: str,
     update_dependencies: bool,
     force_update: bool = False,
+    silent: bool = False,
+    emit_summary: bool = True,
 ) -> None:
     """
     Install one or more repositories according to the configured installers
@@ -170,45 +178,72 @@ def install_repos(
 
     If force_update=True, installers of the currently active layer are allowed
     to run again (upgrade/refresh), even if that layer is already loaded.
+
+    If silent=True, repository failures are downgraded to warnings and the
+    overall command never exits non-zero because of per-repository failures.
     """
     pipeline = InstallationPipeline(INSTALLERS)
+    failures: List[Tuple[str, str]] = []
 
     for repo in selected_repos:
         identifier = get_repo_identifier(repo, all_repos)
 
-        repo_dir = _ensure_repo_dir(
-            repo=repo,
-            repositories_base_dir=repositories_base_dir,
-            all_repos=all_repos,
-            preview=preview,
-            no_verification=no_verification,
-            clone_mode=clone_mode,
-            identifier=identifier,
-        )
-        if not repo_dir:
+        try:
+            repo_dir = _ensure_repo_dir(
+                repo=repo,
+                repositories_base_dir=repositories_base_dir,
+                all_repos=all_repos,
+                preview=preview,
+                no_verification=no_verification,
+                clone_mode=clone_mode,
+                identifier=identifier,
+            )
+            if not repo_dir:
+                failures.append((identifier, "clone/ensure repo directory failed"))
+                continue
+
+            if not _verify_repo(
+                repo=repo,
+                repo_dir=repo_dir,
+                no_verification=no_verification,
+                identifier=identifier,
+                silent=silent,
+            ):
+                continue
+
+            ctx = _create_context(
+                repo=repo,
+                identifier=identifier,
+                repo_dir=repo_dir,
+                repositories_base_dir=repositories_base_dir,
+                bin_dir=bin_dir,
+                all_repos=all_repos,
+                no_verification=no_verification,
+                preview=preview,
+                quiet=quiet,
+                clone_mode=clone_mode,
+                update_dependencies=update_dependencies,
+                force_update=force_update,
+            )
+
+            pipeline.run(ctx)
+
+        except SystemExit as exc:
+            code = exc.code if isinstance(exc.code, int) else str(exc.code)
+            failures.append((identifier, f"installer failed (exit={code})"))
+            if not quiet:
+                print(f"[Warning] install: repository {identifier} failed (exit={code}). Continuing...")
+            continue
+        except Exception as exc:
+            failures.append((identifier, f"unexpected error: {exc}"))
+            if not quiet:
+                print(f"[Warning] install: repository {identifier} hit an unexpected error: {exc}. Continuing...")
             continue
 
-        if not _verify_repo(
-            repo=repo,
-            repo_dir=repo_dir,
-            no_verification=no_verification,
-            identifier=identifier,
-        ):
-            continue
+    if failures and emit_summary and not quiet:
+        print("\n[pkgmgr] Installation finished with warnings:")
+        for ident, msg in failures:
+            print(f"  - {ident}: {msg}")
 
-        ctx = _create_context(
-            repo=repo,
-            identifier=identifier,
-            repo_dir=repo_dir,
-            repositories_base_dir=repositories_base_dir,
-            bin_dir=bin_dir,
-            all_repos=all_repos,
-            no_verification=no_verification,
-            preview=preview,
-            quiet=quiet,
-            clone_mode=clone_mode,
-            update_dependencies=update_dependencies,
-            force_update=force_update,
-        )
-
-        pipeline.run(ctx)
+    if failures and not silent:
+        raise SystemExit(1)

src/pkgmgr/actions/install/installers/nix/conflicts.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, List
+
+from .profile import NixProfileInspector
+from .retry import GitHubRateLimitRetry
+from .runner import CommandRunner
+from .textparse import NixConflictTextParser
+
+if TYPE_CHECKING:
+    from pkgmgr.actions.install.context import RepoContext
+
+
+class NixConflictResolver:
+    """
+    Resolves nix profile file conflicts by:
+      1. Parsing conflicting store paths from stderr
+      2. Mapping them to profile remove tokens via `nix profile list --json`
+      3. Removing those tokens deterministically
+      4. Retrying install
+    """
+
+    def __init__(
+        self,
+        runner: CommandRunner,
+        retry: GitHubRateLimitRetry,
+        profile: NixProfileInspector,
+    ) -> None:
+        self._runner = runner
+        self._retry = retry
+        self._profile = profile
+        self._parser = NixConflictTextParser()
+
+    def resolve(
+        self,
+        ctx: "RepoContext",
+        install_cmd: str,
+        stdout: str,
+        stderr: str,
+        *,
+        output: str,
+        max_rounds: int = 10,
+    ) -> bool:
+        quiet = bool(getattr(ctx, "quiet", False))
+        combined = f"{stdout}\n{stderr}"
+
+        for _ in range(max_rounds):
+            # 1) Extract conflicting store prefixes from nix error output
+            store_prefixes = self._parser.existing_store_prefixes(combined)
+
+            # 2) Resolve them to concrete remove tokens
+            tokens: List[str] = self._profile.find_remove_tokens_for_store_prefixes(
+                ctx,
+                self._runner,
+                store_prefixes,
+            )
+
+            # 3) Fallback: output-name based lookup (also covers nix suggesting: `nix profile remove pkgmgr`)
+            if not tokens:
+                tokens = self._profile.find_remove_tokens_for_output(ctx, self._runner, output)
+
+            if tokens:
+                if not quiet:
+                    print(
+                        "[nix] conflict detected; removing existing profile entries: "
+                        + ", ".join(tokens)
+                    )
+
+                for t in tokens:
+                    # tokens may contain things like "pkgmgr" or "pkgmgr-1" or quoted tokens (we keep raw)
+                    self._runner.run(ctx, f"nix profile remove {t}", allow_failure=True)
+
+                res = self._retry.run_with_retry(ctx, self._runner, install_cmd)
+                if res.returncode == 0:
+                    return True
+
+                combined = f"{res.stdout}\n{res.stderr}"
+                continue
+
+            # 4) Last-resort fallback: use textual remove tokens from stderr (“nix profile remove X”)
+            tokens = self._parser.remove_tokens(combined)
+            if tokens:
+                if not quiet:
+                    print("[nix] fallback remove tokens: " + ", ".join(tokens))
+
+                for t in tokens:
+                    self._runner.run(ctx, f"nix profile remove {t}", allow_failure=True)
+
+                res = self._retry.run_with_retry(ctx, self._runner, install_cmd)
+                if res.returncode == 0:
+                    return True
+
+                combined = f"{res.stdout}\n{res.stderr}"
+                continue
+
+            if not quiet:
+                print("[nix] conflict detected but could not resolve profile entries to remove.")
+            return False
+
+        return False

src/pkgmgr/actions/install/installers/nix/installer.py

@@ -1,12 +1,12 @@
-# src/pkgmgr/actions/install/installers/nix/installer.py
 from __future__ import annotations
 
 import os
 import shutil
-from typing import List, Tuple, TYPE_CHECKING
+from typing import TYPE_CHECKING, List, Tuple
 
 from pkgmgr.actions.install.installers.base import BaseInstaller
 
+from .conflicts import NixConflictResolver
 from .profile import NixProfileInspector
 from .retry import GitHubRateLimitRetry, RetryPolicy
 from .runner import CommandRunner
@@ -14,6 +14,7 @@ from .runner import CommandRunner
 if TYPE_CHECKING:
     from pkgmgr.actions.install.context import RepoContext
 
+
 class NixFlakeInstaller(BaseInstaller):
     layer = "nix"
     FLAKE_FILE = "flake.nix"
@@ -22,15 +23,18 @@ class NixFlakeInstaller(BaseInstaller):
         self._runner = CommandRunner()
         self._retry = GitHubRateLimitRetry(policy=policy)
         self._profile = NixProfileInspector()
+        self._conflicts = NixConflictResolver(self._runner, self._retry, self._profile)
 
-    # ------------------------------------------------------------------ #
-    # Compatibility: supports()
-    # ------------------------------------------------------------------ #
+        # Newer nix rejects numeric indices; we learn this at runtime and cache the decision.
+        self._indices_supported: bool | None = None
 
     def supports(self, ctx: "RepoContext") -> bool:
         if os.environ.get("PKGMGR_DISABLE_NIX_FLAKE_INSTALLER") == "1":
             if not ctx.quiet:
-                print("[INFO] PKGMGR_DISABLE_NIX_FLAKE_INSTALLER=1 – skipping NixFlakeInstaller.")
+                print(
+                    "[INFO] PKGMGR_DISABLE_NIX_FLAKE_INSTALLER=1 – "
+                    "skipping NixFlakeInstaller."
+                )
             return False
 
         if shutil.which("nix") is None:
@@ -38,20 +42,12 @@ class NixFlakeInstaller(BaseInstaller):
 
         return os.path.exists(os.path.join(ctx.repo_dir, self.FLAKE_FILE))
 
-    # ------------------------------------------------------------------ #
-    # Compatibility: output selection
-    # ------------------------------------------------------------------ #
-
     def _profile_outputs(self, ctx: "RepoContext") -> List[Tuple[str, bool]]:
         # (output_name, allow_failure)
         if ctx.identifier in {"pkgmgr", "package-manager"}:
             return [("pkgmgr", False), ("default", True)]
         return [("default", False)]
 
-    # ------------------------------------------------------------------ #
-    # Compatibility: run()
-    # ------------------------------------------------------------------ #
-
     def run(self, ctx: "RepoContext") -> None:
         if not self.supports(ctx):
             return
@@ -59,11 +55,12 @@ class NixFlakeInstaller(BaseInstaller):
         outputs = self._profile_outputs(ctx)
 
         if not ctx.quiet:
-            print(
+            msg = (
                 "[nix] flake detected in "
                 f"{ctx.identifier}, ensuring outputs: "
                 + ", ".join(name for name, _ in outputs)
             )
+            print(msg)
 
         for output, allow_failure in outputs:
             if ctx.force_update:
@@ -71,13 +68,13 @@ class NixFlakeInstaller(BaseInstaller):
             else:
                 self._install_only(ctx, output, allow_failure)
 
-    # ------------------------------------------------------------------ #
-    # Core logic (unchanged semantics)
-    # ------------------------------------------------------------------ #
-
     def _installable(self, ctx: "RepoContext", output: str) -> str:
         return f"{ctx.repo_dir}#{output}"
 
+    # ---------------------------------------------------------------------
+    # Core install path
+    # ---------------------------------------------------------------------
+
     def _install_only(self, ctx: "RepoContext", output: str, allow_failure: bool) -> None:
         install_cmd = f"nix profile install {self._installable(ctx, output)}"
 
@@ -85,35 +82,56 @@ class NixFlakeInstaller(BaseInstaller):
             print(f"[nix] install: {install_cmd}")
 
         res = self._retry.run_with_retry(ctx, self._runner, install_cmd)
-
         if res.returncode == 0:
             if not ctx.quiet:
                 print(f"[nix] output '{output}' successfully installed.")
             return
 
+        # Conflict resolver first (handles the common “existing package already provides file” case)
+        if self._conflicts.resolve(
+            ctx,
+            install_cmd,
+            res.stdout,
+            res.stderr,
+            output=output,
+        ):
+            if not ctx.quiet:
+                print(f"[nix] output '{output}' successfully installed after conflict cleanup.")
+            return
+
         if not ctx.quiet:
             print(
                 f"[nix] install failed for '{output}' (exit {res.returncode}), "
-                "trying index-based upgrade/remove+install..."
+                "trying upgrade/remove+install..."
             )
 
-        indices = self._profile.find_installed_indices_for_output(ctx, self._runner, output)
+        # If indices are supported, try legacy index-upgrade path.
+        if self._indices_supported is not False:
+            indices = self._profile.find_installed_indices_for_output(ctx, self._runner, output)
 
-        upgraded = False
-        for idx in indices:
-            if self._upgrade_index(ctx, idx):
-                upgraded = True
-                if not ctx.quiet:
-                    print(f"[nix] output '{output}' successfully upgraded (index {idx}).")
+            upgraded = False
+            for idx in indices:
+                if self._upgrade_index(ctx, idx):
+                    upgraded = True
+                    if not ctx.quiet:
+                        print(f"[nix] output '{output}' successfully upgraded (index {idx}).")
 
-        if upgraded:
-            return
+            if upgraded:
+                return
 
-        if indices and not ctx.quiet:
-            print(f"[nix] upgrade failed; removing indices {indices} and reinstalling '{output}'.")
+            if indices and not ctx.quiet:
+                print(f"[nix] upgrade failed; removing indices {indices} and reinstalling '{output}'.")
 
-        for idx in indices:
-            self._remove_index(ctx, idx)
+            for idx in indices:
+                self._remove_index(ctx, idx)
+
+            # If we learned indices are unsupported, immediately fall back below
+            if self._indices_supported is False:
+                self._remove_tokens_for_output(ctx, output)
+
+        else:
+            # indices explicitly unsupported
+            self._remove_tokens_for_output(ctx, output)
 
         final = self._runner.run(ctx, install_cmd, allow_failure=True)
         if final.returncode == 0:
@@ -122,17 +140,24 @@ class NixFlakeInstaller(BaseInstaller):
             return
 
         print(f"[ERROR] Failed to install Nix flake output '{output}' (exit {final.returncode})")
-
         if not allow_failure:
             raise SystemExit(final.returncode)
 
         print(f"[WARNING] Continuing despite failure of optional output '{output}'.")
 
-    # ------------------------------------------------------------------ #
-    # force_update path (unchanged semantics)
-    # ------------------------------------------------------------------ #
+    # ---------------------------------------------------------------------
+    # force_update path
+    # ---------------------------------------------------------------------
 
     def _force_upgrade_output(self, ctx: "RepoContext", output: str, allow_failure: bool) -> None:
+        # Prefer token path if indices unsupported (new nix)
+        if self._indices_supported is False:
+            self._remove_tokens_for_output(ctx, output)
+            self._install_only(ctx, output, allow_failure)
+            if not ctx.quiet:
+                print(f"[nix] output '{output}' successfully upgraded.")
+            return
+
         indices = self._profile.find_installed_indices_for_output(ctx, self._runner, output)
 
         upgraded_any = False
@@ -143,7 +168,8 @@ class NixFlakeInstaller(BaseInstaller):
                     print(f"[nix] output '{output}' successfully upgraded (index {idx}).")
 
         if upgraded_any:
-            print(f"[nix] output '{output}' successfully upgraded.")
+            if not ctx.quiet:
+                print(f"[nix] output '{output}' successfully upgraded.")
             return
 
         if indices and not ctx.quiet:
@@ -152,17 +178,52 @@ class NixFlakeInstaller(BaseInstaller):
         for idx in indices:
             self._remove_index(ctx, idx)
 
+        # If we learned indices are unsupported, also remove by token to actually clear conflicts
+        if self._indices_supported is False:
+            self._remove_tokens_for_output(ctx, output)
+
         self._install_only(ctx, output, allow_failure)
 
-        print(f"[nix] output '{output}' successfully upgraded.")
+        if not ctx.quiet:
+            print(f"[nix] output '{output}' successfully upgraded.")
 
-    # ------------------------------------------------------------------ #
+    # ---------------------------------------------------------------------
     # Helpers
-    # ------------------------------------------------------------------ #
+    # ---------------------------------------------------------------------
+
+    def _stderr_says_indices_unsupported(self, stderr: str) -> bool:
+        s = (stderr or "").lower()
+        return "no longer supports indices" in s or "does not support indices" in s
 
     def _upgrade_index(self, ctx: "RepoContext", idx: int) -> bool:
-        res = self._runner.run(ctx, f"nix profile upgrade --refresh {idx}", allow_failure=True)
+        cmd = f"nix profile upgrade --refresh {idx}"
+        res = self._runner.run(ctx, cmd, allow_failure=True)
+
+        if self._stderr_says_indices_unsupported(getattr(res, "stderr", "")):
+            self._indices_supported = False
+            return False
+
+        if self._indices_supported is None:
+            self._indices_supported = True
+
         return res.returncode == 0
 
     def _remove_index(self, ctx: "RepoContext", idx: int) -> None:
-        self._runner.run(ctx, f"nix profile remove {idx}", allow_failure=True)
+        res = self._runner.run(ctx, f"nix profile remove {idx}", allow_failure=True)
+
+        if self._stderr_says_indices_unsupported(getattr(res, "stderr", "")):
+            self._indices_supported = False
+
+        if self._indices_supported is None:
+            self._indices_supported = True
+
+    def _remove_tokens_for_output(self, ctx: "RepoContext", output: str) -> None:
+        tokens = self._profile.find_remove_tokens_for_output(ctx, self._runner, output)
+        if not tokens:
+            return
+
+        if not ctx.quiet:
+            print(f"[nix] indices unsupported; removing by token(s): {', '.join(tokens)}")
+
+        for t in tokens:
+            self._runner.run(ctx, f"nix profile remove {t}", allow_failure=True)

src/pkgmgr/actions/install/installers/nix/profile.py

@@ -1,71 +0,0 @@
-from __future__ import annotations
-
-import json
-from typing import Any, List, TYPE_CHECKING
-
-
-if TYPE_CHECKING:
-    from pkgmgr.actions.install.context import RepoContext
-    from .runner import CommandRunner
- 
-class NixProfileInspector:
-    """
-    Reads and interprets `nix profile list --json` and provides helpers for
-    finding indices matching a given output name.
-    """
-
-    def find_installed_indices_for_output(self, ctx: "RepoContext", runner: "CommandRunner", output: str) -> List[int]:
-        res = runner.run(ctx, "nix profile list --json", allow_failure=True)
-        if res.returncode != 0:
-            return []
-
-        try:
-            data = json.loads(res.stdout or "{}")
-        except json.JSONDecodeError:
-            return []
-
-        indices: List[int] = []
-
-        elements = data.get("elements")
-        if isinstance(elements, dict):
-            for idx_str, elem in elements.items():
-                try:
-                    idx = int(idx_str)
-                except (TypeError, ValueError):
-                    continue
-                if self._element_matches_output(elem, output):
-                    indices.append(idx)
-            return sorted(indices)
-
-        if isinstance(elements, list):
-            for elem in elements:
-                idx = elem.get("index") if isinstance(elem, dict) else None
-                if isinstance(idx, int) and self._element_matches_output(elem, output):
-                    indices.append(idx)
-            return sorted(indices)
-
-        return []
-
-    @staticmethod
-    def element_matches_output(elem: Any, output: str) -> bool:
-        return NixProfileInspector._element_matches_output(elem, output)
-
-    @staticmethod
-    def _element_matches_output(elem: Any, output: str) -> bool:
-        out = (output or "").strip()
-        if not out or not isinstance(elem, dict):
-            return False
-
-        candidates: List[str] = []
-        for k in ("attrPath", "originalUrl", "url", "storePath", "name"):
-            v = elem.get(k)
-            if isinstance(v, str) and v:
-                candidates.append(v)
-
-        for c in candidates:
-            if c == out:
-                return True
-            if f"#{out}" in c:
-                return True
-
-        return False

src/pkgmgr/actions/install/installers/nix/profile/__init__.py

@@ -0,0 +1,4 @@
+from .inspector import NixProfileInspector
+from .models import NixProfileEntry
+
+__all__ = ["NixProfileInspector", "NixProfileEntry"]

src/pkgmgr/actions/install/installers/nix/profile/inspector.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+from typing import Any, List, TYPE_CHECKING
+
+from .matcher import (
+    entry_matches_output,
+    entry_matches_store_path,
+    stable_unique_ints,
+)
+from .normalizer import normalize_elements
+from .parser import parse_profile_list_json
+from .result import extract_stdout_text
+
+if TYPE_CHECKING:
+    # Keep these as TYPE_CHECKING-only to avoid runtime import cycles.
+    from pkgmgr.actions.install.context import RepoContext
+    from pkgmgr.core.command.runner import CommandRunner
+
+
+class NixProfileInspector:
+    """
+    Reads and inspects the user's Nix profile list (JSON).
+
+    Public API:
+      - list_json()
+      - find_installed_indices_for_output()   (legacy; may not work on newer nix)
+      - find_indices_by_store_path()          (legacy; may not work on newer nix)
+      - find_remove_tokens_for_output()
+      - find_remove_tokens_for_store_prefixes()
+    """
+
+    def list_json(self, ctx: "RepoContext", runner: "CommandRunner") -> dict[str, Any]:
+        res = runner.run(ctx, "nix profile list --json", allow_failure=False)
+        raw = extract_stdout_text(res)
+        return parse_profile_list_json(raw)
+
+    # ---------------------------------------------------------------------
+    # Legacy index helpers (still useful on older nix; newer nix may reject indices)
+    # ---------------------------------------------------------------------
+
+    def find_installed_indices_for_output(
+        self,
+        ctx: "RepoContext",
+        runner: "CommandRunner",
+        output: str,
+    ) -> List[int]:
+        data = self.list_json(ctx, runner)
+        entries = normalize_elements(data)
+
+        hits: List[int] = []
+        for e in entries:
+            if e.index is None:
+                continue
+            if entry_matches_output(e, output):
+                hits.append(e.index)
+
+        return stable_unique_ints(hits)
+
+    def find_indices_by_store_path(
+        self,
+        ctx: "RepoContext",
+        runner: "CommandRunner",
+        store_path: str,
+    ) -> List[int]:
+        needle = (store_path or "").strip()
+        if not needle:
+            return []
+
+        data = self.list_json(ctx, runner)
+        entries = normalize_elements(data)
+
+        hits: List[int] = []
+        for e in entries:
+            if e.index is None:
+                continue
+            if entry_matches_store_path(e, needle):
+                hits.append(e.index)
+
+        return stable_unique_ints(hits)
+
+    # ---------------------------------------------------------------------
+    # New token-based helpers (works with newer nix where indices are rejected)
+    # ---------------------------------------------------------------------
+
+    def find_remove_tokens_for_output(
+        self,
+        ctx: "RepoContext",
+        runner: "CommandRunner",
+        output: str,
+    ) -> List[str]:
+        """
+        Returns profile remove tokens to remove entries matching a given output.
+
+        We always include the raw output token first because nix itself suggests:
+          nix profile remove pkgmgr
+        """
+        out = (output or "").strip()
+        if not out:
+            return []
+
+        data = self.list_json(ctx, runner)
+        entries = normalize_elements(data)
+
+        tokens: List[str] = [out]  # critical: matches nix's own suggestion for conflicts
+
+        for e in entries:
+            if entry_matches_output(e, out):
+                # Prefer removing by key/name (non-index) when possible.
+                # New nix rejects numeric indices; these tokens are safer.
+                k = (e.key or "").strip()
+                n = (e.name or "").strip()
+
+                if k and not k.isdigit():
+                    tokens.append(k)
+                elif n and not n.isdigit():
+                    tokens.append(n)
+
+        # stable unique preserving order
+        seen: set[str] = set()
+        uniq: List[str] = []
+        for t in tokens:
+            if t and t not in seen:
+                uniq.append(t)
+                seen.add(t)
+        return uniq
+
+    def find_remove_tokens_for_store_prefixes(
+        self,
+        ctx: "RepoContext",
+        runner: "CommandRunner",
+        prefixes: List[str],
+    ) -> List[str]:
+        """
+        Returns remove tokens for entries whose store path matches any prefix.
+        """
+        prefixes = [(p or "").strip() for p in (prefixes or []) if p]
+        prefixes = [p for p in prefixes if p]
+        if not prefixes:
+            return []
+
+        data = self.list_json(ctx, runner)
+        entries = normalize_elements(data)
+
+        tokens: List[str] = []
+        for e in entries:
+            if not e.store_paths:
+                continue
+            if any(sp == p for sp in e.store_paths for p in prefixes):
+                k = (e.key or "").strip()
+                n = (e.name or "").strip()
+                if k and not k.isdigit():
+                    tokens.append(k)
+                elif n and not n.isdigit():
+                    tokens.append(n)
+
+        seen: set[str] = set()
+        uniq: List[str] = []
+        for t in tokens:
+            if t and t not in seen:
+                uniq.append(t)
+                seen.add(t)
+        return uniq

src/pkgmgr/actions/install/installers/nix/profile/matcher.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from typing import List
+
+from .models import NixProfileEntry
+
+
+def entry_matches_output(entry: NixProfileEntry, output: str) -> bool:
+    """
+    Heuristic matcher: output is typically a flake output name (e.g. "pkgmgr"),
+    and we match against name/attrPath patterns.
+    """
+    out = (output or "").strip()
+    if not out:
+        return False
+
+    candidates = [entry.name, entry.attr_path]
+
+    for c in candidates:
+        c = (c or "").strip()
+        if not c:
+            continue
+
+        # Direct match
+        if c == out:
+            return True
+
+        # AttrPath contains "#<output>"
+        if f"#{out}" in c:
+            return True
+
+        # AttrPath ends with ".<output>"
+        if c.endswith(f".{out}"):
+            return True
+
+        # Name pattern "<output>-<n>" (common, e.g. pkgmgr-1)
+        if c.startswith(f"{out}-"):
+            return True
+
+        # Historical special case: repo is "package-manager" but output is "pkgmgr"
+        if out == "pkgmgr" and c.startswith("package-manager-"):
+            return True
+
+    return False
+
+
+def entry_matches_store_path(entry: NixProfileEntry, store_path: str) -> bool:
+    needle = (store_path or "").strip()
+    if not needle:
+        return False
+    return any((p or "") == needle for p in entry.store_paths)
+
+
+def stable_unique_ints(values: List[int]) -> List[int]:
+    seen: set[int] = set()
+    uniq: List[int] = []
+    for v in values:
+        if v in seen:
+            continue
+        uniq.append(v)
+        seen.add(v)
+    return uniq

src/pkgmgr/actions/install/installers/nix/profile/models.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Optional
+
+
+@dataclass(frozen=True)
+class NixProfileEntry:
+    """
+    Minimal normalized representation of one nix profile element entry.
+    """
+
+    key: str
+    index: Optional[int]
+    name: str
+    attr_path: str
+    store_paths: List[str]

src/pkgmgr/actions/install/installers/nix/profile/normalizer.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+import re
+from typing import Any, Dict, Iterable, List, Optional
+
+from .models import NixProfileEntry
+
+
+def coerce_index(key: str, entry: Dict[str, Any]) -> Optional[int]:
+    """
+    Nix JSON schema varies:
+      - elements keys might be "0", "1", ...
+      - or might be names like "pkgmgr-1"
+    Some versions include an explicit index field.
+    We try safe options in order.
+    """
+    k = (key or "").strip()
+
+    # 1) Classic: numeric keys
+    if k.isdigit():
+        try:
+            return int(k)
+        except Exception:
+            return None
+
+    # 2) Explicit index fields (schema-dependent)
+    for field in ("index", "id", "position"):
+        v = entry.get(field)
+        if isinstance(v, int):
+            return v
+        if isinstance(v, str) and v.strip().isdigit():
+            try:
+                return int(v.strip())
+            except Exception:
+                pass
+
+    # 3) Last resort: extract trailing number from key if it looks like "<name>-<n>"
+    m = re.match(r"^.+-(\d+)$", k)
+    if m:
+        try:
+            return int(m.group(1))
+        except Exception:
+            return None
+
+    return None
+
+
+def iter_store_paths(entry: Dict[str, Any]) -> Iterable[str]:
+    """
+    Yield all possible store paths from a nix profile JSON entry.
+
+    Nix has had schema shifts. We support common variants:
+      - "storePaths": ["/nix/store/..", ...]
+      - "storePaths": "/nix/store/.."  (rare)
+      - "storePath": "/nix/store/.."   (some variants)
+      - nested "outputs" dict(s) with store paths (best-effort)
+    """
+    if not isinstance(entry, dict):
+        return
+
+    sp = entry.get("storePaths")
+    if isinstance(sp, list):
+        for p in sp:
+            if isinstance(p, str):
+                yield p
+    elif isinstance(sp, str):
+        yield sp
+
+    sp2 = entry.get("storePath")
+    if isinstance(sp2, str):
+        yield sp2
+
+    outs = entry.get("outputs")
+    if isinstance(outs, dict):
+        for _, ov in outs.items():
+            if isinstance(ov, dict):
+                p = ov.get("storePath")
+                if isinstance(p, str):
+                    yield p
+
+
+def normalize_store_path(store_path: str) -> str:
+    """
+    Normalize store path for matching.
+    Currently just strips whitespace; hook for future normalization if needed.
+    """
+    return (store_path or "").strip()
+
+
+def normalize_elements(data: Dict[str, Any]) -> List[NixProfileEntry]:
+    """
+    Converts nix profile list JSON into a list of normalized entries.
+
+    JSON formats observed:
+      - {"elements": {"0": {...}, "1": {...}}}
+      - {"elements": {"pkgmgr-1": {...}, "pkgmgr-2": {...}}}
+    """
+    elements = data.get("elements")
+    if not isinstance(elements, dict):
+        return []
+
+    normalized: List[NixProfileEntry] = []
+
+    for k, entry in elements.items():
+        if not isinstance(entry, dict):
+            continue
+
+        idx = coerce_index(str(k), entry)
+        name = str(entry.get("name", "") or "")
+        attr = str(entry.get("attrPath", "") or "")
+
+        store_paths: List[str] = []
+        for p in iter_store_paths(entry):
+            sp = normalize_store_path(p)
+            if sp:
+                store_paths.append(sp)
+
+        normalized.append(
+            NixProfileEntry(
+                key=str(k),
+                index=idx,
+                name=name,
+                attr_path=attr,
+                store_paths=store_paths,
+            )
+        )
+
+    return normalized

src/pkgmgr/actions/install/installers/nix/profile/parser.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+import json
+from typing import Any, Dict
+
+
+def parse_profile_list_json(raw: str) -> Dict[str, Any]:
+    """
+    Parse JSON output from `nix profile list --json`.
+
+    Raises SystemExit with a helpful excerpt on parse failure.
+    """
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError as e:
+        excerpt = (raw or "")[:5000]
+        raise SystemExit(
+            f"[nix] Failed to parse `nix profile list --json`: {e}\n{excerpt}"
+        ) from e

src/pkgmgr/actions/install/installers/nix/profile/result.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def extract_stdout_text(result: Any) -> str:
+    """
+    Normalize different runner return types to a stdout string.
+
+    Supported patterns:
+      - result is str -> returned as-is
+      - result is bytes/bytearray -> decoded UTF-8 (replace errors)
+      - result has `.stdout` (str or bytes) -> used
+      - fallback: str(result)
+    """
+    if isinstance(result, str):
+        return result
+
+    if isinstance(result, (bytes, bytearray)):
+        return bytes(result).decode("utf-8", errors="replace")
+
+    stdout = getattr(result, "stdout", None)
+    if isinstance(stdout, str):
+        return stdout
+    if isinstance(stdout, (bytes, bytearray)):
+        return bytes(stdout).decode("utf-8", errors="replace")
+
+    return str(result)

src/pkgmgr/actions/install/installers/nix/profile_list.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING, List, Tuple
+
+from .runner import CommandRunner
+
+if TYPE_CHECKING:
+    from pkgmgr.actions.install.context import RepoContext
+
+
+class NixProfileListReader:
+    def __init__(self, runner: CommandRunner) -> None:
+        self._runner = runner
+
+    @staticmethod
+    def _store_prefix(path: str) -> str:
+        raw = (path or "").strip()
+        m = re.match(r"^(/nix/store/[0-9a-z]{32}-[^/ \t]+)", raw)
+        return m.group(1) if m else raw
+
+    def entries(self, ctx: "RepoContext") -> List[Tuple[int, str]]:
+        res = self._runner.run(ctx, "nix profile list", allow_failure=True)
+        if res.returncode != 0:
+            return []
+
+        entries: List[Tuple[int, str]] = []
+        pat = re.compile(
+            r"^\s*(\d+)\s+.*?(/nix/store/[0-9a-z]{32}-[^/ \t]+)",
+            re.MULTILINE,
+        )
+
+        for m in pat.finditer(res.stdout or ""):
+            idx_s = m.group(1)
+            sp = m.group(2)
+            try:
+                idx = int(idx_s)
+            except Exception:
+                continue
+            entries.append((idx, self._store_prefix(sp)))
+
+        seen: set[int] = set()
+        uniq: List[Tuple[int, str]] = []
+        for idx, sp in entries:
+            if idx not in seen:
+                seen.add(idx)
+                uniq.append((idx, sp))
+
+        return uniq
+
+    def indices_matching_store_prefixes(self, ctx: "RepoContext", prefixes: List[str]) -> List[int]:
+        prefixes = [self._store_prefix(p) for p in prefixes if p]
+        prefixes = [p for p in prefixes if p]
+        if not prefixes:
+            return []
+
+        hits: List[int] = []
+        for idx, sp in self.entries(ctx):
+            if any(sp == p for p in prefixes):
+                hits.append(idx)
+
+        seen: set[int] = set()
+        uniq: List[int] = []
+        for i in hits:
+            if i not in seen:
+                seen.add(i)
+                uniq.append(i)
+
+        return uniq

src/pkgmgr/actions/install/installers/nix/textparse.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import re
+from typing import List
+
+
+class NixConflictTextParser:
+    @staticmethod
+    def _store_prefix(path: str) -> str:
+        raw = (path or "").strip()
+        m = re.match(r"^(/nix/store/[0-9a-z]{32}-[^/ \t]+)", raw)
+        return m.group(1) if m else raw
+
+    def remove_tokens(self, text: str) -> List[str]:
+        pat = re.compile(
+            r"^\s*nix profile remove\s+([^\s'\"`]+|'[^']+'|\"[^\"]+\")\s*$",
+            re.MULTILINE,
+        )
+
+        tokens: List[str] = []
+        for m in pat.finditer(text or ""):
+            t = (m.group(1) or "").strip()
+            if (t.startswith("'") and t.endswith("'")) or (t.startswith('"') and t.endswith('"')):
+                t = t[1:-1]
+            if t:
+                tokens.append(t)
+
+        seen: set[str] = set()
+        uniq: List[str] = []
+        for t in tokens:
+            if t not in seen:
+                seen.add(t)
+                uniq.append(t)
+
+        return uniq
+
+    def existing_store_prefixes(self, text: str) -> List[str]:
+        lines = (text or "").splitlines()
+        prefixes: List[str] = []
+
+        in_existing = False
+        in_new = False
+
+        store_pat = re.compile(r"^\s*(/nix/store/[0-9a-z]{32}-[^ \t]+)")
+
+        for raw in lines:
+            line = raw.strip()
+
+            if "An existing package already provides the following file" in line:
+                in_existing = True
+                in_new = False
+                continue
+
+            if "This is the conflicting file from the new package" in line:
+                in_existing = False
+                in_new = True
+                continue
+
+            if in_existing:
+                m = store_pat.match(raw)
+                if m:
+                    prefixes.append(m.group(1))
+                    continue
+
+            _ = in_new
+
+        norm = [self._store_prefix(p) for p in prefixes if p]
+
+        seen: set[str] = set()
+        uniq: List[str] = []
+        for p in norm:
+            if p and p not in seen:
+                seen.add(p)
+                uniq.append(p)
+
+        return uniq

src/pkgmgr/actions/mirror/git_remote.py

@@ -1,20 +1,26 @@
 from __future__ import annotations
 
 import os
+from typing import Optional, Set
 
-from pkgmgr.core.command.run import run_command
-from pkgmgr.core.git import GitError, run_git
-from typing import List, Optional, Set
+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 build_default_ssh_url(repo: Repository) -> Optional[str]:
-    """
-    Build a simple SSH URL from repo config if no explicit mirror is defined.
-
-    Example: git@github.com:account/repository.git
-    """
     provider = repo.get("provider")
     account = repo.get("account")
     name = repo.get("repository")
@@ -23,96 +29,73 @@ def build_default_ssh_url(repo: Repository) -> Optional[str]:
     if not provider or not account or not name:
         return None
 
-    provider = str(provider)
-    account = str(account)
-    name = str(name)
-
     if port:
         return f"ssh://git@{provider}:{port}/{account}/{name}.git"
 
-    # GitHub-style shorthand
     return f"git@{provider}:{account}/{name}.git"
 
 
 def determine_primary_remote_url(
     repo: Repository,
-    resolved_mirrors: MirrorMap,
+    ctx: RepoMirrorContext,
 ) -> Optional[str]:
     """
-    Determine the primary remote URL in a consistent way:
-
-      1. resolved_mirrors["origin"]
-      2. any resolved mirror (first by name)
-      3. default SSH URL from provider/account/repository
+    Priority order:
+      1. origin from resolved mirrors
+      2. MIRRORS file order
+      3. config mirrors order
+      4. default SSH URL
     """
-    if "origin" in resolved_mirrors:
-        return resolved_mirrors["origin"]
+    resolved = ctx.resolved_mirrors
 
-    if resolved_mirrors:
-        first_name = sorted(resolved_mirrors.keys())[0]
-        return resolved_mirrors[first_name]
+    if resolved.get("origin"):
+        return resolved["origin"]
+
+    for mirrors in (ctx.file_mirrors, ctx.config_mirrors):
+        for _, url in mirrors.items():
+            if url:
+                return url
 
     return build_default_ssh_url(repo)
 
 
-def _safe_git_output(args: List[str], cwd: str) -> Optional[str]:
-    """
-    Run a Git command via run_git and return its stdout, or None on failure.
-    """
-    try:
-        return run_git(args, cwd=cwd)
-    except GitError:
-        return None
-
-
-def current_origin_url(repo_dir: str) -> Optional[str]:
-    """
-    Return the current URL for remote 'origin', or None if not present.
-    """
-    output = _safe_git_output(["remote", "get-url", "origin"], cwd=repo_dir)
-    if not output:
-        return None
-    url = output.strip()
-    return url or None
-
-
 def has_origin_remote(repo_dir: str) -> bool:
-    """
-    Check whether a remote called 'origin' exists in the repository.
-    """
-    output = _safe_git_output(["remote"], cwd=repo_dir)
-    if not output:
+    try:
+        return "origin" in list_remotes(cwd=repo_dir)
+    except GitError:
         return False
-    names = output.split()
-    return "origin" in names
 
 
-def _ensure_push_urls_for_origin(
+def _set_origin_fetch_and_push(repo_dir: str, url: str, preview: bool) -> None:
+    """
+    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(
     repo_dir: str,
     mirrors: MirrorMap,
+    primary: str,
     preview: bool,
 ) -> None:
     """
-    Ensure that all mirror URLs are present as push URLs on 'origin'.
+    Ensure all mirror URLs (except primary) are configured as additional push URLs for origin.
+    Preview is handled by the underlying git runner.
     """
-    desired: Set[str] = {url for url in mirrors.values() if url}
+    desired: Set[str] = {u for u in mirrors.values() if u and u != primary}
     if not desired:
         return
 
-    existing_output = _safe_git_output(
-        ["remote", "get-url", "--push", "--all", "origin"],
-        cwd=repo_dir,
-    )
-    existing = set(existing_output.splitlines()) if existing_output else set()
+    try:
+        existing = get_remote_push_urls("origin", cwd=repo_dir)
+    except GitError:
+        existing = set()
 
-    missing = sorted(desired - existing)
-    for url in missing:
-        cmd = f"git remote set-url --add --push origin {url}"
-        if preview:
-            print(f"[PREVIEW] Would run in {repo_dir!r}: {cmd}")
-        else:
-            print(f"[INFO] Adding push URL to 'origin': {url}")
-            run_command(cmd, cwd=repo_dir, preview=False)
+    for url in sorted(desired - existing):
+        add_remote_push_url("origin", url, cwd=repo_dir, preview=preview)
 
 
 def ensure_origin_remote(
@@ -120,60 +103,34 @@ def ensure_origin_remote(
     ctx: RepoMirrorContext,
     preview: bool,
 ) -> None:
-    """
-    Ensure that a usable 'origin' remote exists and has all push URLs.
-    """
     repo_dir = ctx.repo_dir
-    resolved_mirrors = ctx.resolved_mirrors
 
     if not os.path.isdir(os.path.join(repo_dir, ".git")):
-        print(f"[WARN] {repo_dir} is not a Git repository (no .git directory).")
+        print(f"[WARN] {repo_dir} is not a Git repository.")
         return
 
-    url = determine_primary_remote_url(repo, resolved_mirrors)
+    primary = determine_primary_remote_url(repo, ctx)
+    if not primary:
+        print("[WARN] No primary mirror URL could be determined.")
+        return
 
+    # 1) Ensure origin exists
     if not has_origin_remote(repo_dir):
-        if not url:
-            print(
-                "[WARN] Could not determine URL for 'origin' remote. "
-                "Please configure mirrors or provider/account/repository."
-            )
-            return
+        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
 
-        cmd = f"git remote add origin {url}"
-        if preview:
-            print(f"[PREVIEW] Would run in {repo_dir!r}: {cmd}")
-        else:
-            print(f"[INFO] Adding 'origin' remote in {repo_dir}: {url}")
-            run_command(cmd, cwd=repo_dir, preview=False)
-    else:
-        current = current_origin_url(repo_dir)
-        if current == url or not url:
-            print(
-                "[INFO] 'origin' already points to "
-                f"{current or '<unknown>'} (no change needed)."
-            )
-        else:
-            # We do not auto-change origin here, only log the mismatch.
-            print(
-                "[INFO] 'origin' exists with URL "
-                f"{current or '<unknown>'}; not changing to {url}."
-            )
-
-    # Ensure all mirrors are present as push URLs
-    _ensure_push_urls_for_origin(repo_dir, resolved_mirrors, preview)
-
-
-def is_remote_reachable(url: str, cwd: Optional[str] = None) -> bool:
-    """
-    Check whether a remote repository is reachable via `git ls-remote`.
-
-    This does NOT modify anything; it only probes the remote.
-    """
-    workdir = cwd or os.getcwd()
+    # 2) Ensure origin fetch+push URLs are correct (ALWAYS, even if origin already existed)
     try:
-        # --exit-code → non-zero exit code if the remote does not exist
-        run_git(["ls-remote", "--exit-code", url], cwd=workdir)
-        return True
-    except GitError:
-        return False
+        _set_origin_fetch_and_push(repo_dir, primary, preview)
+    except GitSetRemoteUrlError as exc:
+        # Do not abort: still try to add additional push URLs
+        print(f"[WARN] Failed to set origin URLs: {exc}")
+
+    # 3) Ensure additional push URLs for mirrors
+    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_provision.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from typing import List
+
+from pkgmgr.core.remote_provisioning import ProviderHint, RepoSpec, ensure_remote_repo
+from pkgmgr.core.remote_provisioning.ensure import EnsureOptions
+
+from .context import build_context
+from .git_remote import determine_primary_remote_url
+from .types import Repository
+from .url_utils import normalize_provider_host, parse_repo_from_git_url
+
+
+def ensure_remote_repository(
+    repo: Repository,
+    repositories_base_dir: str,
+    all_repos: List[Repository],
+    preview: bool,
+) -> None:
+    ctx = build_context(repo, repositories_base_dir, all_repos)
+
+    primary_url = determine_primary_remote_url(repo, ctx)
+    if not primary_url:
+        print("[INFO] No primary URL found; skipping remote provisioning.")
+        return
+
+    host_raw, owner, name = parse_repo_from_git_url(primary_url)
+    host = normalize_provider_host(host_raw)
+
+    if not host or not owner or not name:
+        print("[WARN] Could not parse remote URL:", primary_url)
+        return
+
+    spec = RepoSpec(
+        host=host,
+        owner=owner,
+        name=name,
+        private=bool(repo.get("private", True)),
+        description=str(repo.get("description", "")),
+    )
+
+    provider_kind = str(repo.get("provider", "")).lower() or None
+
+    try:
+        result = ensure_remote_repo(
+            spec,
+            provider_hint=ProviderHint(kind=provider_kind),
+            options=EnsureOptions(
+                preview=preview,
+                interactive=True,
+                allow_prompt=True,
+                save_prompt_token_to_keyring=True,
+            ),
+        )
+        print(f"[REMOTE ENSURE] {result.status.upper()}: {result.message}")
+        if result.url:
+            print(f"[REMOTE ENSURE] URL: {result.url}")
+    except Exception as exc:  # noqa: BLE001
+        print(f"[ERROR] Remote provisioning failed: {exc}")

src/pkgmgr/actions/mirror/setup_cmd.py

@@ -1,131 +1,20 @@
-# src/pkgmgr/actions/mirror/setup_cmd.py
 from __future__ import annotations
 
-from typing import List, Tuple
-from urllib.parse import urlparse
-
-from pkgmgr.core.git import GitError, run_git
-from pkgmgr.core.remote_provisioning import ProviderHint, RepoSpec, ensure_remote_repo
-from pkgmgr.core.remote_provisioning.ensure import EnsureOptions
+from typing import List
 
 from .context import build_context
-from .git_remote import determine_primary_remote_url, ensure_origin_remote
+from .git_remote import ensure_origin_remote, determine_primary_remote_url
+from pkgmgr.core.git.queries import probe_remote_reachable
+from .remote_provision import ensure_remote_repository
 from .types import Repository
 
 
-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)
-
-
-def _host_from_git_url(url: str) -> str:
-    url = (url or "").strip()
-    if not url:
-        return ""
-
-    if "://" in url:
-        parsed = urlparse(url)
-        netloc = (parsed.netloc or "").strip()
-        if "@" in netloc:
-            netloc = netloc.split("@", 1)[1]
-        # keep optional :port
-        return netloc
-
-    # scp-like: git@host:owner/repo.git
-    if "@" in url and ":" in url:
-        after_at = url.split("@", 1)[1]
-        host = after_at.split(":", 1)[0]
-        return host.strip()
-
-    return url.split("/", 1)[0].strip()
-
-def _ensure_remote_repository(
-    repo: Repository,
-    repositories_base_dir: str,
-    all_repos: List[Repository],
-    preview: bool,
-) -> None:
-    """
-    Ensure that the remote repository exists using provider APIs.
-
-    This is ONLY called when ensure_remote=True.
-    """
-    ctx = build_context(repo, repositories_base_dir, all_repos)
-    resolved_mirrors = ctx.resolved_mirrors
-
-    primary_url = determine_primary_remote_url(repo, resolved_mirrors)
-    if not primary_url:
-        print("[INFO] No remote URL could be derived; skipping remote provisioning.")
-        return
-
-    # IMPORTANT:
-    # - repo["provider"] is typically a provider *kind* (e.g. "github" / "gitea"),
-    #   NOT a hostname. We derive the actual host from the remote URL.
-    host = _host_from_git_url(primary_url)
-    owner = repo.get("account")
-    name = repo.get("repository")
-
-    if not host or not owner or not name:
-        print("[WARN] Missing host/account/repository; cannot ensure remote repo.")
-        print(f"       host={host!r}, account={owner!r}, repository={name!r}")
-        return
-
-    print("------------------------------------------------------------")
-    print(f"[REMOTE ENSURE] {ctx.identifier}")
-    print(f"[REMOTE ENSURE] host: {host}")
-    print("------------------------------------------------------------")
-
-    spec = RepoSpec(
-        host=str(host),
-        owner=str(owner),
-        name=str(name),
-        private=bool(repo.get("private", True)),
-        description=str(repo.get("description", "")),
-    )
-
-    provider_kind = str(repo.get("provider", "")).strip().lower() or None
-
-    try:
-        result = ensure_remote_repo(
-            spec,
-            provider_hint=ProviderHint(kind=provider_kind),
-            options=EnsureOptions(
-                preview=preview,
-                interactive=True,
-                allow_prompt=True,
-                save_prompt_token_to_keyring=True,
-            ),
-        )
-        print(f"[REMOTE ENSURE] {result.status.upper()}: {result.message}")
-        if result.url:
-            print(f"[REMOTE ENSURE] URL: {result.url}")
-    except Exception as exc:  # noqa: BLE001
-        # Keep action layer resilient
-        print(f"[ERROR] Remote provisioning failed: {exc}")
-
-    print()
-
-
 def _setup_local_mirrors_for_repo(
     repo: Repository,
     repositories_base_dir: str,
     all_repos: List[Repository],
     preview: bool,
 ) -> None:
-    """
-    Local setup:
-      - Ensure 'origin' remote exists and is sane
-    """
     ctx = build_context(repo, repositories_base_dir, all_repos)
 
     print("------------------------------------------------------------")
@@ -133,7 +22,7 @@ def _setup_local_mirrors_for_repo(
     print(f"[MIRROR SETUP:LOCAL] dir: {ctx.repo_dir}")
     print("------------------------------------------------------------")
 
-    ensure_origin_remote(repo, ctx, preview=preview)
+    ensure_origin_remote(repo, ctx, preview)
     print()
 
 
@@ -144,19 +33,7 @@ def _setup_remote_mirrors_for_repo(
     preview: bool,
     ensure_remote: bool,
 ) -> None:
-    """
-    Remote-side setup / validation.
-
-    Default behavior:
-      - Non-destructive checks using `git ls-remote`.
-
-    Optional behavior:
-      - If ensure_remote=True:
-          * Attempt to create missing repositories via provider API
-          * Uses TokenResolver (ENV -> keyring -> prompt)
-    """
     ctx = build_context(repo, repositories_base_dir, all_repos)
-    resolved_mirrors = ctx.resolved_mirrors
 
     print("------------------------------------------------------------")
     print(f"[MIRROR SETUP:REMOTE] {ctx.identifier}")
@@ -164,39 +41,25 @@ def _setup_remote_mirrors_for_repo(
     print("------------------------------------------------------------")
 
     if ensure_remote:
-        _ensure_remote_repository(
+        ensure_remote_repository(
             repo,
-            repositories_base_dir=repositories_base_dir,
-            all_repos=all_repos,
-            preview=preview,
+            repositories_base_dir,
+            all_repos,
+            preview,
         )
 
-    if not resolved_mirrors:
-        primary_url = determine_primary_remote_url(repo, resolved_mirrors)
-        if not primary_url:
-            print("[INFO] No mirrors configured and no primary URL available.")
-            print()
+    if not ctx.resolved_mirrors:
+        primary = determine_primary_remote_url(repo, ctx)
+        if not primary:
             return
-
-        ok, error_message = _probe_mirror(primary_url, ctx.repo_dir)
-        if ok:
-            print(f"[OK] primary: {primary_url}")
-        else:
-            print(f"[WARN] primary: {primary_url}")
-            for line in error_message.splitlines():
-                print(f"         {line}")
-
+        ok = probe_remote_reachable(primary, cwd=ctx.repo_dir)
+        print("[OK]" if ok else "[WARN]", primary)
         print()
         return
 
-    for name, url in sorted(resolved_mirrors.items()):
-        ok, error_message = _probe_mirror(url, ctx.repo_dir)
-        if ok:
-            print(f"[OK] {name}: {url}")
-        else:
-            print(f"[WARN] {name}: {url}")
-            for line in error_message.splitlines():
-                print(f"         {line}")
+    for name, url in ctx.resolved_mirrors.items():
+        ok = probe_remote_reachable(url, cwd=ctx.repo_dir)
+        print(f"[OK] {name}: {url}" if ok else f"[WARN] {name}: {url}")
 
     print()
 
@@ -210,33 +73,20 @@ def setup_mirrors(
     remote: bool = True,
     ensure_remote: bool = False,
 ) -> None:
-    """
-    Setup mirrors for the selected repositories.
-
-    local:
-      - Configure local Git remotes (ensure 'origin' exists).
-
-    remote:
-      - Non-destructive remote checks using `git ls-remote`.
-
-    ensure_remote:
-      - If True, attempt to create missing remote repositories via provider APIs.
-      - This is explicit and NEVER enabled implicitly.
-    """
     for repo in selected_repos:
         if local:
             _setup_local_mirrors_for_repo(
-                repo=repo,
-                repositories_base_dir=repositories_base_dir,
-                all_repos=all_repos,
-                preview=preview,
+                repo,
+                repositories_base_dir,
+                all_repos,
+                preview,
             )
 
         if remote:
             _setup_remote_mirrors_for_repo(
-                repo=repo,
-                repositories_base_dir=repositories_base_dir,
-                all_repos=all_repos,
-                preview=preview,
-                ensure_remote=ensure_remote,
+                repo,
+                repositories_base_dir,
+                all_repos,
+                preview,
+                ensure_remote,
             )

src/pkgmgr/actions/mirror/url_utils.py

@@ -0,0 +1,111 @@
+# src/pkgmgr/actions/mirror/url_utils.py
+from __future__ import annotations
+
+from urllib.parse import urlparse
+from typing import Optional, Tuple
+
+
+def hostport_from_git_url(url: str) -> Tuple[str, Optional[str]]:
+    url = (url or "").strip()
+    if not url:
+        return "", None
+
+    if "://" in url:
+        parsed = urlparse(url)
+        netloc = (parsed.netloc or "").strip()
+        if "@" in netloc:
+            netloc = netloc.split("@", 1)[1]
+
+        if netloc.startswith("[") and "]" in netloc:
+            host = netloc[1:netloc.index("]")]
+            rest = netloc[netloc.index("]") + 1 :]
+            port = rest[1:] if rest.startswith(":") else None
+            return host.strip(), (port.strip() if port else None)
+
+        if ":" in netloc:
+            host, port = netloc.rsplit(":", 1)
+            return host.strip(), (port.strip() or None)
+
+        return netloc.strip(), None
+
+    if "@" in url and ":" in url:
+        after_at = url.split("@", 1)[1]
+        host = after_at.split(":", 1)[0].strip()
+        return host, None
+
+    host = url.split("/", 1)[0].strip()
+    return host, None
+
+
+def normalize_provider_host(host: str) -> str:
+    host = (host or "").strip()
+    if not host:
+        return ""
+
+    if host.startswith("[") and "]" in host:
+        host = host[1:host.index("]")]
+
+    if ":" in host and host.count(":") == 1:
+        host = host.rsplit(":", 1)[0]
+
+    return host.strip().lower()
+
+
+def _strip_dot_git(name: str) -> str:
+    n = (name or "").strip()
+    if n.lower().endswith(".git"):
+        return n[:-4]
+    return n
+
+
+def parse_repo_from_git_url(url: str) -> Tuple[str, Optional[str], Optional[str]]:
+    """
+    Parse (host, owner, repo_name) from common Git remote URLs.
+
+    Supports:
+      - ssh://git@host:2201/owner/repo.git
+      - https://host/owner/repo.git
+      - git@host:owner/repo.git
+      - host/owner/repo(.git) (best-effort)
+
+    Returns:
+      (host, owner, repo_name) with owner/repo possibly None if not derivable.
+    """
+    u = (url or "").strip()
+    if not u:
+        return "", None, None
+
+    # URL-style (ssh://, https://, http://)
+    if "://" in u:
+        parsed = urlparse(u)
+        host = (parsed.hostname or "").strip()
+        path = (parsed.path or "").strip("/")
+        parts = [p for p in path.split("/") if p]
+        if len(parts) >= 2:
+            owner = parts[0]
+            repo_name = _strip_dot_git(parts[1])
+            return host, owner, repo_name
+        return host, None, None
+
+    # SCP-like: git@host:owner/repo.git
+    if "@" in u and ":" in u:
+        after_at = u.split("@", 1)[1]
+        host = after_at.split(":", 1)[0].strip()
+        path = after_at.split(":", 1)[1].strip("/")
+        parts = [p for p in path.split("/") if p]
+        if len(parts) >= 2:
+            owner = parts[0]
+            repo_name = _strip_dot_git(parts[1])
+            return host, owner, repo_name
+        return host, None, None
+
+    # Fallback: host/owner/repo.git
+    host = u.split("/", 1)[0].strip()
+    rest = u.split("/", 1)[1] if "/" in u else ""
+    parts = [p for p in rest.strip("/").split("/") if p]
+    if len(parts) >= 2:
+        owner = parts[0]
+        repo_name = _strip_dot_git(parts[1])
+        return host, owner, repo_name
+
+    return host, None, None

src/pkgmgr/actions/publish/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from .workflow import publish
+
+__all__ = ["publish"]

src/pkgmgr/actions/publish/git_tags.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+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]:
+    tags = get_tags_at_ref("HEAD", cwd=cwd)
+    tags = [t for t in tags if is_semver_tag(t) and t.startswith("v")]
+    return sorted(tags, key=SemVer.parse)

src/pkgmgr/actions/publish/pypi_url.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from urllib.parse import urlparse
+
+from .types import PyPITarget
+
+
+def parse_pypi_project_url(url: str) -> PyPITarget | None:
+    u = (url or "").strip()
+    if not u:
+        return None
+
+    parsed = urlparse(u)
+    host = (parsed.netloc or "").lower()
+    path = (parsed.path or "").strip("/")
+
+    if host not in ("pypi.org", "test.pypi.org"):
+        return None
+
+    parts = [p for p in path.split("/") if p]
+    if len(parts) >= 2 and parts[0] == "project":
+        return PyPITarget(host=host, project=parts[1])
+
+    return None

src/pkgmgr/actions/publish/types.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class PyPITarget:
+    host: str
+    project: str

src/pkgmgr/actions/publish/workflow.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import glob
+import os
+import shutil
+import subprocess
+
+from pkgmgr.actions.mirror.io import read_mirrors_file
+from pkgmgr.actions.mirror.types import Repository
+from pkgmgr.core.credentials.resolver import ResolutionOptions, TokenResolver
+from pkgmgr.core.version.semver import SemVer
+
+from .git_tags import head_semver_tags
+from .pypi_url import parse_pypi_project_url
+
+
+def _require_tool(module: str) -> None:
+    try:
+        subprocess.run(
+            ["python", "-m", module, "--help"],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            check=True,
+        )
+    except Exception as exc:
+        raise RuntimeError(
+            f"Required Python module '{module}' is not available. "
+            f"Install it via: pip install {module}"
+        ) from exc
+
+
+def publish(
+    repo: Repository,
+    repo_dir: str,
+    *,
+    preview: bool = False,
+    interactive: bool = True,
+    allow_prompt: bool = True,
+) -> None:
+    mirrors = read_mirrors_file(repo_dir)
+
+    targets = []
+    for url in mirrors.values():
+        t = parse_pypi_project_url(url)
+        if t:
+            targets.append(t)
+
+    if not targets:
+        print("[INFO] No PyPI mirror found. Skipping publish.")
+        return
+
+    if len(targets) > 1:
+        raise RuntimeError("Multiple PyPI mirrors found; refusing to publish.")
+
+    tags = head_semver_tags(cwd=repo_dir)
+    if not tags:
+        print("[INFO] No version tag on HEAD. Skipping publish.")
+        return
+
+    tag = max(tags, key=SemVer.parse)
+    target = targets[0]
+
+    print(f"[INFO] Publishing {target.project} for tag {tag}")
+
+    if preview:
+        print("[PREVIEW] Would build and upload to PyPI.")
+        return
+
+    _require_tool("build")
+    _require_tool("twine")
+
+    dist_dir = os.path.join(repo_dir, "dist")
+    if os.path.isdir(dist_dir):
+        shutil.rmtree(dist_dir, ignore_errors=True)
+
+    subprocess.run(
+        ["python", "-m", "build"],
+        cwd=repo_dir,
+        check=True,
+    )
+
+    artifacts = sorted(glob.glob(os.path.join(dist_dir, "*")))
+    if not artifacts:
+        raise RuntimeError("No build artifacts found in dist/.")
+
+    resolver = TokenResolver()
+
+    # Store PyPI token per OS user (keyring is already user-scoped).
+    # Do NOT scope by project name.
+    token = resolver.get_token(
+        provider_kind="pypi",
+        host=target.host,
+        owner=None,
+        options=ResolutionOptions(
+            interactive=interactive,
+            allow_prompt=allow_prompt,
+            save_prompt_token_to_keyring=True,
+        ),
+    ).token
+
+    env = dict(os.environ)
+    env["TWINE_USERNAME"] = "__token__"
+    env["TWINE_PASSWORD"] = token
+
+    subprocess.run(
+        ["python", "-m", "twine", "upload", *artifacts],
+        cwd=repo_dir,
+        env=env,
+        check=True,
+    )
+
+    print("[INFO] Publish completed.")

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,10 +1,13 @@
 from __future__ import annotations
-from typing import Optional
+
 import os
 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.queries import get_current_branch
+from pkgmgr.core.repository.paths import resolve_repo_paths
 
 from .files import (
     update_changelog,
@@ -55,8 +58,12 @@ def _release_impl(
     print(f"New version:     {new_ver_str} ({release_type})")
 
     repo_root = os.path.dirname(os.path.abspath(pyproject_path))
+    paths = resolve_repo_paths(repo_root)
+
+    # --- Update versioned files ------------------------------------------------
 
     update_pyproject_version(pyproject_path, new_ver_str, preview=preview)
+
     changelog_message = update_changelog(
         changelog_path,
         new_ver_str,
@@ -64,38 +71,46 @@ def _release_impl(
         preview=preview,
     )
 
-    flake_path = os.path.join(repo_root, "flake.nix")
-    update_flake_version(flake_path, new_ver_str, preview=preview)
+    update_flake_version(paths.flake_nix, new_ver_str, preview=preview)
 
-    pkgbuild_path = os.path.join(repo_root, "PKGBUILD")
-    update_pkgbuild_version(pkgbuild_path, new_ver_str, preview=preview)
+    if paths.arch_pkgbuild:
+        update_pkgbuild_version(paths.arch_pkgbuild, new_ver_str, preview=preview)
+    else:
+        print("[INFO] No PKGBUILD found (packaging/arch/PKGBUILD or PKGBUILD). Skipping.")
 
-    spec_path = os.path.join(repo_root, "package-manager.spec")
-    update_spec_version(spec_path, new_ver_str, preview=preview)
+    if paths.rpm_spec:
+        update_spec_version(paths.rpm_spec, new_ver_str, preview=preview)
+    else:
+        print("[INFO] No RPM spec file found. Skipping spec version update.")
 
     effective_message: Optional[str] = message
     if effective_message is None and isinstance(changelog_message, str):
         if changelog_message.strip():
             effective_message = changelog_message.strip()
 
-    debian_changelog_path = os.path.join(repo_root, "debian", "changelog")
     package_name = os.path.basename(repo_root) or "package-manager"
 
-    update_debian_changelog(
-        debian_changelog_path,
-        package_name=package_name,
-        new_version=new_ver_str,
-        message=effective_message,
-        preview=preview,
-    )
+    if paths.debian_changelog:
+        update_debian_changelog(
+            paths.debian_changelog,
+            package_name=package_name,
+            new_version=new_ver_str,
+            message=effective_message,
+            preview=preview,
+        )
+    else:
+        print("[INFO] No debian changelog found. Skipping debian/changelog update.")
 
-    update_spec_changelog(
-        spec_path=spec_path,
-        package_name=package_name,
-        new_version=new_ver_str,
-        message=effective_message,
-        preview=preview,
-    )
+    if paths.rpm_spec:
+        update_spec_changelog(
+            spec_path=paths.rpm_spec,
+            package_name=package_name,
+            new_version=new_ver_str,
+            message=effective_message,
+            preview=preview,
+        )
+
+    # --- Git commit / tag / push ----------------------------------------------
 
     commit_msg = f"Release version {new_ver_str}"
     tag_msg = effective_message or commit_msg
@@ -103,12 +118,12 @@ def _release_impl(
     files_to_add = [
         pyproject_path,
         changelog_path,
-        flake_path,
-        pkgbuild_path,
-        spec_path,
-        debian_changelog_path,
+        paths.flake_nix,
+        paths.arch_pkgbuild,
+        paths.rpm_spec,
+        paths.debian_changelog,
     ]
-    existing_files = [p for p in files_to_add if p and os.path.exists(p)]
+    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:

src/pkgmgr/actions/repository/create.py

@@ -1,143 +1,257 @@
+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
 
-def create_repo(identifier, config_merged, user_config_path, bin_dir, remote=False, preview=False):
-    """
-    Creates a new repository by performing the following steps:
-    
-    1. Parses the identifier (provider:port/account/repository) and adds a new entry to the user config
-       if it is not already present. The provider part is split into provider and port (if provided).
-    2. Creates the local repository directory and initializes a Git repository.
-    3. If --remote is set, checks for an existing "origin" remote (removing it if found),
-       adds the remote using a URL built from provider, port, account, and repository,
-       creates an initial commit (e.g. with a README.md), and pushes to the remote.
-       The push is attempted on both "main" and "master" branches.
-    """
-    parts = identifier.split("/")
+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:
-        print("Identifier must be in the format 'provider:port/account/repository' (port is optional).")
+        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
 
-    provider_with_port, account, repository = parts
-    # Split provider and port if a colon is present.
-    if ":" in provider_with_port:
-        provider_name, port = provider_with_port.split(":", 1)
-    else:
-        provider_name = provider_with_port
-        port = None
+    subprocess.run('git commit -m "Initial commit"', cwd=repo_dir, shell=True, check=False)
 
-    # Check if the repository is already present in the merged config (including port)
-    exists = False
-    for repo in config_merged.get("repositories", []):
-        if (repo.get("provider") == provider_name and 
-            repo.get("account") == account and 
-            repo.get("repository") == repository):
-            exists = True
-            print(f"Repository {identifier} already exists in the configuration.")
-            break
+
+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:
-        # Create a new entry with an automatically generated alias.
-        new_entry = {
-            "provider": provider_name,
-            "port": port,
-            "account": account,
-            "repository": repository,
-            "alias": generate_alias({"repository": repository, "provider": provider_name, "account": account}, bin_dir, existing_aliases=set()),
-            "verified": {}  # No initial verification info
+        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": {},
         }
-        # Load or initialize the user configuration.
+
         if os.path.exists(user_config_path):
-            with open(user_config_path, "r") as f:
+            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)
-        save_user_config(user_config, user_config_path)
-        print(f"Repository {identifier} added to the configuration.")
-        # Also update the merged configuration object.
-        config_merged.setdefault("repositories", []).append(new_entry)
 
-    # Create the local repository directory based on the configured base directory.
-    base_dir = os.path.expanduser(config_merged["directories"]["repositories"])
-    repo_dir = os.path.join(base_dir, provider_name, account, repository)
-    if not os.path.exists(repo_dir):
-        os.makedirs(repo_dir, exist_ok=True)
-        print(f"Local repository directory created: {repo_dir}")
-    else:
-        print(f"Local repository directory already exists: {repo_dir}")
-
-    # Initialize a Git repository if not already initialized.
-    if not os.path.exists(os.path.join(repo_dir, ".git")):
-        cmd_init = "git init"
         if preview:
-            print(f"[Preview] Would execute: '{cmd_init}' in {repo_dir}")
+            print(f"[Preview] Would save user config: {user_config_path}")
         else:
-            subprocess.run(cmd_init, cwd=repo_dir, shell=True, check=True)
-            print(f"Git repository initialized in {repo_dir}.")
+            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:
-        print("Git repository is already initialized.")
+        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:
-        # Create a README.md if it does not exist to have content for an initial commit.
-        readme_path = os.path.join(repo_dir, "README.md")
-        if not os.path.exists(readme_path):
-            if preview:
-                print(f"[Preview] Would create README.md in {repo_dir}.")
-            else:
-                with open(readme_path, "w") as f:
-                    f.write(f"# {repository}\n")
-                subprocess.run("git add README.md", cwd=repo_dir, shell=True, check=True)
-                subprocess.run('git commit -m "Initial commit"', cwd=repo_dir, shell=True, check=True)
-                print("README.md created and initial commit made.")
-
-        # Build the remote URL.
-        if provider_name.lower() == "github.com":
-            remote_url = f"git@{provider_name}:{account}/{repository}.git"
-        else:
-            if port:
-                remote_url = f"ssh://git@{provider_name}:{port}/{account}/{repository}.git"
-            else:
-                remote_url = f"ssh://git@{provider_name}/{account}/{repository}.git"
-
-        # Check if the remote "origin" already exists.
-        cmd_list = "git remote"
-        if preview:
-            print(f"[Preview] Would check for existing remotes in {repo_dir}")
-            remote_exists = False  # Assume no remote in preview mode.
-        else:
-            result = subprocess.run(cmd_list, cwd=repo_dir, shell=True, capture_output=True, text=True, check=True)
-            remote_list = result.stdout.strip().split()
-            remote_exists = "origin" in remote_list
-
-        if remote_exists:
-            # Remove the existing remote "origin".
-            cmd_remove = "git remote remove origin"
-            if preview:
-                print(f"[Preview] Would execute: '{cmd_remove}' in {repo_dir}")
-            else:
-                subprocess.run(cmd_remove, cwd=repo_dir, shell=True, check=True)
-                print("Existing remote 'origin' removed.")
-
-        # Now add the new remote.
-        cmd_remote = f"git remote add origin {remote_url}"
-        if preview:
-            print(f"[Preview] Would execute: '{cmd_remote}' in {repo_dir}")
-        else:
-            try:
-                subprocess.run(cmd_remote, cwd=repo_dir, shell=True, check=True)
-                print(f"Remote 'origin' added: {remote_url}")
-            except subprocess.CalledProcessError:
-                print(f"Failed to add remote using URL: {remote_url}.")
-
-        # Push the initial commit to the remote repository
-        cmd_push = "git push -u origin master"
-        if preview:
-            print(f"[Preview] Would execute: '{cmd_push}' in {repo_dir}")
-        else:
-            subprocess.run(cmd_push, cwd=repo_dir, shell=True, check=True)
-            print("Initial push to the remote repository completed.")
+        _git_push_main_or_master(repo_dir, preview=preview)

src/pkgmgr/actions/repository/scaffold.py

@@ -0,0 +1,105 @@
+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/actions/update/manager.py

@@ -3,7 +3,7 @@
 
 from __future__ import annotations
 
-from typing import Any, Iterable
+from typing import Any, Iterable, List, Tuple
 
 from pkgmgr.actions.update.system_updater import SystemUpdater
 
@@ -30,32 +30,73 @@ class UpdateManager:
         quiet: bool,
         update_dependencies: bool,
         clone_mode: str,
+        silent: bool = False,
         force_update: bool = True,
     ) -> None:
         from pkgmgr.actions.install import install_repos
         from pkgmgr.actions.repository.pull import pull_with_verification
+        from pkgmgr.core.repository.identifier import get_repo_identifier
 
-        pull_with_verification(
-            selected_repos,
-            repositories_base_dir,
-            all_repos,
-            [],
-            no_verification,
-            preview,
-        )
+        failures: List[Tuple[str, str]] = []
 
-        install_repos(
-            selected_repos,
-            repositories_base_dir,
-            bin_dir,
-            all_repos,
-            no_verification,
-            preview,
-            quiet,
-            clone_mode,
-            update_dependencies,
-            force_update=force_update,
-        )
+        for repo in list(selected_repos):
+            identifier = get_repo_identifier(repo, all_repos)
+
+            try:
+                pull_with_verification(
+                    [repo],
+                    repositories_base_dir,
+                    all_repos,
+                    [],
+                    no_verification,
+                    preview,
+                )
+            except SystemExit as exc:
+                code = exc.code if isinstance(exc.code, int) else str(exc.code)
+                failures.append((identifier, f"pull failed (exit={code})"))
+                if not quiet:
+                    print(f"[Warning] update: pull failed for {identifier} (exit={code}). Continuing...")
+                continue
+            except Exception as exc:
+                failures.append((identifier, f"pull failed: {exc}"))
+                if not quiet:
+                    print(f"[Warning] update: pull failed for {identifier}: {exc}. Continuing...")
+                continue
+
+            try:
+                install_repos(
+                    [repo],
+                    repositories_base_dir,
+                    bin_dir,
+                    all_repos,
+                    no_verification,
+                    preview,
+                    quiet,
+                    clone_mode,
+                    update_dependencies,
+                    force_update=force_update,
+                    silent=silent,
+                    emit_summary=False,
+                )
+            except SystemExit as exc:
+                code = exc.code if isinstance(exc.code, int) else str(exc.code)
+                failures.append((identifier, f"install failed (exit={code})"))
+                if not quiet:
+                    print(f"[Warning] update: install failed for {identifier} (exit={code}). Continuing...")
+                continue
+            except Exception as exc:
+                failures.append((identifier, f"install failed: {exc}"))
+                if not quiet:
+                    print(f"[Warning] update: install failed for {identifier}: {exc}. Continuing...")
+                continue
+
+        if failures and not quiet:
+            print("\n[pkgmgr] Update finished with warnings:")
+            for ident, msg in failures:
+                print(f"  - {ident}: {msg}")
+
+        if failures and not silent:
+            raise SystemExit(1)
 
         if system_update:
             self._system_updater.run(preview=preview)

src/pkgmgr/cli/commands/__init__.py

@@ -2,6 +2,7 @@ from .repos import handle_repos_command
 from .config import handle_config
 from .tools import handle_tools_command
 from .release import handle_release
+from .publish import handle_publish
 from .version import handle_version
 from .make import handle_make
 from .changelog import handle_changelog
@@ -13,6 +14,7 @@ __all__ = [
     "handle_config",
     "handle_tools_command",
     "handle_release",
+    "handle_publish",
     "handle_version",
     "handle_make",
     "handle_changelog",

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/publish.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, List
+
+from pkgmgr.actions.publish import publish
+from pkgmgr.cli.context import CLIContext
+from pkgmgr.core.repository.dir import get_repo_dir
+from pkgmgr.core.repository.identifier import get_repo_identifier
+
+Repository = Dict[str, Any]
+
+
+def handle_publish(args, ctx: CLIContext, selected: List[Repository]) -> None:
+    if not selected:
+        print("[pkgmgr] No repositories selected for publish.")
+        return
+
+    for repo in selected:
+        identifier = get_repo_identifier(repo, ctx.all_repositories)
+        repo_dir = repo.get("directory") or get_repo_dir(ctx.repositories_base_dir, repo)
+
+        if not os.path.isdir(repo_dir):
+            print(f"[WARN] Skipping {identifier}: directory missing.")
+            continue
+
+        print(f"[pkgmgr] Publishing repository {identifier}...")
+        publish(
+            repo=repo,
+            repo_dir=repo_dir,
+            preview=getattr(args, "preview", False),
+            interactive=not getattr(args, "non_interactive", False),
+            allow_prompt=not getattr(args, "non_interactive", False),
+        )

src/pkgmgr/cli/commands/release.py

@@ -1,31 +1,17 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 
-"""
-Release command wiring for the pkgmgr CLI.
-
-This module implements the `pkgmgr release` subcommand on top of the
-generic selection logic from cli.dispatch. It does not define its
-own subparser; the CLI surface is configured in cli.parser.
-
-Responsibilities:
-  - Take the parsed argparse.Namespace for the `release` command.
-  - Use the list of selected repositories provided by dispatch_command().
-  - Optionally list affected repositories when --list is set.
-  - For each selected repository, run pkgmgr.actions.release.release(...) in
-    the context of that repository directory.
-"""
-
 from __future__ import annotations
 
 import os
+import sys
 from typing import Any, Dict, List
 
+from pkgmgr.actions.publish import publish as run_publish
+from pkgmgr.actions.release import release as run_release
 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.actions.release import release as run_release
-
 
 Repository = Dict[str, Any]
 
@@ -35,23 +21,10 @@ def handle_release(
     ctx: CLIContext,
     selected: List[Repository],
 ) -> None:
-    """
-    Handle the `pkgmgr release` subcommand.
-
-    Flow:
-      1) Use the `selected` repositories as computed by dispatch_command().
-      2) If --list is given, print the identifiers of the selected repos
-         and return without running any release.
-      3) For each selected repository:
-           - Resolve its identifier and local directory.
-           - Change into that directory.
-           - Call pkgmgr.actions.release.release(...) with the parsed options.
-    """
     if not selected:
         print("[pkgmgr] No repositories selected for release.")
         return
 
-    # List-only mode: show which repositories would be affected.
     if getattr(args, "list", False):
         print("[pkgmgr] Repositories that would be affected by this release:")
         for repo in selected:
@@ -62,29 +35,22 @@ def handle_release(
     for repo in selected:
         identifier = get_repo_identifier(repo, ctx.all_repositories)
 
-        repo_dir = repo.get("directory")
-        if not repo_dir:
-            try:
-                repo_dir = get_repo_dir(ctx.repositories_base_dir, repo)
-            except Exception:
-                repo_dir = None
-
-        if not repo_dir or not os.path.isdir(repo_dir):
-            print(
-                f"[WARN] Skipping repository {identifier}: "
-                "local directory does not exist."
-            )
+        try:
+            repo_dir = repo.get("directory") or get_repo_dir(ctx.repositories_base_dir, repo)
+        except Exception as exc:
+            print(f"[WARN] Skipping repository {identifier}: failed to resolve directory: {exc}")
             continue
 
-        print(
-            f"[pkgmgr] Running release for repository {identifier} "
-            f"in '{repo_dir}'..."
-        )
+        if not os.path.isdir(repo_dir):
+            print(f"[WARN] Skipping repository {identifier}: directory missing.")
+            continue
+
+        print(f"[pkgmgr] Running release for repository {identifier}...")
 
-        # Change to repo directory and invoke the helper.
         cwd_before = os.getcwd()
         try:
             os.chdir(repo_dir)
+
             run_release(
                 pyproject_path="pyproject.toml",
                 changelog_path="CHANGELOG.md",
@@ -94,5 +60,17 @@ def handle_release(
                 force=getattr(args, "force", False),
                 close=getattr(args, "close", False),
             )
+
+            if not getattr(args, "no_publish", False):
+                print(f"[pkgmgr] Running publish for repository {identifier}...")
+                is_tty = sys.stdin.isatty()
+                run_publish(
+                    repo=repo,
+                    repo_dir=repo_dir,
+                    preview=getattr(args, "preview", False),
+                    interactive=is_tty,
+                    allow_prompt=is_tty,
+                )
+
         finally:
             os.chdir(cwd_before)

src/pkgmgr/cli/commands/repos.py

@@ -68,6 +68,7 @@ def handle_repos_command(
             args.clone_mode,
             args.dependencies,
             force_update=getattr(args, "update", False),
+            silent=getattr(args, "silent", False),
         )
         return
 

src/pkgmgr/cli/commands/version.py

@@ -7,10 +7,15 @@ 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,
+    get_installed_nix_profile_version,
+)
 from pkgmgr.core.version.source import (
     read_pyproject_version,
+    read_pyproject_project_name,
     read_flake_version,
     read_pkgbuild_version,
     read_debian_changelog_version,
@@ -18,10 +23,54 @@ from pkgmgr.core.version.source import (
     read_ansible_galaxy_version,
 )
 
-
 Repository = Dict[str, Any]
 
 
+def _print_pkgmgr_self_version() -> None:
+    """
+    Print version information for pkgmgr itself (installed env + nix profile),
+    used when no repository is selected (e.g. user is not inside a repo).
+    """
+    print("pkgmgr version info")
+    print("====================")
+    print("\nRepository: <pkgmgr self>")
+    print("----------------------------------------")
+
+    # Common distribution/module naming variants.
+    python_candidates = [
+        "package-manager",   # PyPI dist name in your project
+        "package_manager",   # module-ish variant
+        "pkgmgr",            # console/alias-ish
+    ]
+    nix_candidates = [
+        "pkgmgr",
+        "package-manager",
+    ]
+
+    installed_python = get_installed_python_version(*python_candidates)
+    installed_nix = get_installed_nix_profile_version(*nix_candidates)
+
+    if installed_python:
+        print(
+            f"Installed (Python env):  {installed_python.version} "
+            f"(dist: {installed_python.name})"
+        )
+    else:
+        print("Installed (Python env):  <not installed>")
+
+    if installed_nix:
+        print(
+            f"Installed (Nix profile): {installed_nix.version} "
+            f"(match: {installed_nix.name})"
+        )
+    else:
+        print("Installed (Nix profile): <not installed>")
+
+    # Helpful context for debugging "why do versions differ?"
+    print(f"Python executable:       {sys.executable}")
+    print(f"Python prefix:           {sys.prefix}")
+
+
 def handle_version(
     args,
     ctx: CLIContext,
@@ -30,20 +79,39 @@ def handle_version(
     """
     Handle the 'version' command.
 
-    Shows version information from various sources (git tags, pyproject,
-    flake.nix, PKGBUILD, debian, spec, Ansible Galaxy).
-    """
+    Shows version information from:
+      - Git tags
+      - packaging metadata
+      - installed Python environment
+      - installed Nix profile
 
-    repo_list = selected
-    if not repo_list:
-        print("No repositories selected for version.")
-        sys.exit(1)
+    Special case:
+      - If no repositories are selected (e.g. not in a repo and no identifiers),
+        print pkgmgr's own installed versions instead of exiting with an error.
+    """
+    if not selected:
+        _print_pkgmgr_self_version()
+        return
 
     print("pkgmgr version info")
     print("====================")
 
-    for repo in repo_list:
-        # Resolve repository directory
+    for repo in selected:
+        identifier = get_repo_identifier(repo, ctx.all_repositories)
+
+        python_candidates: list[str] = []
+        nix_candidates: list[str] = [identifier]
+
+        for key in ("pypi", "pip", "python_package", "distribution", "package"):
+            val = repo.get(key)
+            if isinstance(val, str) and val.strip():
+                python_candidates.append(val.strip())
+
+        python_candidates.append(identifier)
+
+        installed_python = get_installed_python_version(*python_candidates)
+        installed_nix = get_installed_nix_profile_version(*nix_candidates)
+
         repo_dir = repo.get("directory")
         if not repo_dir:
             try:
@@ -51,51 +119,79 @@ def handle_version(
             except Exception:
                 repo_dir = None
 
-        # If no local clone exists, skip gracefully with info message
         if not repo_dir or not os.path.isdir(repo_dir):
-            identifier = get_repo_identifier(repo, ctx.all_repositories)
             print(f"\nRepository: {identifier}")
             print("----------------------------------------")
             print(
-                "[INFO] Skipped: repository directory does not exist "
-                "locally, version detection is not possible."
+                "[INFO] Skipped: repository directory does not exist locally, "
+                "version detection is not possible."
             )
+
+            if installed_python:
+                print(
+                    f"Installed (Python env):  {installed_python.version} "
+                    f"(dist: {installed_python.name})"
+                )
+            else:
+                print("Installed (Python env):  <not installed>")
+
+            if installed_nix:
+                print(
+                    f"Installed (Nix profile): {installed_nix.version} "
+                    f"(match: {installed_nix.name})"
+                )
+            else:
+                print("Installed (Nix profile): <not installed>")
+
             continue
 
         print(f"\nRepository: {repo_dir}")
         print("----------------------------------------")
 
-        # 1) Git tags (SemVer)
         try:
             tags = get_tags(cwd=repo_dir)
         except Exception as exc:
             print(f"[ERROR] Could not read git tags: {exc}")
             tags = []
 
-        latest_tag_info: Optional[Tuple[str, SemVer]]
-        latest_tag_info = find_latest_version(tags) if tags else None
+        latest_tag_info: Optional[Tuple[str, SemVer]] = (
+            find_latest_version(tags) if tags else None
+        )
 
-        if latest_tag_info is None:
-            latest_tag_str = None
-            latest_ver = None
+        if latest_tag_info:
+            tag, ver = latest_tag_info
+            print(f"Git (latest SemVer tag): {tag} (parsed: {ver})")
         else:
-            latest_tag_str, latest_ver = latest_tag_info
+            print("Git (latest SemVer tag): <none found>")
 
-        # 2) Packaging / metadata sources
         pyproject_version = read_pyproject_version(repo_dir)
+        pyproject_name = read_pyproject_project_name(repo_dir)
         flake_version = read_flake_version(repo_dir)
         pkgbuild_version = read_pkgbuild_version(repo_dir)
         debian_version = read_debian_changelog_version(repo_dir)
         spec_version = read_spec_version(repo_dir)
         ansible_version = read_ansible_galaxy_version(repo_dir)
 
-        # 3) Print version summary
-        if latest_ver is not None:
+        if pyproject_name:
+            installed_python = get_installed_python_version(
+                pyproject_name, *python_candidates
+            )
+
+        if installed_python:
             print(
-                f"Git (latest SemVer tag): {latest_tag_str} (parsed: {latest_ver})"
+                f"Installed (Python env):  {installed_python.version} "
+                f"(dist: {installed_python.name})"
             )
         else:
-            print("Git (latest SemVer tag): <none found>")
+            print("Installed (Python env):  <not installed>")
+
+        if installed_nix:
+            print(
+                f"Installed (Nix profile): {installed_nix.version} "
+                f"(match: {installed_nix.name})"
+            )
+        else:
+            print("Installed (Nix profile): <not installed>")
 
         print(f"pyproject.toml:         {pyproject_version or '<not found>'}")
         print(f"flake.nix:              {flake_version or '<not found>'}")
@@ -104,15 +200,16 @@ def handle_version(
         print(f"package-manager.spec:   {spec_version or '<not found>'}")
         print(f"Ansible Galaxy meta:    {ansible_version or '<not found>'}")
 
-        # 4) Consistency hint (Git tag vs. pyproject)
-        if latest_ver is not None and pyproject_version is not None:
+        if latest_tag_info and pyproject_version:
             try:
                 file_ver = SemVer.parse(pyproject_version)
-                if file_ver != latest_ver:
+                if file_ver != latest_tag_info[1]:
                     print(
-                        f"[WARN] Version mismatch: Git={latest_ver}, pyproject={file_ver}"
+                        f"[WARN] Version mismatch: "
+                        f"Git={latest_tag_info[1]}, pyproject={file_ver}"
                     )
             except ValueError:
                 print(
-                    f"[WARN] pyproject version {pyproject_version!r} is not valid SemVer."
+                    f"[WARN] pyproject version {pyproject_version!r} "
+                    f"is not valid SemVer."
                 )

src/pkgmgr/cli/dispatch.py

@@ -1,6 +1,3 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-
 from __future__ import annotations
 
 import os
@@ -16,6 +13,7 @@ from pkgmgr.cli.commands import (
     handle_repos_command,
     handle_tools_command,
     handle_release,
+    handle_publish,
     handle_version,
     handle_config,
     handle_make,
@@ -24,40 +22,20 @@ from pkgmgr.cli.commands import (
     handle_mirror_command,
 )
 
-def _has_explicit_selection(args) -> bool:
-    """
-    Return True if the user explicitly selected repositories via
-    identifiers / --all / --category / --tag / --string.
-    """
-    identifiers = getattr(args, "identifiers", []) or []
-    use_all = getattr(args, "all", False)
-    categories = getattr(args, "category", []) or []
-    tags = getattr(args, "tag", []) or []
-    string_filter = getattr(args, "string", "") or ""
 
+def _has_explicit_selection(args) -> bool:
     return bool(
-        use_all
-        or identifiers
-        or categories
-        or tags
-        or string_filter
+        getattr(args, "all", False)
+        or getattr(args, "identifiers", [])
+        or getattr(args, "category", [])
+        or getattr(args, "tag", [])
+        or getattr(args, "string", "")
     )
 
 
-def _select_repo_for_current_directory(
-    ctx: CLIContext,
-) -> List[Dict[str, Any]]:
-    """
-    Heuristic: find the repository whose local directory matches the
-    current working directory or is the closest parent.
-
-    Example:
-      - Repo directory: /home/kevin/Repositories/foo
-      - CWD:           /home/kevin/Repositories/foo/subdir
-      → 'foo' is selected.
-    """
+def _select_repo_for_current_directory(ctx: CLIContext) -> List[Dict[str, Any]]:
     cwd = os.path.abspath(os.getcwd())
-    candidates: List[tuple[str, Dict[str, Any]]] = []
+    matches = []
 
     for repo in ctx.all_repositories:
         repo_dir = repo.get("directory")
@@ -65,33 +43,24 @@ def _select_repo_for_current_directory(
             try:
                 repo_dir = get_repo_dir(ctx.repositories_base_dir, repo)
             except Exception:
-                repo_dir = None
-        if not repo_dir:
-            continue
+                continue
 
-        repo_dir_abs = os.path.abspath(os.path.expanduser(repo_dir))
-        if cwd == repo_dir_abs or cwd.startswith(repo_dir_abs + os.sep):
-            candidates.append((repo_dir_abs, repo))
+        repo_dir = os.path.abspath(os.path.expanduser(repo_dir))
+        if cwd == repo_dir or cwd.startswith(repo_dir + os.sep):
+            matches.append((repo_dir, repo))
 
-    if not candidates:
+    if not matches:
         return []
 
-    # Pick the repo with the longest (most specific) path.
-    candidates.sort(key=lambda item: len(item[0]), reverse=True)
-    return [candidates[0][1]]
+    matches.sort(key=lambda x: len(x[0]), reverse=True)
+    return [matches[0][1]]
 
 
 def dispatch_command(args, ctx: CLIContext) -> None:
-    """
-    Dispatch the parsed arguments to the appropriate command handler.
-    """
-
-    # First: proxy commands (git / docker / docker compose / make wrapper etc.)
     if maybe_handle_proxy(args, ctx):
         return
 
-    # Commands that operate on repository selections
-    commands_with_selection: List[str] = [
+    commands_with_selection = {
         "install",
         "update",
         "deinstall",
@@ -103,31 +72,25 @@ def dispatch_command(args, ctx: CLIContext) -> None:
         "list",
         "make",
         "release",
+        "publish",
         "version",
         "changelog",
         "explore",
         "terminal",
         "code",
         "mirror",
-    ]
+    }
 
-    if getattr(args, "command", None) in commands_with_selection:
-        if _has_explicit_selection(args):
-            # Classic selection logic (identifiers / --all / filters)
-            selected = get_selected_repos(args, ctx.all_repositories)
-        else:
-            # Default per help text: repository of current folder.
-            selected = _select_repo_for_current_directory(ctx)
-            # If none is found, leave 'selected' empty.
-            # Individual handlers will then emit a clear message instead
-            # of silently picking an unrelated repository.
+    if args.command in commands_with_selection:
+        selected = (
+            get_selected_repos(args, ctx.all_repositories)
+            if _has_explicit_selection(args)
+            else _select_repo_for_current_directory(ctx)
+        )
     else:
         selected = []
 
-    # ------------------------------------------------------------------ #
-    # Repos-related commands
-    # ------------------------------------------------------------------ #
-    if args.command in (
+    if args.command in {
         "install",
         "deinstall",
         "delete",
@@ -136,15 +99,13 @@ def dispatch_command(args, ctx: CLIContext) -> None:
         "shell",
         "create",
         "list",
-    ):
+    }:
         handle_repos_command(args, ctx, selected)
         return
 
-    # ------------------------------------------------------------
-    # update
-    # ------------------------------------------------------------
     if args.command == "update":
         from pkgmgr.actions.update import UpdateManager
+
         UpdateManager().run(
             selected_repos=selected,
             repositories_base_dir=ctx.repositories_base_dir,
@@ -156,25 +117,23 @@ def dispatch_command(args, ctx: CLIContext) -> None:
             quiet=args.quiet,
             update_dependencies=args.dependencies,
             clone_mode=args.clone_mode,
+            silent=getattr(args, "silent", False),
             force_update=True,
         )
         return
 
-
-    # ------------------------------------------------------------------ #
-    # Tools (explore / terminal / code)
-    # ------------------------------------------------------------------ #
     if args.command in ("explore", "terminal", "code"):
         handle_tools_command(args, ctx, selected)
         return
 
-    # ------------------------------------------------------------------ #
-    # Release / Version / Changelog / Config / Make / Branch
-    # ------------------------------------------------------------------ #
     if args.command == "release":
         handle_release(args, ctx, selected)
         return
 
+    if args.command == "publish":
+        handle_publish(args, ctx, selected)
+        return
+
     if args.command == "version":
         handle_version(args, ctx, selected)
         return

src/pkgmgr/cli/parser/__init__.py

@@ -1,68 +1,73 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-
 from __future__ import annotations
 
 import argparse
 
 from pkgmgr.cli.proxy import register_proxy_commands
 
-from .common import SortedSubParsersAction
-from .install_update import add_install_update_subparsers
-from .config_cmd import add_config_subparsers
-from .navigation_cmd import add_navigation_subparsers
 from .branch_cmd import add_branch_subparsers
-from .release_cmd import add_release_subparser
-from .version_cmd import add_version_subparser
 from .changelog_cmd import add_changelog_subparser
+from .common import SortedSubParsersAction
+from .config_cmd import add_config_subparsers
+from .install_update import add_install_update_subparsers
 from .list_cmd import add_list_subparser
 from .make_cmd import add_make_subparsers
 from .mirror_cmd import add_mirror_subparsers
+from .navigation_cmd import add_navigation_subparsers
+from .publish_cmd import add_publish_subparser
+from .release_cmd import add_release_subparser
+from .version_cmd import add_version_subparser
 
 
 def create_parser(description_text: str) -> argparse.ArgumentParser:
-    """
-    Create the top-level argument parser for pkgmgr.
-    """
     parser = argparse.ArgumentParser(
         description=description_text,
         formatter_class=argparse.RawTextHelpFormatter,
     )
+
     subparsers = parser.add_subparsers(
         dest="command",
         help="Subcommands",
         action=SortedSubParsersAction,
     )
 
-    # Core repo operations
+    # create
+    p_create = subparsers.add_parser(
+        "create",
+        help="Create a new repository (scaffold + config).",
+    )
+    p_create.add_argument(
+        "identifiers",
+        nargs="+",
+        help="Repository identifier(s): URL or 'provider(:port)/owner/repo'.",
+    )
+    p_create.add_argument(
+        "--remote",
+        action="store_true",
+        help="Also push an initial commit to the remote (main/master).",
+    )
+    p_create.add_argument(
+        "--preview",
+        action="store_true",
+        help="Print actions without writing files or executing commands.",
+    )
+
     add_install_update_subparsers(subparsers)
     add_config_subparsers(subparsers)
-
-    # Navigation / tooling around repos
     add_navigation_subparsers(subparsers)
 
-    # Branch & release workflow
     add_branch_subparsers(subparsers)
     add_release_subparser(subparsers)
+    add_publish_subparser(subparsers)
 
-    # Info commands
     add_version_subparser(subparsers)
     add_changelog_subparser(subparsers)
     add_list_subparser(subparsers)
 
-    # Make wrapper
     add_make_subparsers(subparsers)
-
-    # Mirror management
     add_mirror_subparsers(subparsers)
 
-    # Proxy commands (git, docker, docker compose, ...)
     register_proxy_commands(subparsers)
-
     return parser
 
 
-__all__ = [
-    "create_parser",
-    "SortedSubParsersAction",
-]
+__all__ = ["create_parser", "SortedSubParsersAction"]

src/pkgmgr/cli/parser/common.py

@@ -168,3 +168,10 @@ def add_install_update_arguments(subparser: argparse.ArgumentParser) -> None:
         default="ssh",
         help="Specify clone mode (default: ssh).",
     )
+
+    _add_option_if_missing(
+        subparser,
+        "--silent",
+        action="store_true",
+        help="Continue with other repositories if one fails; downgrade errors to warnings.",
+    )

src/pkgmgr/cli/parser/publish_cmd.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+import argparse
+
+from .common import add_identifier_arguments
+
+
+def add_publish_subparser(subparsers: argparse._SubParsersAction) -> None:
+    parser = subparsers.add_parser(
+        "publish",
+        help="Publish repository artifacts (e.g. PyPI) based on MIRRORS.",
+    )
+    add_identifier_arguments(parser)
+
+    parser.add_argument(
+        "--non-interactive",
+        action="store_true",
+        help="Disable interactive credential prompts (CI mode).",
+    )

src/pkgmgr/cli/parser/release_cmd.py

@@ -21,22 +21,22 @@ def add_release_subparser(
             "and updating the changelog."
         ),
     )
+
     release_parser.add_argument(
         "release_type",
         choices=["major", "minor", "patch"],
         help="Type of version increment for the release (major, minor, patch).",
     )
+
     release_parser.add_argument(
         "-m",
         "--message",
         default=None,
-        help=(
-            "Optional release message to add to the changelog and tag."
-        ),
+        help="Optional release message to add to the changelog and tag.",
     )
-    # Generic selection / preview / list / extra_args
+
     add_identifier_arguments(release_parser)
-    # Close current branch after successful release
+
     release_parser.add_argument(
         "--close",
         action="store_true",
@@ -45,7 +45,7 @@ def add_release_subparser(
             "repository, if it is not main/master."
         ),
     )
-    # Force: skip preview+confirmation and run release directly
+
     release_parser.add_argument(
         "-f",
         "--force",
@@ -55,3 +55,9 @@ def add_release_subparser(
             "release directly."
         ),
     )
+
+    release_parser.add_argument(
+        "--no-publish",
+        action="store_true",
+        help="Do not run publish automatically after a successful release.",
+    )

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

@@ -9,15 +9,33 @@ from ..types import KeyringUnavailableError, TokenRequest, TokenResult
 
 
 def _import_keyring():
+    """
+    Import python-keyring.
+
+    Raises:
+      KeyringUnavailableError if:
+        - library is missing
+        - no backend is configured / usable
+        - import fails for any reason
+    """
     try:
         import keyring  # type: ignore
-
-        return keyring
     except Exception as exc:  # noqa: BLE001
         raise KeyringUnavailableError(
-            "python-keyring is not available or no backend is configured."
+            "python-keyring is not installed."
         ) from exc
 
+    # Some environments have keyring installed but no usable backend.
+    # We do a lightweight "backend sanity check" by attempting to read the backend.
+    try:
+        _ = keyring.get_keyring()
+    except Exception as exc:  # noqa: BLE001
+        raise KeyringUnavailableError(
+            "python-keyring is installed but no usable keyring backend is configured."
+        ) from exc
+
+    return keyring
+
 
 @dataclass(frozen=True)
 class KeyringTokenProvider:

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

@@ -9,6 +9,37 @@ from typing import Optional
 from ..types import TokenRequest, TokenResult
 
 
+def _token_help_url(provider_kind: str, host: str) -> Optional[str]:
+    """
+    Return a provider-specific URL where a user can create/get an API token.
+
+    Keep this conservative and stable:
+    - GitHub: official token settings URL
+    - Gitea/Forgejo: common settings path on the given host
+    - GitLab: common personal access token path
+    """
+    kind = (provider_kind or "").strip().lower()
+    h = (host or "").strip()
+
+    # GitHub (cloud)
+    if kind == "github":
+        return "https://github.com/settings/tokens"
+
+    # Gitea / Forgejo (self-hosted)
+    if kind in ("gitea", "forgejo"):
+        # Typical UI path: Settings -> Applications -> Access Tokens
+        # In many installations this is available at /user/settings/applications
+        base = f"https://{h}".rstrip("/")
+        return f"{base}/user/settings/applications"
+
+    # GitLab (cloud or self-hosted)
+    if kind == "gitlab":
+        base = "https://gitlab.com" if not h else f"https://{h}".rstrip("/")
+        return f"{base}/-/profile/personal_access_tokens"
+
+    return None
+
+
 @dataclass(frozen=True)
 class PromptTokenProvider:
     """Interactively prompt for a token.
@@ -25,6 +56,11 @@ class PromptTokenProvider:
             return None
 
         owner_info = f" (owner: {request.owner})" if request.owner else ""
+        help_url = _token_help_url(request.provider_kind, request.host)
+
+        if help_url:
+            print(f"[INFO] Create/get your token here: {help_url}")
+
         prompt = f"Enter API token for {request.provider_kind} on {request.host}{owner_info}: "
         token = (getpass(prompt) or "").strip()
         if not token:

src/pkgmgr/core/credentials/resolver.py

@@ -1,13 +1,14 @@
 # src/pkgmgr/core/credentials/resolver.py
 from __future__ import annotations
 
+import sys
 from dataclasses import dataclass
 from typing import Optional
 
 from .providers.env import EnvTokenProvider
 from .providers.keyring import KeyringTokenProvider
 from .providers.prompt import PromptTokenProvider
-from .types import NoCredentialsError, TokenRequest, TokenResult
+from .types import KeyringUnavailableError, NoCredentialsError, TokenRequest, TokenResult
 
 
 @dataclass(frozen=True)
@@ -26,6 +27,26 @@ class TokenResolver:
         self._env = EnvTokenProvider()
         self._keyring = KeyringTokenProvider()
         self._prompt = PromptTokenProvider()
+        self._warned_keyring: bool = False
+
+    def _warn_keyring_unavailable(self, exc: Exception) -> None:
+        if self._warned_keyring:
+            return
+        self._warned_keyring = True
+
+        msg = str(exc).strip() or "Keyring is unavailable."
+        print("[WARN] Keyring support is not available.", file=sys.stderr)
+        print(f"       {msg}", file=sys.stderr)
+        print("       Tokens will NOT be persisted securely.", file=sys.stderr)
+        print("", file=sys.stderr)
+        print("       To enable secure token storage, install python-keyring:", file=sys.stderr)
+        print("         pip install keyring", file=sys.stderr)
+        print("", file=sys.stderr)
+        print("       Or install via system packages:", file=sys.stderr)
+        print("         sudo apt install python3-keyring", file=sys.stderr)
+        print("         sudo pacman -S python-keyring", file=sys.stderr)
+        print("         sudo dnf install python3-keyring", file=sys.stderr)
+        print("", file=sys.stderr)
 
     def get_token(
         self,
@@ -47,9 +68,11 @@ class TokenResolver:
             kr_res = self._keyring.get(request)
             if kr_res:
                 return kr_res
+        except KeyringUnavailableError as exc:
+            # Show a helpful warning once, then continue (prompt fallback).
+            self._warn_keyring_unavailable(exc)
         except Exception:
-            # Keyring missing/unavailable: ignore to allow prompt (workstations)
-            # or to fail cleanly below (headless CI without prompt).
+            # Unknown keyring errors: do not block prompting; still avoid hard crash.
             pass
 
         # 3) Prompt (optional)
@@ -59,6 +82,8 @@ class TokenResolver:
                 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

src/pkgmgr/core/git/__init__.py

@@ -1,5 +1,4 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
+from __future__ import annotations
 
 """
 Lightweight helper functions around Git commands.
@@ -9,84 +8,10 @@ logic (release, version, changelog) does not have to deal with the
 details of subprocess handling.
 """
 
-from __future__ import annotations
+from .errors import GitError
+from .run import run
 
-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,42 @@
+from __future__ import annotations
+
+from .checkout import GitCheckoutError, checkout
+from .delete_local_branch import GitDeleteLocalBranchError, delete_local_branch
+from .delete_remote_branch import GitDeleteRemoteBranchError, delete_remote_branch
+from .fetch import GitFetchError, fetch
+from .merge_no_ff import GitMergeError, merge_no_ff
+from .pull import GitPullError, pull
+from .push import GitPushError, push
+from .create_branch import GitCreateBranchError, create_branch
+from .push_upstream import GitPushUpstreamError, push_upstream
+
+from .add_remote import GitAddRemoteError, add_remote
+from .set_remote_url import GitSetRemoteUrlError, set_remote_url
+from .add_remote_push_url import GitAddRemotePushUrlError, add_remote_push_url
+
+__all__ = [
+    "fetch",
+    "checkout",
+    "pull",
+    "merge_no_ff",
+    "push",
+    "delete_local_branch",
+    "delete_remote_branch",
+    "create_branch",
+    "push_upstream",
+    "add_remote",
+    "set_remote_url",
+    "add_remote_push_url",
+    "GitFetchError",
+    "GitCheckoutError",
+    "GitPullError",
+    "GitMergeError",
+    "GitPushError",
+    "GitDeleteLocalBranchError",
+    "GitDeleteRemoteBranchError",
+    "GitCreateBranchError",
+    "GitPushUpstreamError",
+    "GitAddRemoteError",
+    "GitSetRemoteUrlError",
+    "GitAddRemotePushUrlError",
+]

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/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/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,18 @@
+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", cwd: str = ".") -> None:
+    try:
+        run(["fetch", remote], cwd=cwd)
+    except GitError as exc:
+        raise GitFetchError(
+            f"Failed to fetch from remote {remote!r}.",
+            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/push.py

@@ -0,0 +1,18 @@
+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, cwd: str = ".") -> None:
+    try:
+        run(["push", remote, ref], cwd=cwd)
+    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,23 @@
+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 = ".") -> None:
+    """
+    Push a branch and set upstream tracking.
+
+    Equivalent to: git push -u <remote> <branch>
+    """
+    try:
+        run(["push", "-u", remote, branch], cwd=cwd)
+    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/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,26 @@
+from __future__ import annotations
+
+from .get_current_branch import get_current_branch
+from .get_head_commit import get_head_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
+
+__all__ = [
+    "get_current_branch",
+    "get_head_commit",
+    "get_tags",
+    "resolve_base_branch",
+    "GitBaseBranchNotFoundError",
+    "list_remotes",
+    "get_remote_push_urls",
+    "probe_remote_reachable",
+    "get_changelog",
+    "GitChangelogQueryError",
+    "get_tags_at_ref",
+    "GitTagsAtRefQueryError",
+]

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_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_remote_push_urls.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from typing import Set
+
+from ..errors import GitError
+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_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/list_remotes.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from typing import List
+
+from ..errors import GitError
+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/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()

src/pkgmgr/core/remote_provisioning/ensure.py

@@ -64,10 +64,12 @@ def ensure_remote_repo(
     provider = reg.resolve(spec.host)
     if provider_hint and provider_hint.kind:
         forced = provider_hint.kind.strip().lower()
-        provider = next(
+        forced_provider = next(
             (p for p in reg.providers if getattr(p, "kind", "").lower() == forced),
             None,
         )
+        if forced_provider is not None:
+            provider = forced_provider
 
     if provider is None:
         raise UnsupportedProviderError(f"No provider matched host: {spec.host}")

src/pkgmgr/core/repository/paths.py

@@ -0,0 +1,124 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+Central repository path resolver.
+
+Goal:
+- Provide ONE place to define where packaging / changelog / metadata files live.
+- Prefer modern layout (packaging/*) but stay backwards-compatible with legacy
+  root-level paths.
+
+Both:
+- readers (pkgmgr.core.version.source)
+- writers (pkgmgr.actions.release.workflow)
+
+should use this module instead of hardcoding paths.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Iterable, Optional
+
+
+@dataclass(frozen=True)
+class RepoPaths:
+    repo_dir: str
+
+    pyproject_toml: str
+    flake_nix: str
+
+    # Human changelog (typically Markdown)
+    changelog_md: Optional[str]
+
+    # Packaging-related files
+    arch_pkgbuild: Optional[str]
+    debian_changelog: Optional[str]
+    rpm_spec: Optional[str]
+
+
+def _first_existing(candidates: Iterable[str]) -> Optional[str]:
+    for p in candidates:
+        if p and os.path.isfile(p):
+            return p
+    return None
+
+
+def _find_first_spec_in_dir(dir_path: str) -> Optional[str]:
+    if not os.path.isdir(dir_path):
+        return None
+    try:
+        for fn in sorted(os.listdir(dir_path)):
+            if fn.endswith(".spec"):
+                p = os.path.join(dir_path, fn)
+                if os.path.isfile(p):
+                    return p
+    except OSError:
+        return None
+    return None
+
+
+def resolve_repo_paths(repo_dir: str) -> RepoPaths:
+    """
+    Resolve canonical file locations for a repository.
+
+    Preferences (new layout first, legacy fallback second):
+      - PKGBUILD:            packaging/arch/PKGBUILD  -> PKGBUILD
+      - Debian changelog:    packaging/debian/changelog -> debian/changelog
+      - RPM spec:            packaging/fedora/package-manager.spec
+                             -> first *.spec in packaging/fedora
+                             -> first *.spec in repo root
+      - CHANGELOG.md:        CHANGELOG.md -> packaging/CHANGELOG.md (optional fallback)
+
+    Notes:
+      - This resolver only returns paths; it does not read/parse files.
+      - Callers should treat Optional paths as "may not exist".
+    """
+    repo_dir = os.path.abspath(repo_dir)
+
+    pyproject_toml = os.path.join(repo_dir, "pyproject.toml")
+    flake_nix = os.path.join(repo_dir, "flake.nix")
+
+    changelog_md = _first_existing(
+        [
+            os.path.join(repo_dir, "CHANGELOG.md"),
+            os.path.join(repo_dir, "packaging", "CHANGELOG.md"),
+        ]
+    )
+
+    arch_pkgbuild = _first_existing(
+        [
+            os.path.join(repo_dir, "packaging", "arch", "PKGBUILD"),
+            os.path.join(repo_dir, "PKGBUILD"),
+        ]
+    )
+
+    debian_changelog = _first_existing(
+        [
+            os.path.join(repo_dir, "packaging", "debian", "changelog"),
+            os.path.join(repo_dir, "debian", "changelog"),
+        ]
+    )
+
+    # RPM spec: prefer the canonical file, else first spec in packaging/fedora, else first spec in repo root.
+    rpm_spec = _first_existing(
+        [
+            os.path.join(repo_dir, "packaging", "fedora", "package-manager.spec"),
+        ]
+    )
+    if rpm_spec is None:
+        rpm_spec = _find_first_spec_in_dir(os.path.join(repo_dir, "packaging", "fedora"))
+    if rpm_spec is None:
+        rpm_spec = _find_first_spec_in_dir(repo_dir)
+
+    return RepoPaths(
+        repo_dir=repo_dir,
+        pyproject_toml=pyproject_toml,
+        flake_nix=flake_nix,
+        changelog_md=changelog_md,
+        arch_pkgbuild=arch_pkgbuild,
+        debian_changelog=debian_changelog,
+        rpm_spec=rpm_spec,
+    )

src/pkgmgr/core/version/installed.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import subprocess
+from dataclasses import dataclass
+from typing import Iterable, Optional, Tuple
+
+
+@dataclass(frozen=True)
+class InstalledVersion:
+    """
+    Represents a resolved installed version and the matched name.
+    """
+    name: str
+    version: str
+
+
+def _normalize(name: str) -> str:
+    return re.sub(r"[-_.]+", "-", (name or "").strip()).lower()
+
+
+def _unique_candidates(names: Iterable[str]) -> list[str]:
+    seen: set[str] = set()
+    out: list[str] = []
+    for n in names:
+        if not n:
+            continue
+        key = _normalize(n)
+        if key in seen:
+            continue
+        seen.add(key)
+        out.append(n)
+    return out
+
+
+def get_installed_python_version(*candidates: str) -> Optional[InstalledVersion]:
+    """
+    Detect installed Python package version in the CURRENT Python environment.
+
+    Strategy:
+      1) Exact normalized match using importlib.metadata.version()
+      2) Substring fallback by scanning installed distributions
+    """
+    try:
+        from importlib import metadata as importlib_metadata
+    except Exception:
+        return None
+
+    candidates = _unique_candidates(candidates)
+
+    expanded: list[str] = []
+    for c in candidates:
+        n = _normalize(c)
+        expanded.extend([c, n, n.replace("-", "_"), n.replace("-", ".")])
+    expanded = _unique_candidates(expanded)
+
+    # 1) Direct queries first (fast path)
+    for name in expanded:
+        try:
+            version = importlib_metadata.version(name)
+            return InstalledVersion(name=name, version=version)
+        except Exception:
+            continue
+
+    # 2) Fallback: scan distributions (last resort)
+    try:
+        dists = importlib_metadata.distributions()
+    except Exception:
+        return None
+
+    norm_candidates = {_normalize(c) for c in candidates}
+
+    for dist in dists:
+        dist_name = dist.metadata.get("Name", "") or ""
+        norm_dist = _normalize(dist_name)
+        for c in norm_candidates:
+            if c and (c in norm_dist or norm_dist in c):
+                ver = getattr(dist, "version", None)
+                if ver:
+                    return InstalledVersion(name=dist_name, version=ver)
+
+    return None
+
+
+def _run_nix(args: list[str]) -> Tuple[int, str, str]:
+    p = subprocess.run(
+        args,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        check=False,
+    )
+    return p.returncode, p.stdout or "", p.stderr or ""
+
+
+def _extract_version_from_store_path(path: str) -> Optional[str]:
+    if not path:
+        return None
+    base = path.rstrip("/").split("/")[-1]
+    if "-" not in base:
+        return None
+    tail = base.split("-")[-1]
+    if re.match(r"\d+(\.\d+){0,3}([a-z0-9+._-]*)?$", tail, re.I):
+        return tail
+    return None
+
+
+def get_installed_nix_profile_version(*candidates: str) -> Optional[InstalledVersion]:
+    """
+    Detect installed version from the current Nix profile.
+
+    Strategy:
+      1) JSON output (exact normalized match)
+      2) Text fallback (substring)
+    """
+    if shutil.which("nix") is None:
+        return None
+
+    candidates = _unique_candidates(candidates)
+    if not candidates:
+        return None
+
+    norm_candidates = {_normalize(c) for c in candidates}
+
+    # Preferred: JSON output
+    rc, out, _ = _run_nix(["nix", "profile", "list", "--json"])
+    if rc == 0 and out.strip():
+        try:
+            data = json.loads(out)
+            elements = data.get("elements") or data.get("items") or {}
+            if isinstance(elements, dict):
+                for elem in elements.values():
+                    if not isinstance(elem, dict):
+                        continue
+                    name = (elem.get("name") or elem.get("pname") or "").strip()
+                    version = (elem.get("version") or "").strip()
+                    norm_name = _normalize(name)
+
+                    if norm_name in norm_candidates:
+                        if version:
+                            return InstalledVersion(name=name, version=version)
+                        for sp in elem.get("storePaths", []) or []:
+                            guess = _extract_version_from_store_path(sp)
+                            if guess:
+                                return InstalledVersion(name=name, version=guess)
+        except Exception:
+            pass
+
+    # Fallback: text mode
+    rc, out, _ = _run_nix(["nix", "profile", "list"])
+    if rc != 0:
+        return None
+
+    for line in out.splitlines():
+        norm_line = _normalize(line)
+        for c in norm_candidates:
+            if c in norm_line:
+                m = re.search(r"\b\d+(\.\d+){0,3}[a-z0-9+._-]*\b", line, re.I)
+                if m:
+                    return InstalledVersion(name=c, version=m.group(0))
+                if "/nix/store/" in line:
+                    guess = _extract_version_from_store_path(line.split()[-1])
+                    if guess:
+                        return InstalledVersion(name=c, version=guess)
+
+    return None

src/pkgmgr/core/version/source.py

@@ -1,21 +1,4 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-
-"""
-Helpers to extract version information from various packaging files.
-
-All functions take a repository directory and return either a version
-string or None if the corresponding file or version field is missing.
-
-Supported sources:
-- pyproject.toml   (PEP 621, [project].version)
-- flake.nix        (version = "X.Y.Z";)
-- PKGBUILD         (pkgver / pkgrel)
-- debian/changelog (first entry line: package (version) ...)
-- RPM spec file    (package-manager.spec: Version / Release)
-- Ansible Galaxy   (galaxy.yml or meta/main.yml)
-"""
-
+# src/pkgmgr/core/version/source.py
 from __future__ import annotations
 
 import os
@@ -24,52 +7,72 @@ from typing import Optional
 
 import yaml
 
+from pkgmgr.core.repository.paths import resolve_repo_paths
+
 
 def read_pyproject_version(repo_dir: str) -> Optional[str]:
     """
     Read the version from pyproject.toml in repo_dir, if present.
 
     Expects a PEP 621-style [project] table with a 'version' field.
-    Returns the version string or None.
     """
-    path = os.path.join(repo_dir, "pyproject.toml")
-    if not os.path.exists(path):
+    paths = resolve_repo_paths(repo_dir)
+    path = paths.pyproject_toml
+    if not os.path.isfile(path):
         return None
 
     try:
-        try:
-            import tomllib  # Python 3.11+
-        except ModuleNotFoundError:  # pragma: no cover
-            tomllib = None
-
-        if tomllib is None:
-            return None
+        import tomllib  # Python 3.11+
+    except Exception:
+        import tomli as tomllib  # type: ignore
 
+    try:
         with open(path, "rb") as f:
             data = tomllib.load(f)
-
-        project = data.get("project", {})
-        if isinstance(project, dict):
-            version = project.get("version")
-            if isinstance(version, str):
-                return version.strip() or None
+        project = data.get("project") or {}
+        version = project.get("version")
+        return str(version).strip() if version else None
     except Exception:
-        # Intentionally swallow errors and fall back to None.
         return None
 
-    return None
+
+def read_pyproject_project_name(repo_dir: str) -> Optional[str]:
+    """
+    Read distribution name from pyproject.toml ([project].name).
+
+    This is required to correctly resolve installed Python package
+    versions via importlib.metadata.
+    """
+    paths = resolve_repo_paths(repo_dir)
+    path = paths.pyproject_toml
+    if not os.path.isfile(path):
+        return None
+
+    try:
+        import tomllib  # Python 3.11+
+    except Exception:
+        import tomli as tomllib  # type: ignore
+
+    try:
+        with open(path, "rb") as f:
+            data = tomllib.load(f)
+        project = data.get("project") or {}
+        name = project.get("name")
+        return str(name).strip() if name else None
+    except Exception:
+        return None
 
 
 def read_flake_version(repo_dir: str) -> Optional[str]:
     """
     Read the version from flake.nix in repo_dir, if present.
 
-    Looks for a line like:
-        version = "1.2.3";
-    and returns the string inside the quotes.
+    Looks for:
+        version = "X.Y.Z";
     """
-    path = os.path.join(repo_dir, "flake.nix")
-    if not os.path.exists(path):
+    paths = resolve_repo_paths(repo_dir)
+    path = paths.flake_nix
+    if not os.path.isfile(path):
         return None
 
     try:
@@ -81,22 +84,22 @@ def read_flake_version(repo_dir: str) -> Optional[str]:
     match = re.search(r'version\s*=\s*"([^"]+)"', text)
     if not match:
         return None
-    version = match.group(1).strip()
-    return version or None
+
+    return match.group(1).strip() or None
 
 
 def read_pkgbuild_version(repo_dir: str) -> Optional[str]:
     """
-    Read the version from PKGBUILD in repo_dir, if present.
+    Read the version from PKGBUILD (preferring packaging/arch/PKGBUILD).
 
-    Expects:
-        pkgver=1.2.3
-        pkgrel=1
-
-    Returns either "1.2.3-1" (if both are present) or just "1.2.3".
+    Combines pkgver and pkgrel if both exist:
+      pkgver=1.2.3
+      pkgrel=1
+    -> 1.2.3-1
     """
-    path = os.path.join(repo_dir, "PKGBUILD")
-    if not os.path.exists(path):
+    paths = resolve_repo_paths(repo_dir)
+    path = paths.arch_pkgbuild
+    if not path or not os.path.isfile(path):
         return None
 
     try:
@@ -121,15 +124,19 @@ def read_pkgbuild_version(repo_dir: str) -> Optional[str]:
 
 def read_debian_changelog_version(repo_dir: str) -> Optional[str]:
     """
-    Read the latest Debian version from debian/changelog in repo_dir, if present.
+    Read the latest version from debian changelog.
 
-    The first non-empty line typically looks like:
-        package-name (1.2.3-1) unstable; urgency=medium
+    Preferred path:
+      packaging/debian/changelog
+    Fallback:
+      debian/changelog
 
-    We extract the text inside the first parentheses.
+    Expected format:
+      package (1.2.3-1) unstable; urgency=medium
     """
-    path = os.path.join(repo_dir, "debian", "changelog")
-    if not os.path.exists(path):
+    paths = resolve_repo_paths(repo_dir)
+    path = paths.debian_changelog
+    if not path or not os.path.isfile(path):
         return None
 
     try:
@@ -140,8 +147,7 @@ def read_debian_changelog_version(repo_dir: str) -> Optional[str]:
                     continue
                 match = re.search(r"\(([^)]+)\)", line)
                 if match:
-                    version = match.group(1).strip()
-                    return version or None
+                    return match.group(1).strip() or None
                 break
     except Exception:
         return None
@@ -151,19 +157,21 @@ def read_debian_changelog_version(repo_dir: str) -> Optional[str]:
 
 def read_spec_version(repo_dir: str) -> Optional[str]:
     """
-    Read the version from a RPM spec file.
+    Read the version from an RPM spec file.
 
-    For now, we assume a fixed file name 'package-manager.spec'
-    in repo_dir with lines like:
+    Preferred paths:
+      packaging/fedora/package-manager.spec
+      packaging/fedora/*.spec
+      repo_root/*.spec
 
-        Version: 1.2.3
-        Release: 1%{?dist}
-
-    Returns either "1.2.3-1" (if Release is present) or "1.2.3".
-    Any RPM macro suffix like '%{?dist}' is stripped from the release.
+    Combines:
+      Version: 1.2.3
+      Release: 1%{?dist}
+    -> 1.2.3-1
     """
-    path = os.path.join(repo_dir, "package-manager.spec")
-    if not os.path.exists(path):
+    paths = resolve_repo_paths(repo_dir)
+    path = paths.rpm_spec
+    if not path or not os.path.isfile(path):
         return None
 
     try:
@@ -180,10 +188,7 @@ def read_spec_version(repo_dir: str) -> Optional[str]:
     rel_match = re.search(r"^Release:\s*(.+)$", text, re.MULTILINE)
     if rel_match:
         release_raw = rel_match.group(1).strip()
-        # Strip common RPM macro suffix like %... (e.g. 1%{?dist})
-        release = release_raw.split("%", 1)[0].strip()
-        # Also strip anything after first whitespace, just in case
-        release = release.split(" ", 1)[0].strip()
+        release = release_raw.split("%", 1)[0].split(" ", 1)[0].strip()
         if release:
             return f"{version}-{release}"
 
@@ -192,40 +197,35 @@ def read_spec_version(repo_dir: str) -> Optional[str]:
 
 def read_ansible_galaxy_version(repo_dir: str) -> Optional[str]:
     """
-    Read the version from Ansible Galaxy metadata, if present.
+    Read the version from Ansible Galaxy metadata.
 
-    Supported locations:
-    - galaxy.yml  (preferred for modern roles/collections)
-    - meta/main.yml (legacy style roles; uses galaxy_info.version or version)
+    Supported:
+      - galaxy.yml
+      - meta/main.yml (galaxy_info.version or version)
     """
-    # 1) galaxy.yml in repo root
-    galaxy_path = os.path.join(repo_dir, "galaxy.yml")
-    if os.path.exists(galaxy_path):
+    galaxy_yml = os.path.join(repo_dir, "galaxy.yml")
+    if os.path.isfile(galaxy_yml):
         try:
-            with open(galaxy_path, "r", encoding="utf-8") as f:
+            with open(galaxy_yml, "r", encoding="utf-8") as f:
                 data = yaml.safe_load(f) or {}
             version = data.get("version")
             if isinstance(version, str) and version.strip():
                 return version.strip()
         except Exception:
-            # Ignore parse errors and fall through to meta/main.yml
             pass
 
-    # 2) meta/main.yml (classic Ansible role)
-    meta_path = os.path.join(repo_dir, "meta", "main.yml")
-    if os.path.exists(meta_path):
+    meta_yml = os.path.join(repo_dir, "meta", "main.yml")
+    if os.path.isfile(meta_yml):
         try:
-            with open(meta_path, "r", encoding="utf-8") as f:
+            with open(meta_yml, "r", encoding="utf-8") as f:
                 data = yaml.safe_load(f) or {}
 
-            # Preferred: galaxy_info.version
             galaxy_info = data.get("galaxy_info") or {}
             if isinstance(galaxy_info, dict):
                 version = galaxy_info.get("version")
                 if isinstance(version, str) and version.strip():
                     return version.strip()
 
-            # Fallback: top-level 'version'
             version = data.get("version")
             if isinstance(version, str) and version.strip():
                 return version.strip()

templates/default/.gitignore.j2

@@ -0,0 +1,5 @@
+.venv/
+dist/
+build/
+__pycache__/
+*.pyc

templates/default/LICENSE.j2

@@ -0,0 +1 @@
+{{ license_text }}

templates/default/README.md.j2

@@ -0,0 +1,6 @@
+# {{ repository }}
+
+Homepage: {{ homepage }}
+
+## Author
+{{ author_name }} <{{ author_email }}>