Release version 1.8.3

- Allow MIRRORS to contain plain URLs (one per line) in addition to legacy "NAME URL"
- Treat strings as single URLs to avoid iterable pitfalls
- Write PyPI URLs as metadata-only entries (never added to git config)
- Keep MIRRORS as the single source of truth for mirror setup
- Update integration test to assert URL-only MIRRORS output

https://chatgpt.com/share/6941a9aa-b8b4-800f-963d-2486b34856b1

.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 }}" \

.github/workflows/test-e2e.yml

@@ -22,4 +22,4 @@ jobs:
       - name: Run E2E tests via make (${{ matrix.distro }})
         run: |
           set -euo pipefail
-          distro="${{ matrix.distro }}" make test-e2e
+          PKGMGR_DISTRO="${{ matrix.distro }}" make test-e2e

.github/workflows/test-env-nix.yml

@@ -23,4 +23,4 @@ jobs:
       - name: Nix flake-only test (${{ matrix.distro }})
         run: |
           set -euo pipefail
-          distro="${{ matrix.distro }}" make test-env-nix
+          PKGMGR_DISTRO="${{ matrix.distro }}" make test-env-nix

.github/workflows/test-env-virtual.yml

@@ -25,4 +25,4 @@ jobs:
       - name: Run container tests (${{ matrix.distro }})
         run: |
           set -euo pipefail
-          distro="${{ matrix.distro }}" make test-env-virtual
+          PKGMGR_DISTRO="${{ matrix.distro }}" make test-env-virtual

.github/workflows/test-integration.yml

@@ -16,4 +16,4 @@ jobs:
         run: docker version
 
       - name: Run integration tests via make (Arch container)
-        run: make test-integration distro="arch"
+        run: make test-integration PKGMGR_DISTRO="arch"

.github/workflows/test-unit.yml

@@ -16,4 +16,4 @@ jobs:
         run: docker version
 
       - name: Run unit tests via make (Arch container)
-        run: make test-unit distro="arch"
+        run: make test-unit PKGMGR_DISTRO="arch"

.github/workflows/test-virgin-root.yml

@@ -23,7 +23,7 @@ jobs:
       - name: Build virgin container (${{ matrix.distro }})
         run: |
           set -euo pipefail
-          distro="${{ matrix.distro }}" make build-missing-virgin
+          PKGMGR_DISTRO="${{ matrix.distro }}" make build-missing-virgin
 
       # 🔹 RUN test inside virgin image
       - name: Virgin ${{ matrix.distro }} pkgmgr test (root)
@@ -46,8 +46,6 @@ jobs:
 
               . "$HOME/.venvs/pkgmgr/bin/activate"
 
-              export NIX_CONFIG="experimental-features = nix-command flakes"
-
               pkgmgr update pkgmgr --clone-mode shallow --no-verification
               pkgmgr version pkgmgr
 

.github/workflows/test-virgin-user.yml

@@ -23,7 +23,7 @@ jobs:
       - name: Build virgin container (${{ matrix.distro }})
         run: |
           set -euo pipefail
-          distro="${{ matrix.distro }}" make build-missing-virgin
+          PKGMGR_DISTRO="${{ matrix.distro }}" make build-missing-virgin
 
       # 🔹 RUN test inside virgin image as non-root
       - name: Virgin ${{ matrix.distro }} pkgmgr test (user)
@@ -59,7 +59,6 @@ jobs:
                 pkgmgr version pkgmgr
 
                 export NIX_REMOTE=local
-                export NIX_CONFIG=\"experimental-features = nix-command flakes\"
                 nix run /src#pkgmgr -- version pkgmgr
               "
             '

CHANGELOG.md

@@ -1,3 +1,110 @@
+## [1.8.3] - 2025-12-16
+
+* MIRRORS now supports plain URL entries, ensuring metadata-only sources like PyPI are recorded without ever being added to the Git configuration.
+
+
+## [1.8.2] - 2025-12-16
+
+* * ***pkgmgr tools code*** is more robust and predictable: it now fails early with clear errors if VS Code is not installed or a repository is not yet identified.
+
+
+## [1.8.1] - 2025-12-16
+
+* * Improved stability and consistency of all Git operations (clone, pull, push, release, branch handling) with clearer error messages and predictable preview behavior.
+* Mirrors are now handled cleanly: only valid Git remotes are used for Git operations, while non-Git URLs (e.g. PyPI) are excluded, preventing broken or confusing repository configs.
+* GitHub authentication is more robust: tokens are automatically resolved via the GitHub CLI (`gh`), invalid stored tokens are replaced, and interactive prompts occur only when necessary.
+* Repository creation and release workflows are more reliable, producing cleaner Git configurations and more predictable version handling.
+
+
+## [1.8.0] - 2025-12-15
+
+* *** New Features: ***
+- **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).
+
+
+## [1.6.0] - 2025-12-14
+
+* *** Changed ***
+- Unified update handling via a single top-level `pkgmgr update` command, removing ambiguous update paths.
+- Improved update reliability by routing all update logic through a central UpdateManager.
+- Renamed system update flag from `--system-update` to `--system` for clarity and consistency.
+- Made mirror handling explicit and safer by separating setup, check, and provision responsibilities.
+- Improved credential resolution for remote providers (environment → keyring → interactive).
+
+*** Added ***
+- Optional system updates via `pkgmgr update --system` (Arch, Debian/Ubuntu, Fedora/RHEL).
+- `pkgmgr install --update` to force re-running installers and refresh existing installations.
+- Remote repository provisioning for mirrors on supported providers.
+- Extended end-to-end test coverage for update and mirror workflows.
+
+*** Fixed ***
+- Resolved “Unknown repos command: update” errors after CLI refactoring.
+- Improved Nix update stability and reduced CI failures caused by transient rate limits.
+
+
+## [1.5.0] - 2025-12-13
+
+* - Commands now show live output while running, making long operations easier to follow
+- Error messages include full command output, making failures easier to understand and debug
+- Deinstallation is more complete and predictable, removing CLI links and properly cleaning up repositories
+- Preview mode is more trustworthy, clearly showing what would happen without making changes
+- Repository configuration problems are detected earlier with clear, user-friendly explanations
+- More consistent behavior across different Linux distributions
+- More reliable execution in Docker containers and CI environments
+- Nix-based execution works more smoothly, especially when running as root or inside containers
+- Existing commands, scripts, and workflows continue to work without any breaking changes
+
+
 ## [1.4.1] - 2025-12-12
 
 * Fixed stable release container publishing

Dockerfile

@@ -36,9 +36,6 @@ CMD ["bash"]
 # ============================================================
 FROM virgin AS full
 
-# Nix environment defaults (only config; nix itself comes from deps/install flow)
-ENV NIX_CONFIG="experimental-features = nix-command flakes"
-
 WORKDIR /build
 
 # Copy full repository for build

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

@@ -7,8 +7,8 @@
 # Distro
 # Options: arch debian ubuntu fedora centos
 DISTROS ?= arch debian ubuntu fedora centos
-distro ?= arch
-export distro
+PKGMGR_DISTRO ?= arch
+export PKGMGR_DISTRO
 
 # ------------------------------------------------------------
 # Base images
@@ -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
@@ -75,7 +75,7 @@ build-no-cache-all:
 	@set -e; \
 	for d in $(DISTROS); do \
 	  echo "=== build-no-cache: $$d ==="; \
-	  distro="$$d" $(MAKE) build-no-cache; \
+	  PKGMGR_DISTRO="$$d" $(MAKE) build-no-cache; \
 	done
 
 # ------------------------------------------------------------
@@ -101,7 +101,7 @@ test-env-nix: build-missing
 test: test-env-virtual test-unit test-integration test-e2e
 
 delete-volumes: 
-	@docker volume rm pkgmgr_nix_store_${distro} pkgmgr_nix_cache_${distro} || true
+	@docker volume rm "pkgmgr_nix_store_${PKGMGR_DISTRO}" "pkgmgr_nix_cache_${PKGMGR_DISTRO}" || echo "No volumes to delete."
 
 purge: delete-volumes build-no-cache
 

flake.nix

@@ -26,17 +26,13 @@
       packages = forAllSystems (system:
         let
           pkgs = nixpkgs.legacyPackages.${system};
-
-          # Single source of truth for pkgmgr: Python 3.11
-          # - Matches pyproject.toml: requires-python = ">=3.11"
-          # - Uses python311Packages so that PyYAML etc. are available
           python = pkgs.python311;
           pyPkgs = pkgs.python311Packages;
         in
         rec {
           pkgmgr = pyPkgs.buildPythonApplication {
             pname   = "package-manager";
-            version = "1.4.1";
+            version = "1.8.3";
 
             # Use the git repo as source
             src = ./.;
@@ -53,6 +49,7 @@
             # Runtime dependencies (matches [project.dependencies] in pyproject.toml)
             propagatedBuildInputs = [
               pyPkgs.pyyaml
+              pyPkgs.jinja2
               pyPkgs.pip
             ];
 
@@ -82,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.3
 pkgrel=1
 pkgdesc="Local-flake wrapper for Kevin's package-manager (Nix-based)."
 arch=('any')
@@ -47,7 +47,7 @@ package() {
   cd "$srcdir/$_srcdir_name"
 
   # Install the wrapper into /usr/bin
-  install -Dm0755 "scripts/pkgmgr-wrapper.sh" \
+  install -Dm0755 "scripts/launcher.sh" \
     "$pkgdir/usr/bin/pkgmgr"
 
   # Install Nix bootstrap (init + lib)

packaging/debian/changelog

@@ -1,3 +1,76 @@
+package-manager (1.8.3-1) unstable; urgency=medium
+
+  * MIRRORS now supports plain URL entries, ensuring metadata-only sources like PyPI are recorded without ever being added to the Git configuration.
+
+ -- Kevin Veen-Birkenbach <kevin@veen.world>  Tue, 16 Dec 2025 19:49:51 +0100
+
+package-manager (1.8.2-1) unstable; urgency=medium
+
+  * * ***pkgmgr tools code*** is more robust and predictable: it now fails early with clear errors if VS Code is not installed or a repository is not yet identified.
+
+ -- Kevin Veen-Birkenbach <kevin@veen.world>  Tue, 16 Dec 2025 19:22:41 +0100
+
+package-manager (1.8.1-1) unstable; urgency=medium
+
+  * * Improved stability and consistency of all Git operations (clone, pull, push, release, branch handling) with clearer error messages and predictable preview behavior.
+* Mirrors are now handled cleanly: only valid Git remotes are used for Git operations, while non-Git URLs (e.g. PyPI) are excluded, preventing broken or confusing repository configs.
+* GitHub authentication is more robust: tokens are automatically resolved via the GitHub CLI (`gh`), invalid stored tokens are replaced, and interactive prompts occur only when necessary.
+* Repository creation and release workflows are more reliable, producing cleaner Git configurations and more predictable version handling.
+
+ -- Kevin Veen-Birkenbach <kevin@veen.world>  Tue, 16 Dec 2025 18:06:35 +0100
+
+package-manager (1.8.0-1) unstable; urgency=medium
+
+  * *** New Features: ***
+- **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/debian/rules

@@ -28,7 +28,7 @@ override_dh_auto_install:
 	install -d debian/package-manager/usr/lib/package-manager
 
 	# Install wrapper
-	install -m0755 scripts/pkgmgr-wrapper.sh \
+	install -m0755 scripts/launcher.sh \
 		debian/package-manager/usr/bin/pkgmgr
 
 	# Install Nix bootstrap (init + lib)

packaging/fedora/package-manager.spec

@@ -1,5 +1,5 @@
 Name:           package-manager
-Version:        0.9.1
+Version:        1.8.3
 Release:        1%{?dist}
 Summary:        Wrapper that runs Kevin's package-manager via Nix flake
 
@@ -42,7 +42,7 @@ install -d %{buildroot}/usr/lib/package-manager
 cp -a . %{buildroot}/usr/lib/package-manager/
 
 # Wrapper
-install -m0755 scripts/pkgmgr-wrapper.sh %{buildroot}%{_bindir}/pkgmgr
+install -m0755 scripts/launcher.sh %{buildroot}%{_bindir}/pkgmgr
 
 # Nix bootstrap (init + lib)
 install -d %{buildroot}/usr/lib/package-manager/nix
@@ -74,6 +74,52 @@ echo ">>> package-manager removed. Nix itself was not removed."
 /usr/lib/package-manager/
 
 %changelog
+* Tue Dec 16 2025 Kevin Veen-Birkenbach <kevin@veen.world> - 1.8.3-1
+- MIRRORS now supports plain URL entries, ensuring metadata-only sources like PyPI are recorded without ever being added to the Git configuration.
+
+* Tue Dec 16 2025 Kevin Veen-Birkenbach <kevin@veen.world> - 1.8.2-1
+- * ***pkgmgr tools code*** is more robust and predictable: it now fails early with clear errors if VS Code is not installed or a repository is not yet identified.
+
+* Tue Dec 16 2025 Kevin Veen-Birkenbach <kevin@veen.world> - 1.8.1-1
+- * Improved stability and consistency of all Git operations (clone, pull, push, release, branch handling) with clearer error messages and predictable preview behavior.
+* Mirrors are now handled cleanly: only valid Git remotes are used for Git operations, while non-Git URLs (e.g. PyPI) are excluded, preventing broken or confusing repository configs.
+* GitHub authentication is more robust: tokens are automatically resolved via the GitHub CLI (`gh`), invalid stored tokens are replaced, and interactive prompts occur only when necessary.
+* Repository creation and release workflows are more reliable, producing cleaner Git configurations and more predictable version handling.
+
+* Mon Dec 15 2025 Kevin Veen-Birkenbach <kevin@veen.world> - 1.8.0-1
+- *** New Features: ***
+- **Silent Updates**: You can now use the `--silent` flag during installs and updates to suppress error messages for individual repositories and get a single summary at the end. This ensures the process continues even if some repositories fail, while still preserving interactive checks when not in silent mode.
+- **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.4.1"
+name = "kpmx"
+version = "1.8.3"
 description = "Kevin's package-manager tool (pkgmgr)"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -19,16 +19,18 @@ authors = [
 
 # Base runtime dependencies
 dependencies = [
-  "PyYAML>=6.0"
+  "PyYAML>=6.0",
+  "tomli; python_version < \"3.11\"",
+  "jinja2>=3.1"
 ]
 
 [project.urls]
-Homepage = "https://github.com/kevinveenbirkenbach/package-manager"
+Homepage = "https://s.veen.world/pkgmgr"
 Source   = "https://github.com/kevinveenbirkenbach/package-manager"
 
 [project.optional-dependencies]
+keyring = ["keyring>=24.0.0"]
 dev = [
-  "pytest",
   "mypy"
 ]
 

scripts/build/base.sh

@@ -8,13 +8,13 @@ set -euo pipefail
 : "${BASE_IMAGE_CENTOS:=quay.io/centos/centos:stream9}"
 
 resolve_base_image() {
-  local distro="$1"
-  case "$distro" in
+  local PKGMGR_DISTRO="$1"
+  case "$PKGMGR_DISTRO" in
     arch)   echo "$BASE_IMAGE_ARCH" ;;
     debian) echo "$BASE_IMAGE_DEBIAN" ;;
     ubuntu) echo "$BASE_IMAGE_UBUNTU" ;;
     fedora) echo "$BASE_IMAGE_FEDORA" ;;
     centos) echo "$BASE_IMAGE_CENTOS" ;;
-    *) echo "ERROR: Unknown distro '$distro'" >&2; exit 1 ;;
+    *) echo "ERROR: Unknown distro '$PKGMGR_DISTRO'" >&2; exit 1 ;;
   esac
 }

scripts/build/image.sh

@@ -2,9 +2,11 @@
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# shellcheck source=./scripts/build/base.sh
 source "${SCRIPT_DIR}/base.sh"
 
-: "${distro:?Environment variable 'distro' must be set (arch|debian|ubuntu|fedora|centos)}"
+: "${PKGMGR_DISTRO:?Environment variable 'PKGMGR_DISTRO' must be set (arch|debian|ubuntu|fedora|centos)}"
 
 NO_CACHE=0
 MISSING_ONLY=0
@@ -20,13 +22,13 @@ IS_STABLE="false"    # "true" -> publish stable tags
 DEFAULT_DISTRO="arch"
 
 usage() {
-  local default_tag="pkgmgr-${distro}"
+  local default_tag="pkgmgr-${PKGMGR_DISTRO}"
   if [[ -n "${TARGET:-}" ]]; then
     default_tag="${default_tag}-${TARGET}"
   fi
 
   cat <<EOF
-Usage: distro=<distro> $0 [options]
+Usage: PKGMGR_DISTRO=<distro> $0 [options]
 
 Build options:
   --missing             Build only if the image does not already exist (local build only)
@@ -101,13 +103,13 @@ done
 
 # Derive default local tag if not provided
 if [[ -z "${IMAGE_TAG}" ]]; then
-  IMAGE_TAG="${REPO_PREFIX}-${distro}"
+  IMAGE_TAG="${REPO_PREFIX}-${PKGMGR_DISTRO}"
   if [[ -n "${TARGET}" ]]; then
     IMAGE_TAG="${IMAGE_TAG}-${TARGET}"
   fi
 fi
 
-BASE_IMAGE="$(resolve_base_image "$distro")"
+BASE_IMAGE="$(resolve_base_image "$PKGMGR_DISTRO")"
 
 # Local-only "missing" shortcut
 if [[ "${MISSING_ONLY}" == "1" ]]; then
@@ -139,7 +141,7 @@ fi
 echo
 echo "------------------------------------------------------------"
 echo "[build] Building image"
-echo "distro     = ${distro}"
+echo "distro     = ${PKGMGR_DISTRO}"
 echo "BASE_IMAGE = ${BASE_IMAGE}"
 if [[ -n "${TARGET}" ]]; then echo "target    = ${TARGET}"; fi
 if [[ "${NO_CACHE}" == "1" ]]; then echo "cache     = disabled"; fi
@@ -165,14 +167,14 @@ if [[ -n "${TARGET}" ]]; then
 fi
 
 compute_publish_tags() {
-  local distro_tag_base="${REGISTRY}/${OWNER}/${REPO_PREFIX}-${distro}"
+  local distro_tag_base="${REGISTRY}/${OWNER}/${REPO_PREFIX}-${PKGMGR_DISTRO}"
   local alias_tag_base=""
 
   if [[ -n "${TARGET}" ]]; then
     distro_tag_base="${distro_tag_base}-${TARGET}"
   fi
 
-  if [[ "${distro}" == "${DEFAULT_DISTRO}" ]]; then
+  if [[ "${PKGMGR_DISTRO}" == "${DEFAULT_DISTRO}" ]]; then
     alias_tag_base="${REGISTRY}/${OWNER}/${REPO_PREFIX}"
     if [[ -n "${TARGET}" ]]; then
       alias_tag_base="${alias_tag_base}-${TARGET}"

scripts/build/publish.sh

@@ -30,11 +30,11 @@ echo "[publish] DISTROS=${DISTROS}"
 for d in ${DISTROS}; do
   echo
   echo "============================================================"
-  echo "[publish] distro=${d}"
+  echo "[publish] PKGMGR_DISTRO=${d}"
   echo "============================================================"
 
   # virgin
-  distro="${d}" bash "${SCRIPT_DIR}/image.sh" \
+  PKGMGR_DISTRO="${d}" bash "${SCRIPT_DIR}/image.sh" \
     --publish \
     --registry "${REGISTRY}" \
     --owner "${OWNER}" \
@@ -43,7 +43,7 @@ for d in ${DISTROS}; do
     --target virgin
 
   # full (default target)
-  distro="${d}" bash "${SCRIPT_DIR}/image.sh" \
+  PKGMGR_DISTRO="${d}" bash "${SCRIPT_DIR}/image.sh" \
     --publish \
     --registry "${REGISTRY}" \
     --owner "${OWNER}" \

scripts/docker/entry.sh

@@ -1,8 +1,6 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-
 echo "[docker] Starting package-manager container"
 
 # ---------------------------------------------------------------------------

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

@@ -1,12 +1,17 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-# Ensure NIX_CONFIG has our defaults if not already set
-if [[ -z "${NIX_CONFIG:-}" ]]; then
-  export NIX_CONFIG="experimental-features = nix-command flakes"
-fi
-
 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)
@@ -37,12 +42,16 @@ 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
 
-echo "[pkgmgr-wrapper] ERROR: 'nix' binary not found on PATH after init."
-echo "[pkgmgr-wrapper] Nix is required to run pkgmgr (no Python fallback)."
+echo "[launcher] ERROR: 'nix' binary not found on PATH after init."
+echo "[launcher] Nix is required to run pkgmgr (no Python fallback)."
 exit 1

scripts/nix/init.sh

@@ -1,22 +1,27 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-# shellcheck source=lib/bootstrap_config.sh
-# shellcheck source=lib/detect.sh
-# shellcheck source=lib/path.sh
-# shellcheck source=lib/symlinks.sh
-# shellcheck source=lib/users.sh
-# shellcheck source=lib/install.sh
-# shellcheck source=lib/nix_conf_file.sh
-
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
+# shellcheck source=./scripts/nix/lib/bootstrap_config.sh
 source "${SCRIPT_DIR}/lib/bootstrap_config.sh"
+
+# shellcheck source=./scripts/nix/lib/detect.sh
 source "${SCRIPT_DIR}/lib/detect.sh"
+
+# shellcheck source=./scripts/nix/lib/path.sh
 source "${SCRIPT_DIR}/lib/path.sh"
+
+# shellcheck source=./scripts/nix/lib/symlinks.sh
 source "${SCRIPT_DIR}/lib/symlinks.sh"
+
+# shellcheck source=./scripts/nix/lib/users.sh
 source "${SCRIPT_DIR}/lib/users.sh"
+
+# shellcheck source=./scripts/nix/lib/install.sh
 source "${SCRIPT_DIR}/lib/install.sh"
+
+# shellcheck source=./scripts/nix/lib/nix_conf_file.sh
 source "${SCRIPT_DIR}/lib/nix_conf_file.sh"
 
 echo "[init-nix] Starting Nix initialization..."

scripts/nix/lib/nix_conf_file.sh

@@ -11,45 +11,79 @@ nixconf_file_path() {
   echo "/etc/nix/nix.conf"
 }
 
-nixconf_ensure_experimental_features() {
-  local nix_conf want
-  nix_conf="$(nixconf_file_path)"
-  want="experimental-features = nix-command flakes"
+# Ensure a given nix.conf key contains required tokens (merged, no duplicates)
+nixconf_ensure_features_key() {
+  local nix_conf="$1"
+  local key="$2"
+  shift 2
+  local required=("$@")
 
   mkdir -p /etc/nix
 
+  # Create file if missing (with just the required tokens)
   if [[ ! -f "${nix_conf}" ]]; then
+    local want="${key} = ${required[*]}"
     echo "[nix-conf] Creating ${nix_conf} with: ${want}"
     printf "%s\n" "${want}" >"${nix_conf}"
     return 0
   fi
 
-  if grep -qE '^\s*experimental-features\s*=' "${nix_conf}"; then
-    if grep -qE '^\s*experimental-features\s*=.*\bnix-command\b' "${nix_conf}" \
-      && grep -qE '^\s*experimental-features\s*=.*\bflakes\b' "${nix_conf}"; then
-      echo "[nix-conf] experimental-features already correct"
+  # Key exists -> merge tokens
+  if grep -qE "^\s*${key}\s*=" "${nix_conf}"; then
+    local ok=1
+    local t
+    for t in "${required[@]}"; do
+      if ! grep -qE "^\s*${key}\s*=.*\b${t}\b" "${nix_conf}"; then
+        ok=0
+        break
+      fi
+    done
+
+    if [[ "$ok" -eq 1 ]]; then
+      echo "[nix-conf] ${key} already correct"
       return 0
     fi
 
-    echo "[nix-conf] Extending experimental-features in ${nix_conf}"
+    echo "[nix-conf] Extending ${key} in ${nix_conf}"
 
     local current
-    current="$(grep -E '^\s*experimental-features\s*=' "${nix_conf}" | head -n1 | cut -d= -f2-)"
+    current="$(grep -E "^\s*${key}\s*=" "${nix_conf}" | head -n1 | cut -d= -f2-)"
     current="$(echo "${current}" | xargs)" # trim
 
-    # Build a merged feature string without duplicates (simple token set)
-    local merged="nix-command flakes"
+    local merged=""
     local token
+
+    # Start with existing tokens
     for token in ${current}; do
       if [[ " ${merged} " != *" ${token} "* ]]; then
         merged="${merged} ${token}"
       fi
     done
 
-    sed -i "s|^\s*experimental-features\s*=.*|experimental-features = ${merged}|" "${nix_conf}"
+    # Add required tokens
+    for token in "${required[@]}"; do
+      if [[ " ${merged} " != *" ${token} "* ]]; then
+        merged="${merged} ${token}"
+      fi
+    done
+
+    merged="$(echo "${merged}" | xargs)" # trim
+
+    sed -i "s|^\s*${key}\s*=.*|${key} = ${merged}|" "${nix_conf}"
     return 0
   fi
 
+  # Key missing -> append
+  local want="${key} = ${required[*]}"
   echo "[nix-conf] Appending to ${nix_conf}: ${want}"
   printf "\n%s\n" "${want}" >>"${nix_conf}"
 }
+
+nixconf_ensure_experimental_features() {
+  local nix_conf
+  nix_conf="$(nixconf_file_path)"
+
+  # Ensure both keys to avoid prompts and cover older/alternate expectations
+  nixconf_ensure_features_key "${nix_conf}" "experimental-features" "nix-command" "flakes"
+  nixconf_ensure_features_key "${nix_conf}" "extra-experimental-features" "nix-command" "flakes"
+}

scripts/nix/lib/retry_403.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ -n "${PKGMGR_NIX_RETRY_403_SH:-}" ]]; then
+  return 0
+fi
+PKGMGR_NIX_RETRY_403_SH=1
+
+# Retry only when we see the GitHub API rate limit 403 error during nix flake evaluation.
+# Retries 7 times with delays: 10, 30, 50, 80, 130, 210, 420 seconds.
+run_with_github_403_retry() {
+  local -a delays=(10 30 50 80 130 210 420)
+  local attempt=0
+  local max_retries="${#delays[@]}"
+
+  while true; do
+    local err tmp
+    tmp="$(mktemp -t nix-err.XXXXXX)"
+    err=0
+
+    # Run the command; capture stderr for inspection while preserving stdout.
+    if "$@" 2>"$tmp"; then
+      rm -f "$tmp"
+      return 0
+    else
+      err=$?
+    fi
+
+    # Only retry on the specific GitHub API rate limit 403 case.
+    if grep -qE 'HTTP error 403' "$tmp" && grep -qiE 'API rate limit exceeded|api\.github\.com' "$tmp"; then
+      if (( attempt >= max_retries )); then
+        cat "$tmp" >&2
+        rm -f "$tmp"
+        return "$err"
+      fi
+
+      local sleep_s="${delays[$attempt]}"
+      attempt=$((attempt + 1))
+
+      echo "[nix-retry] GitHub API rate-limit (403). Retry ${attempt}/${max_retries} in ${sleep_s}s: $*" >&2
+      cat "$tmp" >&2
+      rm -f "$tmp"
+      sleep "$sleep_s"
+      continue
+    fi
+
+    # Not our retry case -> fail fast with original stderr.
+    cat "$tmp" >&2
+    rm -f "$tmp"
+    return "$err"
+  done
+}

scripts/setup/nix.sh

@@ -1,3 +1,5 @@
+#!/usr/bin/env bash
+
 # ------------------------------------------------------------
 # Nix shell mode: do not touch venv, only run install
 # ------------------------------------------------------------

scripts/setup/venv.sh

@@ -7,6 +7,7 @@ PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
 cd "${PROJECT_ROOT}"
 
 VENV_DIR="${HOME}/.venvs/pkgmgr"
+# shellcheck disable=SC2016
 RC_LINE='if [ -d "${HOME}/.venvs/pkgmgr" ]; then . "${HOME}/.venvs/pkgmgr/bin/activate"; if [ -n "${PS1:-}" ]; then echo "Global Python virtual environment '\''~/.venvs/pkgmgr'\'' activated."; fi; fi'
 
 # ------------------------------------------------------------

scripts/test/test-e2e.sh

@@ -2,17 +2,17 @@
 set -euo pipefail
 
 echo "============================================================"
-echo ">>> Running E2E tests: $distro"
+echo ">>> Running E2E tests: $PKGMGR_DISTRO"
 echo "============================================================"
 
 docker run --rm \
   -v "$(pwd):/src" \
-  -v "pkgmgr_nix_store_${distro}:/nix" \
-  -v "pkgmgr_nix_cache_${distro}:/root/.cache/nix" \
+  -v "pkgmgr_nix_store_${PKGMGR_DISTRO}:/nix" \
+  -v "pkgmgr_nix_cache_${PKGMGR_DISTRO}:/root/.cache/nix" \
   -e REINSTALL_PKGMGR=1 \
   -e TEST_PATTERN="${TEST_PATTERN}" \
   --workdir /src \
-  "pkgmgr-${distro}" \
+  "pkgmgr-${PKGMGR_DISTRO}" \
   bash -lc '
     set -euo pipefail
 
@@ -49,7 +49,7 @@ docker run --rm \
       # Gitdir path shown in the "dubious ownership" error
       git config --global --add safe.directory /src/.git || true
       # Ephemeral CI containers: allow all paths as a last resort
-      git config --global --add safe.directory '*' || true
+      git config --global --add safe.directory "*" || true
     fi
 
     # Run the E2E tests inside the Nix development shell

scripts/test/test-env-nix.sh

@@ -1,17 +1,17 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-IMAGE="pkgmgr-${distro}"
+IMAGE="pkgmgr-${PKGMGR_DISTRO}"
 
 echo "============================================================"
-echo ">>> Running Nix flake-only test in ${distro} container"
+echo ">>> Running Nix flake-only test in ${PKGMGR_DISTRO} container"
 echo ">>> Image: ${IMAGE}"
 echo "============================================================"
 
 docker run --rm \
   -v "$(pwd):/src" \
-  -v "pkgmgr_nix_store_${distro}:/nix" \
-  -v "pkgmgr_nix_cache_${distro}:/root/.cache/nix" \
+  -v "pkgmgr_nix_store_${PKGMGR_DISTRO}:/nix" \
+  -v "pkgmgr_nix_cache_${PKGMGR_DISTRO}:/root/.cache/nix" \
   --workdir /src \
   -e REINSTALL_PKGMGR=1 \
   "${IMAGE}" \
@@ -27,7 +27,7 @@ docker run --rm \
     echo ">>> preflight: nix must exist in image"
     if ! command -v nix >/dev/null 2>&1; then
       echo "NO_NIX"
-      echo "ERROR: nix not found in image '\'''"${IMAGE}"''\'' (distro='"${distro}"')"
+      echo "ERROR: nix not found in image '"${IMAGE}"' (PKGMGR_DISTRO='"${PKGMGR_DISTRO}"')"
       echo "HINT: Ensure Nix is installed during image build for this distro."
       exit 1
     fi
@@ -35,14 +35,28 @@ docker run --rm \
     echo ">>> nix version"
     nix --version
 
+    # ------------------------------------------------------------
+    # Retry helper for GitHub API rate-limit (HTTP 403)
+    # ------------------------------------------------------------
+    if [[ -f /src/scripts/nix/lib/retry_403.sh ]]; then
+      # shellcheck source=./scripts/nix/lib/retry_403.sh
+      source /src/scripts/nix/lib/retry_403.sh
+    elif [[ -f ./scripts/nix/lib/retry_403.sh ]]; then
+      # shellcheck source=./scripts/nix/lib/retry_403.sh
+      source ./scripts/nix/lib/retry_403.sh
+    else
+      echo "ERROR: retry helper not found: scripts/nix/lib/retry_403.sh"
+      exit 1
+    fi
+
     echo ">>> nix flake show"
-    nix flake show . --no-write-lock-file >/dev/null
+    run_with_github_403_retry nix flake show . --no-write-lock-file >/dev/null
 
     echo ">>> nix build .#default"
-    nix build .#default --no-link --no-write-lock-file
+    run_with_github_403_retry nix build .#default --no-link --no-write-lock-file
 
     echo ">>> nix run .#pkgmgr -- --help"
-    nix run .#pkgmgr -- --help --no-write-lock-file
+    run_with_github_403_retry nix run .#pkgmgr -- --help --no-write-lock-file
 
     echo ">>> OK: Nix flake-only test succeeded."
   '

scripts/test/test-env-virtual.sh

@@ -1,32 +1,49 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-IMAGE="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_${distro}:/nix \
-        -v "$(pwd):/src" \
-        -v "pkgmgr_nix_cache_${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

scripts/test/test-integration.sh

@@ -2,17 +2,17 @@
 set -euo pipefail
 
 echo "============================================================"
-echo ">>> Running INTEGRATION tests in ${distro} container"
+echo ">>> Running INTEGRATION tests in ${PKGMGR_DISTRO} container"
 echo "============================================================"
 
 docker run --rm \
   -v "$(pwd):/src" \
-  -v pkgmgr_nix_store_${distro}:/nix \
-  -v "pkgmgr_nix_cache_${distro}:/root/.cache/nix" \
+  -v "pkgmgr_nix_store_${PKGMGR_DISTRO}:/nix" \
+  -v "pkgmgr_nix_cache_${PKGMGR_DISTRO}:/root/.cache/nix" \
   --workdir /src \
   -e REINSTALL_PKGMGR=1 \
   -e TEST_PATTERN="${TEST_PATTERN}" \
-  "pkgmgr-${distro}" \
+  "pkgmgr-${PKGMGR_DISTRO}" \
   bash -lc '
     set -e;
     git config --global --add safe.directory /src || true;

scripts/test/test-unit.sh

@@ -2,17 +2,17 @@
 set -euo pipefail
 
 echo "============================================================"
-echo ">>> Running UNIT tests in ${distro} container"
+echo ">>> Running UNIT tests in ${PKGMGR_DISTRO} container"
 echo "============================================================"
 
 docker run --rm \
   -v "$(pwd):/src" \
-  -v "pkgmgr_nix_cache_${distro}:/root/.cache/nix" \
-  -v pkgmgr_nix_store_${distro}:/nix \
+  -v "pkgmgr_nix_cache_${PKGMGR_DISTRO}:/root/.cache/nix" \
+  -v "pkgmgr_nix_store_${PKGMGR_DISTRO}:/nix" \
   --workdir /src \
   -e REINSTALL_PKGMGR=1 \
   -e TEST_PATTERN="${TEST_PATTERN}" \
-  "pkgmgr-${distro}" \
+  "pkgmgr-${PKGMGR_DISTRO}" \
   bash -lc '
     set -e;
     git config --global --add safe.directory /src || true;

scripts/uninstall.sh

@@ -19,12 +19,20 @@ fi
 # ------------------------------------------------------------
 # Remove auto-activation lines from shell RC files
 # ------------------------------------------------------------
-RC_PATTERN='\.venvs\/pkgmgr\/bin\/activate"; if \[ -n "\$${PS1:-}" \]; then echo "Global Python virtual environment '\''~\/\.venvs\/pkgmgr'\'' activated."; fi; fi'
+# Matches:
+#   ~/.venvs/pkgmgr/bin/activate
+#   ./.venvs/pkgmgr/bin/activate
+RC_PATTERN='(\./)?\.venvs/pkgmgr/bin/activate'
 
 echo "[uninstall] Cleaning up ~/.bashrc and ~/.zshrc entries..."
 for rc in "$HOME/.bashrc" "$HOME/.zshrc"; do
     if [[ -f "$rc" ]]; then
-        sed -i "/$RC_PATTERN/d" "$rc"
+        # Remove activation lines (functional)
+        sed -E -i "/$RC_PATTERN/d" "$rc"
+
+        # Remove leftover echo / cosmetic lines referencing pkgmgr venv
+        sed -i '/\.venvs\/pkgmgr/d' "$rc"
+
         echo "[uninstall] Cleaned $rc"
     else
         echo "[uninstall] File not found: $rc (skipped)"

src/pkgmgr/actions/__init__.py

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

src/pkgmgr/actions/branch/close_branch.py

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

src/pkgmgr/actions/branch/drop_branch.py

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

src/pkgmgr/actions/branch/open_branch.py

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

src/pkgmgr/actions/branch/utils.py

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

src/pkgmgr/actions/changelog/__init__.py

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

src/pkgmgr/actions/config/add.py

@@ -1,5 +1,6 @@
 import yaml
 import os
+from pkgmgr.core.config.save import save_user_config 
 
 def interactive_add(config,USER_CONFIG_PATH:str):
     """Interactively prompt the user to add a new repository entry to the user config."""

src/pkgmgr/actions/config/init.py

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

src/pkgmgr/actions/install/__init__.py

@@ -1,3 +1,4 @@
+# src/pkgmgr/actions/install/__init__.py
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 
@@ -15,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
@@ -27,7 +28,7 @@ from pkgmgr.actions.install.installers.os_packages import (
     DebianControlInstaller,
     RpmSpecInstaller,
 )
-from pkgmgr.actions.install.installers.nix_flake import (
+from pkgmgr.actions.install.installers.nix import (
     NixFlakeInstaller,
 )
 from pkgmgr.actions.install.installers.python import PythonInstaller
@@ -36,10 +37,8 @@ from pkgmgr.actions.install.installers.makefile import (
 )
 from pkgmgr.actions.install.pipeline import InstallationPipeline
 
-
 Repository = Dict[str, Any]
 
-# All available installers, in the order they should be considered.
 INSTALLERS = [
     ArchPkgbuildInstaller(),
     DebianControlInstaller(),
@@ -50,11 +49,6 @@ INSTALLERS = [
 ]
 
 
-# ---------------------------------------------------------------------------
-# Internal helpers
-# ---------------------------------------------------------------------------
-
-
 def _ensure_repo_dir(
     repo: Repository,
     repositories_base_dir: str,
@@ -99,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.
@@ -117,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
 
@@ -137,6 +137,7 @@ def _create_context(
     quiet: bool,
     clone_mode: str,
     update_dependencies: bool,
+    force_update: bool,
 ) -> RepoContext:
     """
     Build a RepoContext instance for the given repository.
@@ -153,14 +154,10 @@ def _create_context(
         quiet=quiet,
         clone_mode=clone_mode,
         update_dependencies=update_dependencies,
+        force_update=force_update,
     )
 
 
-# ---------------------------------------------------------------------------
-# Public API
-# ---------------------------------------------------------------------------
-
-
 def install_repos(
     selected_repos: List[Repository],
     repositories_base_dir: str,
@@ -171,48 +168,82 @@ def install_repos(
     quiet: bool,
     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
     and the CLI layer precedence rules.
+
+    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,
-        )
-
-        pipeline.run(ctx)
+    if failures and not silent:
+        raise SystemExit(1)

src/pkgmgr/actions/install/context.py

@@ -1,3 +1,4 @@
+# src/pkgmgr/actions/install/context.py
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 
@@ -28,3 +29,6 @@ class RepoContext:
     quiet: bool
     clone_mode: str
     update_dependencies: bool
+
+    # If True, allow re-running installers of the currently active layer.
+    force_update: bool = False

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

@@ -9,7 +9,7 @@ pkgmgr.actions.install.installers.
 """
 
 from pkgmgr.actions.install.installers.base import BaseInstaller  # noqa: F401
-from pkgmgr.actions.install.installers.nix_flake import NixFlakeInstaller  # noqa: F401
+from pkgmgr.actions.install.installers.nix import NixFlakeInstaller  # noqa: F401
 from pkgmgr.actions.install.installers.python import PythonInstaller  # noqa: F401
 from pkgmgr.actions.install.installers.makefile import MakefileInstaller  # noqa: F401
 

src/pkgmgr/actions/install/installers/makefile.py

@@ -1,3 +1,4 @@
+# src/pkgmgr/actions/install/installers/makefile.py
 from __future__ import annotations
 
 import os
@@ -9,89 +10,45 @@ from pkgmgr.core.command.run import run_command
 
 
 class MakefileInstaller(BaseInstaller):
-    """
-    Generic installer that runs `make install` if a Makefile with an
-    install target is present.
-
-    Safety rules:
-      - If PKGMGR_DISABLE_MAKEFILE_INSTALLER=1 is set, this installer
-        is globally disabled.
-      - The higher-level InstallationPipeline ensures that Makefile
-        installation does not run if a stronger CLI layer already owns
-        the command (e.g. Nix or OS packages).
-    """
-
     layer = "makefile"
     MAKEFILE_NAME = "Makefile"
 
     def supports(self, ctx: RepoContext) -> bool:
-        """
-        Return True if this repository has a Makefile and the installer
-        is not globally disabled.
-        """
-        # Optional global kill switch.
         if os.environ.get("PKGMGR_DISABLE_MAKEFILE_INSTALLER") == "1":
             if not ctx.quiet:
-                print(
-                    "[INFO] MakefileInstaller is disabled via "
-                    "PKGMGR_DISABLE_MAKEFILE_INSTALLER."
-                )
+                print("[INFO] PKGMGR_DISABLE_MAKEFILE_INSTALLER=1 – skipping MakefileInstaller.")
             return False
 
         makefile_path = os.path.join(ctx.repo_dir, self.MAKEFILE_NAME)
         return os.path.exists(makefile_path)
 
     def _has_install_target(self, makefile_path: str) -> bool:
-        """
-        Heuristically check whether the Makefile defines an install target.
-
-        We look for:
-
-          - a plain 'install:' target, or
-          - any 'install-*:' style target.
-        """
         try:
             with open(makefile_path, "r", encoding="utf-8", errors="ignore") as f:
                 content = f.read()
         except OSError:
             return False
 
-        # Simple heuristics: look for "install:" or targets starting with "install-"
         if re.search(r"^install\s*:", content, flags=re.MULTILINE):
             return True
-
         if re.search(r"^install-[a-zA-Z0-9_-]*\s*:", content, flags=re.MULTILINE):
             return True
-
         return False
 
     def run(self, ctx: RepoContext) -> None:
-        """
-        Execute `make install` in the repository directory if an install
-        target exists.
-        """
         makefile_path = os.path.join(ctx.repo_dir, self.MAKEFILE_NAME)
-
         if not os.path.exists(makefile_path):
-            if not ctx.quiet:
-                print(
-                    f"[pkgmgr] Makefile '{makefile_path}' not found, "
-                    "skipping MakefileInstaller."
-                )
             return
 
         if not self._has_install_target(makefile_path):
             if not ctx.quiet:
-                print(
-                    f"[pkgmgr] No 'install' target found in {makefile_path}."
-                )
+                print(f"[pkgmgr] No 'install' target found in {makefile_path}.")
             return
 
         if not ctx.quiet:
-            print(
-                f"[pkgmgr] Running 'make install' in {ctx.repo_dir} "
-                "(MakefileInstaller)"
-            )
+            print(f"[pkgmgr] Running make install for {ctx.identifier} (MakefileInstaller)")
 
-        cmd = "make install"
-        run_command(cmd, cwd=ctx.repo_dir, preview=ctx.preview)
+        run_command("make install", cwd=ctx.repo_dir, preview=ctx.preview)
+
+        if ctx.force_update and not ctx.quiet:
+            print(f"[makefile] repo '{ctx.identifier}' successfully upgraded.")

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

@@ -0,0 +1,4 @@
+from .installer import NixFlakeInstaller
+from .retry import RetryPolicy
+
+__all__ = ["NixFlakeInstaller", "RetryPolicy"]

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

@@ -0,0 +1,229 @@
+from __future__ import annotations
+
+import os
+import shutil
+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
+
+if TYPE_CHECKING:
+    from pkgmgr.actions.install.context import RepoContext
+
+
+class NixFlakeInstaller(BaseInstaller):
+    layer = "nix"
+    FLAKE_FILE = "flake.nix"
+
+    def __init__(self, policy: RetryPolicy | None = None) -> None:
+        self._runner = CommandRunner()
+        self._retry = GitHubRateLimitRetry(policy=policy)
+        self._profile = NixProfileInspector()
+        self._conflicts = NixConflictResolver(self._runner, self._retry, self._profile)
+
+        # 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."
+                )
+            return False
+
+        if shutil.which("nix") is None:
+            return False
+
+        return os.path.exists(os.path.join(ctx.repo_dir, self.FLAKE_FILE))
+
+    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)]
+
+    def run(self, ctx: "RepoContext") -> None:
+        if not self.supports(ctx):
+            return
+
+        outputs = self._profile_outputs(ctx)
+
+        if not ctx.quiet:
+            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:
+                self._force_upgrade_output(ctx, output, allow_failure)
+            else:
+                self._install_only(ctx, output, allow_failure)
+
+    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)}"
+
+        if not ctx.quiet:
+            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 upgrade/remove+install..."
+            )
+
+        # 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}).")
+
+            if upgraded:
+                return
+
+            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)
+
+            # 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:
+            if not ctx.quiet:
+                print(f"[nix] output '{output}' successfully re-installed.")
+            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
+    # ---------------------------------------------------------------------
+
+    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
+        for idx in indices:
+            if self._upgrade_index(ctx, idx):
+                upgraded_any = True
+                if not ctx.quiet:
+                    print(f"[nix] output '{output}' successfully upgraded (index {idx}).")
+
+        if upgraded_any:
+            if not ctx.quiet:
+                print(f"[nix] output '{output}' successfully upgraded.")
+            return
+
+        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)
+
+        # 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)
+
+        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:
+        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:
+        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/__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/retry.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import random
+import time
+from dataclasses import dataclass
+from typing import Iterable, TYPE_CHECKING
+
+from .types import RunResult
+
+if TYPE_CHECKING:
+    from pkgmgr.actions.install.context import RepoContext
+    from .runner import CommandRunner
+
+@dataclass(frozen=True)
+class RetryPolicy:
+    max_attempts: int = 7
+    base_delay_seconds: int = 30
+    jitter_seconds_min: int = 0
+    jitter_seconds_max: int = 60
+
+
+class GitHubRateLimitRetry:
+    """
+    Retries nix install commands only when the error looks like a GitHub API rate limit (HTTP 403).
+    Backoff: Fibonacci(base, base, ...) + random jitter.
+    """
+
+    def __init__(self, policy: RetryPolicy | None = None) -> None:
+        self._policy = policy or RetryPolicy()
+
+    def run_with_retry(
+        self,
+        ctx: "RepoContext",
+        runner: "CommandRunner",
+        install_cmd: str,
+    ) -> RunResult:
+        quiet = bool(getattr(ctx, "quiet", False))
+        delays = list(self._fibonacci_backoff(self._policy.base_delay_seconds, self._policy.max_attempts))
+
+        last: RunResult | None = None
+
+        for attempt, base_delay in enumerate(delays, start=1):
+            if not quiet:
+                print(f"[nix] attempt {attempt}/{self._policy.max_attempts}: {install_cmd}")
+
+            res = runner.run(ctx, install_cmd, allow_failure=True)
+            last = res
+
+            if res.returncode == 0:
+                return res
+
+            combined = f"{res.stdout}\n{res.stderr}"
+            if not self._is_github_rate_limit_error(combined):
+                return res
+
+            if attempt >= self._policy.max_attempts:
+                break
+
+            jitter = random.randint(self._policy.jitter_seconds_min, self._policy.jitter_seconds_max)
+            wait_time = base_delay + jitter
+
+            if not quiet:
+                print(
+                    "[nix] GitHub rate limit detected (403). "
+                    f"Retrying in {wait_time}s (base={base_delay}s, jitter={jitter}s)..."
+                )
+
+            time.sleep(wait_time)
+
+        return last if last is not None else RunResult(returncode=1, stdout="", stderr="nix install retry failed")
+
+    @staticmethod
+    def _is_github_rate_limit_error(text: str) -> bool:
+        t = (text or "").lower()
+        return (
+            "http error 403" in t
+            or "rate limit exceeded" in t
+            or "github api rate limit" in t
+            or "api rate limit exceeded" in t
+        )
+
+    @staticmethod
+    def _fibonacci_backoff(base: int, attempts: int) -> Iterable[int]:
+        a, b = base, base
+        for _ in range(max(1, attempts)):
+            yield a
+            a, b = b, a + b

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

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import subprocess
+
+from typing import TYPE_CHECKING
+
+from .types import RunResult
+
+if TYPE_CHECKING:
+    from pkgmgr.actions.install.context import RepoContext
+
+class CommandRunner:
+    """
+    Executes commands (shell=True) inside a repository directory (if provided).
+    Supports preview mode and compact failure output logging.
+    """
+
+    def run(self, ctx: "RepoContext", cmd: str, allow_failure: bool) -> RunResult:
+        repo_dir = getattr(ctx, "repo_dir", None) or getattr(ctx, "repo_path", None)
+        preview = bool(getattr(ctx, "preview", False))
+        quiet = bool(getattr(ctx, "quiet", False))
+
+        if preview:
+            if not quiet:
+                print(f"[preview] {cmd}")
+            return RunResult(returncode=0, stdout="", stderr="")
+
+        try:
+            p = subprocess.run(
+                cmd,
+                shell=True,
+                cwd=repo_dir,
+                check=False,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+            )
+        except Exception as e:
+            if not allow_failure:
+                raise
+            return RunResult(returncode=1, stdout="", stderr=str(e))
+
+        res = RunResult(returncode=p.returncode, stdout=p.stdout or "", stderr=p.stderr or "")
+
+        if res.returncode != 0 and not quiet:
+            self._print_compact_failure(res)
+
+        if res.returncode != 0 and not allow_failure:
+            raise SystemExit(res.returncode)
+
+        return res
+
+    @staticmethod
+    def _print_compact_failure(res: RunResult) -> None:
+        out = (res.stdout or "").strip()
+        err = (res.stderr or "").strip()
+
+        if out:
+            print("[nix] stdout (last lines):")
+            print("\n".join(out.splitlines()[-20:]))
+
+        if err:
+            print("[nix] stderr (last lines):")
+            print("\n".join(err.splitlines()[-40:]))

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/install/installers/nix/types.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class RunResult:
+    returncode: int
+    stdout: str
+    stderr: str

src/pkgmgr/actions/install/installers/nix_flake.py

@@ -1,165 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-
-"""
-Installer for Nix flakes.
-
-If a repository contains flake.nix and the 'nix' command is available, this
-installer will try to install profile outputs from the flake.
-
-Behavior:
-  - If flake.nix is present and `nix` exists on PATH:
-      * First remove any existing `package-manager` profile entry (best-effort).
-      * Then install one or more flake outputs via `nix profile install`.
-  - For the package-manager repo:
-      * `pkgmgr` is mandatory (CLI), `default` is optional.
-  - For all other repos:
-      * `default` is mandatory.
-
-Special handling:
-  - If PKGMGR_DISABLE_NIX_FLAKE_INSTALLER=1 is set, the installer is
-    globally disabled (useful for CI or debugging).
-
-The higher-level InstallationPipeline and CLI-layer model decide when this
-installer is allowed to run, based on where the current CLI comes from
-(e.g. Nix, OS packages, Python, Makefile).
-"""
-
-import os
-import shutil
-from typing import TYPE_CHECKING, List, Tuple
-
-from pkgmgr.actions.install.installers.base import BaseInstaller
-from pkgmgr.core.command.run import run_command
-
-if TYPE_CHECKING:
-    from pkgmgr.actions.install.context import RepoContext
-    from pkgmgr.actions.install import InstallContext
-
-
-class NixFlakeInstaller(BaseInstaller):
-    """Install Nix flake profiles for repositories that define flake.nix."""
-
-    # Logical layer name, used by capability matchers.
-    layer = "nix"
-
-    FLAKE_FILE = "flake.nix"
-    PROFILE_NAME = "package-manager"
-
-    def supports(self, ctx: "RepoContext") -> bool:
-        """
-        Only support repositories that:
-          - Are NOT explicitly disabled via PKGMGR_DISABLE_NIX_FLAKE_INSTALLER=1,
-          - Have a flake.nix,
-          - And have the `nix` command available.
-        """
-        # Optional global kill-switch for CI or debugging.
-        if os.environ.get("PKGMGR_DISABLE_NIX_FLAKE_INSTALLER") == "1":
-            print(
-                "[INFO] PKGMGR_DISABLE_NIX_FLAKE_INSTALLER=1 – "
-                "NixFlakeInstaller is disabled."
-            )
-            return False
-
-        # Nix must be available.
-        if shutil.which("nix") is None:
-            return False
-
-        # flake.nix must exist in the repository.
-        flake_path = os.path.join(ctx.repo_dir, self.FLAKE_FILE)
-        return os.path.exists(flake_path)
-
-    def _ensure_old_profile_removed(self, ctx: "RepoContext") -> None:
-        """
-        Best-effort removal of an existing profile entry.
-
-        This handles the "already provides the following file" conflict by
-        removing previous `package-manager` installations before we install
-        the new one.
-
-        Any error in `nix profile remove` is intentionally ignored, because
-        a missing profile entry is not a fatal condition.
-        """
-        if shutil.which("nix") is None:
-            return
-
-        cmd = f"nix profile remove {self.PROFILE_NAME} || true"
-        try:
-            # NOTE: no allow_failure here → matches the existing unit tests
-            run_command(cmd, cwd=ctx.repo_dir, preview=ctx.preview)
-        except SystemExit:
-            # Unit tests explicitly assert this is swallowed
-            pass
-
-    def _profile_outputs(self, ctx: "RepoContext") -> List[Tuple[str, bool]]:
-        """
-        Decide which flake outputs to install and whether failures are fatal.
-
-        Returns a list of (output_name, allow_failure) tuples.
-
-        Rules:
-          - For the package-manager repo (identifier 'pkgmgr' or 'package-manager'):
-                [("pkgmgr", False), ("default", True)]
-          - For all other repos:
-                [("default", False)]
-        """
-        ident = ctx.identifier
-
-        if ident in {"pkgmgr", "package-manager"}:
-            # pkgmgr: main CLI output is "pkgmgr" (mandatory),
-            # "default" is nice-to-have (non-fatal).
-            return [("pkgmgr", False), ("default", True)]
-
-        # Generic repos: we expect a sensible "default" package/app.
-        # Failure to install it is considered fatal.
-        return [("default", False)]
-
-    def run(self, ctx: "InstallContext") -> None:
-        """
-        Install Nix flake profile outputs.
-
-        For the package-manager repo, failure installing 'pkgmgr' is fatal,
-        failure installing 'default' is non-fatal.
-        For other repos, failure installing 'default' is fatal.
-        """
-        # Reuse supports() to keep logic in one place.
-        if not self.supports(ctx):  # type: ignore[arg-type]
-            return
-
-        outputs = self._profile_outputs(ctx)  # list of (name, allow_failure)
-
-        print(
-            "Nix flake detected in "
-            f"{ctx.identifier}, attempting to install profile outputs: "
-            + ", ".join(name for name, _ in outputs)
-        )
-
-        # Handle the "already installed" case up-front for the shared profile.
-        self._ensure_old_profile_removed(ctx)  # type: ignore[arg-type]
-
-        for output, allow_failure in outputs:
-            cmd = f"nix profile install {ctx.repo_dir}#{output}"
-            print(f"[INFO] Running: {cmd}")
-            ret = os.system(cmd)
-
-            # Extract real exit code from os.system() result
-            if os.WIFEXITED(ret):
-                exit_code = os.WEXITSTATUS(ret)
-            else:
-                # abnormal termination (signal etc.) – keep raw value
-                exit_code = ret
-
-            if exit_code == 0:
-                print(f"Nix flake output '{output}' successfully installed.")
-                continue
-
-            print(f"[Error] Failed to install Nix flake output '{output}'")
-            print(f"[Error] Command exited with code {exit_code}")
-
-            if not allow_failure:
-                raise SystemExit(exit_code)
-
-            print(
-                "[Warning] Continuing despite failure to install "
-                f"optional output '{output}'."
-            )

src/pkgmgr/actions/install/installers/python.py

@@ -1,104 +1,40 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-
-"""
-PythonInstaller — install Python projects defined via pyproject.toml.
-
-Installation rules:
-
-1. pip command resolution:
-      a) If PKGMGR_PIP is set → use it exactly as provided.
-      b) Else if running inside a virtualenv → use `sys.executable -m pip`.
-      c) Else → create/use a per-repository virtualenv under ~/.venvs/<repo>/.
-
-2. Installation target:
-      - Always install into the resolved pip environment.
-      - Never modify system Python, never rely on --user.
-      - Nix-immutable systems (PEP 668) are automatically avoided because we
-        never touch system Python.
-
-3. The installer is skipped when:
-      - PKGMGR_DISABLE_PYTHON_INSTALLER=1 is set.
-      - The repository has no pyproject.toml.
-
-All pip failures are treated as fatal.
-"""
-
+# src/pkgmgr/actions/install/installers/python.py
 from __future__ import annotations
 
 import os
 import sys
-import subprocess
-from typing import TYPE_CHECKING
 
 from pkgmgr.actions.install.installers.base import BaseInstaller
+from pkgmgr.actions.install.context import RepoContext
 from pkgmgr.core.command.run import run_command
 
-if TYPE_CHECKING:
-    from pkgmgr.actions.install.context import RepoContext
-    from pkgmgr.actions.install import InstallContext
-
 
 class PythonInstaller(BaseInstaller):
-    """Install Python projects and dependencies via pip using isolated environments."""
-
     layer = "python"
 
-    # ----------------------------------------------------------------------
-    # Installer activation logic
-    # ----------------------------------------------------------------------
-    def supports(self, ctx: "RepoContext") -> bool:
-        """
-        Return True if this installer should handle this repository.
-
-        The installer is active only when:
-          - A pyproject.toml exists in the repo, and
-          - PKGMGR_DISABLE_PYTHON_INSTALLER is not set.
-        """
+    def supports(self, ctx: RepoContext) -> bool:
         if os.environ.get("PKGMGR_DISABLE_PYTHON_INSTALLER") == "1":
             print("[INFO] PythonInstaller disabled via PKGMGR_DISABLE_PYTHON_INSTALLER.")
             return False
 
         return os.path.exists(os.path.join(ctx.repo_dir, "pyproject.toml"))
 
-    # ----------------------------------------------------------------------
-    # Virtualenv handling
-    # ----------------------------------------------------------------------
     def _in_virtualenv(self) -> bool:
-        """Detect whether the current interpreter is inside a venv."""
         if os.environ.get("VIRTUAL_ENV"):
             return True
-
         base = getattr(sys, "base_prefix", sys.prefix)
         return sys.prefix != base
 
-    def _ensure_repo_venv(self, ctx: "InstallContext") -> str:
-        """
-        Ensure that ~/.venvs/<identifier>/ exists and contains a minimal venv.
-
-        Returns the venv directory path.
-        """
+    def _ensure_repo_venv(self, ctx: RepoContext) -> str:
         venv_dir = os.path.expanduser(f"~/.venvs/{ctx.identifier}")
         python = sys.executable
 
-        if not os.path.isdir(venv_dir):
-            print(f"[python-installer] Creating virtualenv: {venv_dir}")
-            subprocess.check_call([python, "-m", "venv", venv_dir])
+        if not os.path.exists(venv_dir):
+            run_command(f"{python} -m venv {venv_dir}", preview=ctx.preview)
 
         return venv_dir
 
-    # ----------------------------------------------------------------------
-    # pip command resolution
-    # ----------------------------------------------------------------------
-    def _pip_cmd(self, ctx: "InstallContext") -> str:
-        """
-        Determine which pip command to use.
-
-        Priority:
-          1. PKGMGR_PIP override given by user or automation.
-          2. Active virtualenv → use sys.executable -m pip.
-          3. Per-repository venv → ~/.venvs/<repo>/bin/pip
-        """
+    def _pip_cmd(self, ctx: RepoContext) -> str:
         explicit = os.environ.get("PKGMGR_PIP", "").strip()
         if explicit:
             return explicit
@@ -107,33 +43,19 @@ class PythonInstaller(BaseInstaller):
             return f"{sys.executable} -m pip"
 
         venv_dir = self._ensure_repo_venv(ctx)
-        pip_path = os.path.join(venv_dir, "bin", "pip")
-        return pip_path
+        return os.path.join(venv_dir, "bin", "pip")
 
-    # ----------------------------------------------------------------------
-    # Execution
-    # ----------------------------------------------------------------------
-    def run(self, ctx: "InstallContext") -> None:
-        """
-        Install the project defined by pyproject.toml.
-
-        Uses the resolved pip environment. Installation is isolated and never
-        touches system Python.
-        """
-        if not self.supports(ctx):  # type: ignore[arg-type]
-            return
-
-        pyproject = os.path.join(ctx.repo_dir, "pyproject.toml")
-        if not os.path.exists(pyproject):
+    def run(self, ctx: RepoContext) -> None:
+        if not self.supports(ctx):
             return
 
         print(f"[python-installer] Installing Python project for {ctx.identifier}...")
 
         pip_cmd = self._pip_cmd(ctx)
+        run_command(f"{pip_cmd} install .", cwd=ctx.repo_dir, preview=ctx.preview)
 
-        # Final install command: ALWAYS isolated, never system-wide.
-        install_cmd = f"{pip_cmd} install ."
-
-        run_command(install_cmd, cwd=ctx.repo_dir, preview=ctx.preview)
+        if ctx.force_update:
+            # test-visible marker
+            print(f"[python-installer] repo '{ctx.identifier}' successfully upgraded.")
 
         print(f"[python-installer] Installation finished for {ctx.identifier}.")

src/pkgmgr/actions/install/pipeline.py

@@ -1,21 +1,9 @@
+# src/pkgmgr/actions/install/pipeline.py
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 
 """
 Installation pipeline orchestration for repositories.
-
-This module implements the "Setup Controller" logic:
-
-  1. Detect current CLI command for the repo (if any).
-  2. Classify it into a layer (os-packages, nix, python, makefile).
-  3. Iterate over installers in layer order:
-       - Skip installers whose layer is weaker than an already-loaded one.
-       - Run only installers that support() the repo and add new capabilities.
-       - After each installer, re-resolve the command and update the layer.
-  4. Maintain the repo["command"] field and create/update symlinks via create_ink().
-
-The goal is to prevent conflicting installations and make the layering
-behaviour explicit and testable.
 """
 
 from __future__ import annotations
@@ -36,34 +24,15 @@ from pkgmgr.core.command.resolve import resolve_command_for_repo
 
 @dataclass
 class CommandState:
-    """
-    Represents the current CLI state for a repository:
-
-      - command: absolute or relative path to the CLI entry point
-      - layer:   which conceptual layer this command belongs to
-    """
-
     command: Optional[str]
     layer: Optional[CliLayer]
 
 
 class CommandResolver:
-    """
-    Small helper responsible for resolving the current command for a repo
-    and mapping it into a CommandState.
-    """
-
     def __init__(self, ctx: RepoContext) -> None:
         self._ctx = ctx
 
     def resolve(self) -> CommandState:
-        """
-        Resolve the current command for this repository.
-
-        If resolve_command_for_repo raises SystemExit (e.g. Python package
-        without installed entry point), we treat this as "no command yet"
-        from the point of view of the installers.
-        """
         repo = self._ctx.repo
         identifier = self._ctx.identifier
         repo_dir = self._ctx.repo_dir
@@ -85,28 +54,10 @@ class CommandResolver:
 
 
 class InstallationPipeline:
-    """
-    High-level orchestrator that applies a sequence of installers
-    to a repository based on CLI layer precedence.
-    """
-
     def __init__(self, installers: Sequence[BaseInstaller]) -> None:
         self._installers = list(installers)
 
-    # ------------------------------------------------------------------
-    # Public API
-    # ------------------------------------------------------------------
     def run(self, ctx: RepoContext) -> None:
-        """
-        Execute the installation pipeline for a single repository.
-
-        - Detect initial command & layer.
-        - Optionally create a symlink.
-        - Run installers in order, skipping those whose layer is weaker
-          than an already-loaded CLI.
-        - After each installer, re-resolve the command and refresh the
-          symlink if needed.
-        """
         repo = ctx.repo
         repo_dir = ctx.repo_dir
         identifier = ctx.identifier
@@ -119,7 +70,6 @@ class InstallationPipeline:
         resolver = CommandResolver(ctx)
         state = resolver.resolve()
 
-        # Persist initial command (if any) and create a symlink.
         if state.command:
             repo["command"] = state.command
             create_ink(
@@ -135,11 +85,9 @@ class InstallationPipeline:
 
         provided_capabilities: Set[str] = set()
 
-        # Main installer loop
         for installer in self._installers:
             layer_name = getattr(installer, "layer", None)
 
-            # Installers without a layer participate without precedence logic.
             if layer_name is None:
                 self._run_installer(installer, ctx, identifier, repo_dir, quiet)
                 continue
@@ -147,17 +95,13 @@ class InstallationPipeline:
             try:
                 installer_layer = CliLayer(layer_name)
             except ValueError:
-                # Unknown layer string → treat as lowest priority.
                 installer_layer = None
 
-            # "Previous/Current layer already loaded?"
             if state.layer is not None and installer_layer is not None:
                 current_prio = layer_priority(state.layer)
                 installer_prio = layer_priority(installer_layer)
 
                 if current_prio < installer_prio:
-                    # Current CLI comes from a higher-priority layer,
-                    # so we skip this installer entirely.
                     if not quiet:
                         print(
                             "[pkgmgr] Skipping installer "
@@ -166,9 +110,7 @@ class InstallationPipeline:
                         )
                     continue
 
-                if current_prio == installer_prio:
-                    # Same layer already provides a CLI; usually there is no
-                    # need to run another installer on top of it.
+                if current_prio == installer_prio and not ctx.force_update:
                     if not quiet:
                         print(
                             "[pkgmgr] Skipping installer "
@@ -177,12 +119,9 @@ class InstallationPipeline:
                         )
                     continue
 
-            # Check if this installer is applicable at all.
             if not installer.supports(ctx):
                 continue
 
-            # Capabilities: if everything this installer would provide is already
-            # covered, we can safely skip it.
             caps = installer.discover_capabilities(ctx)
             if caps and caps.issubset(provided_capabilities):
                 if not quiet:
@@ -193,18 +132,22 @@ class InstallationPipeline:
                 continue
 
             if not quiet:
-                print(
-                    f"[pkgmgr] Running installer {installer.__class__.__name__} "
-                    f"for {identifier} in '{repo_dir}' "
-                    f"(new capabilities: {caps or set()})..."
-                )
+                if ctx.force_update and state.layer is not None and installer_layer == state.layer:
+                    print(
+                        f"[pkgmgr] Running installer {installer.__class__.__name__} "
+                        f"for {identifier} in '{repo_dir}' (upgrade requested)..."
+                    )
+                else:
+                    print(
+                        f"[pkgmgr] Running installer {installer.__class__.__name__} "
+                        f"for {identifier} in '{repo_dir}' "
+                        f"(new capabilities: {caps or set()})..."
+                    )
 
-            # Run the installer with error reporting.
             self._run_installer(installer, ctx, identifier, repo_dir, quiet)
 
             provided_capabilities.update(caps)
 
-            # After running an installer, re-resolve the command and layer.
             new_state = resolver.resolve()
             if new_state.command:
                 repo["command"] = new_state.command
@@ -221,9 +164,6 @@ class InstallationPipeline:
 
             state = new_state
 
-    # ------------------------------------------------------------------
-    # Internal helpers
-    # ------------------------------------------------------------------
     @staticmethod
     def _run_installer(
         installer: BaseInstaller,
@@ -232,9 +172,6 @@ class InstallationPipeline:
         repo_dir: str,
         quiet: bool,
     ) -> None:
-        """
-        Execute a single installer with unified error handling.
-        """
         try:
             installer.run(ctx)
         except SystemExit as exc:

src/pkgmgr/actions/mirror/__init__.py

@@ -1,5 +1,3 @@
-from __future__ import annotations
-
 """
 High-level mirror actions.
 
@@ -10,6 +8,7 @@ Public API:
     - setup_mirrors
 """
 
+from __future__ import annotations
 from .types import Repository, MirrorMap
 from .list_cmd import list_mirrors
 from .diff_cmd import diff_mirrors

src/pkgmgr/actions/mirror/git_remote.py

@@ -1,20 +1,50 @@
 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]:
+def _is_git_remote_url(url: str) -> bool:
     """
-    Build a simple SSH URL from repo config if no explicit mirror is defined.
+    True only for URLs that should become git remotes / push URLs.
 
-    Example: git@github.com:account/repository.git
+    Accepted:
+      - git@host:owner/repo(.git)                (SCP-like SSH)
+      - ssh://git@host(:port)/owner/repo(.git)   (SSH URL)
+      - https://host/owner/repo.git              (HTTPS git remote)
+      - http://host/owner/repo.git               (rare, but possible)
+    Everything else (e.g. PyPI project page) stays metadata only.
     """
+    u = (url or "").strip()
+    if not u:
+        return False
+
+    if u.startswith("git@"):
+        return True
+
+    if u.startswith("ssh://"):
+        return True
+
+    if (u.startswith("https://") or u.startswith("http://")) and u.endswith(".git"):
+        return True
+
+    return False
+
+
+def build_default_ssh_url(repo: Repository) -> Optional[str]:
     provider = repo.get("provider")
     account = repo.get("account")
     name = repo.get("repository")
@@ -23,96 +53,80 @@ 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 _git_mirrors_only(m: MirrorMap) -> MirrorMap:
+    return {k: v for k, v in m.items() if v and _is_git_remote_url(v)}
+
+
 def determine_primary_remote_url(
     repo: Repository,
-    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 (GIT URLS ONLY):
+      1. origin from resolved mirrors (if it is a git URL)
+      2. first git URL from MIRRORS file (in file order)
+      3. first git URL from config mirrors (in config order)
+      4. default SSH URL
     """
-    if "origin" in resolved_mirrors:
-        return resolved_mirrors["origin"]
+    resolved = ctx.resolved_mirrors
+    origin = resolved.get("origin")
+    if origin and _is_git_remote_url(origin):
+        return origin
 
-    if resolved_mirrors:
-        first_name = sorted(resolved_mirrors.keys())[0]
-        return resolved_mirrors[first_name]
+    for mirrors in (ctx.file_mirrors, ctx.config_mirrors):
+        for _, url in mirrors.items():
+            if url and _is_git_remote_url(url):
+                return url
 
     return build_default_ssh_url(repo)
 
 
-def _safe_git_output(args: List[str], cwd: str) -> Optional[str]:
-    """
-    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 *git* mirror URLs (except primary) are configured as additional
+    push URLs for origin.
+
+    Non-git URLs (like PyPI) are ignored and will never land in git config.
     """
-    desired: Set[str] = {url for url in mirrors.values() if url}
+    git_only = _git_mirrors_only(mirrors)
+    desired: Set[str] = {u for u in git_only.values() if u and u != primary}
     if not desired:
         return
 
-    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 +134,33 @@ 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 or not _is_git_remote_url(primary):
+        print("[WARN] No valid git primary mirror URL could be determined.")
+        return
 
+    # 1) Ensure origin exists
     if not has_origin_remote(repo_dir):
-        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
     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:
+        print(f"[WARN] Failed to set origin URLs: {exc}")
+
+    # 3) Ensure additional push URLs for mirrors (git urls only)
+    try:
+        _ensure_additional_push_urls(repo_dir, ctx.resolved_mirrors, primary, preview)
+    except GitAddRemotePushUrlError as exc:
+        print(f"[WARN] Failed to add additional push URLs: {exc}")

src/pkgmgr/actions/mirror/io.py

@@ -1,8 +1,9 @@
 from __future__ import annotations
 
 import os
+from collections.abc import Iterable, Mapping
+from typing import Union
 from urllib.parse import urlparse
-from typing import List, Mapping
 
 from .types import MirrorMap, Repository
 
@@ -32,7 +33,7 @@ def read_mirrors_file(repo_dir: str, filename: str = "MIRRORS") -> MirrorMap:
     """
     Supports:
         NAME URL
-        URL  → auto name = hostname
+        URL  -> auto-generate name from hostname
     """
     path = os.path.join(repo_dir, filename)
     mirrors: MirrorMap = {}
@@ -52,7 +53,8 @@ def read_mirrors_file(repo_dir: str, filename: str = "MIRRORS") -> MirrorMap:
                 # Case 1: "name url"
                 if len(parts) == 2:
                     name, url = parts
-                # Case 2: "url" → auto-generate name
+
+                # Case 2: "url" -> auto name
                 elif len(parts) == 1:
                     url = parts[0]
                     parsed = urlparse(url)
@@ -67,21 +69,56 @@ def read_mirrors_file(repo_dir: str, filename: str = "MIRRORS") -> MirrorMap:
                     continue
 
                 mirrors[name] = url
+
     except OSError as exc:
         print(f"[WARN] Could not read MIRRORS file at {path}: {exc}")
 
     return mirrors
 
 
+MirrorsInput = Union[Mapping[str, str], Iterable[str]]
+
+
 def write_mirrors_file(
     repo_dir: str,
-    mirrors: Mapping[str, str],
+    mirrors: MirrorsInput,
     filename: str = "MIRRORS",
     preview: bool = False,
 ) -> None:
+    """
+    Write MIRRORS in one of two formats:
 
+    1) Mapping[str, str] -> "NAME URL" per line (legacy / compatible)
+    2) Iterable[str]     -> "URL" per line (new preferred)
+
+    Strings are treated as a single URL (not iterated character-by-character).
+    """
     path = os.path.join(repo_dir, filename)
-    lines = [f"{name} {url}" for name, url in sorted(mirrors.items())]
+
+    lines: list[str]
+
+    if isinstance(mirrors, Mapping):
+        items = [
+            (str(name), str(url))
+            for name, url in mirrors.items()
+            if url is not None and str(url).strip()
+        ]
+        items.sort(key=lambda x: (x[0], x[1]))
+        lines = [f"{name} {url}" for name, url in items]
+
+    else:
+        if isinstance(mirrors, (str, bytes)):
+            urls = [str(mirrors).strip()]
+        else:
+            urls = [
+                str(url).strip()
+                for url in mirrors
+                if url is not None and str(url).strip()
+            ]
+
+        urls = sorted(set(urls))
+        lines = urls
+
     content = "\n".join(lines) + ("\n" if lines else "")
 
     if preview:
@@ -94,5 +131,6 @@ def write_mirrors_file(
         with open(path, "w", encoding="utf-8") as fh:
             fh.write(content)
         print(f"[INFO] Wrote MIRRORS file at {path}")
+
     except OSError as exc:
         print(f"[ERROR] Failed to write MIRRORS file at {path}: {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,23 +1,36 @@
 from __future__ import annotations
 
-from typing import List, Tuple
+from typing import List
 
-from pkgmgr.core.git import run_git, GitError
+from pkgmgr.core.git.queries import probe_remote_reachable
 
 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 .remote_provision import ensure_remote_repository
 from .types import Repository
 
 
+def _is_git_remote_url(url: str) -> bool:
+    # Keep the same filtering semantics as in git_remote.py (duplicated on purpose
+    # to keep setup_cmd independent of private helpers).
+    u = (url or "").strip()
+    if not u:
+        return False
+    if u.startswith("git@"):
+        return True
+    if u.startswith("ssh://"):
+        return True
+    if (u.startswith("https://") or u.startswith("http://")) and u.endswith(".git"):
+        return True
+    return False
+
+
 def _setup_local_mirrors_for_repo(
     repo: Repository,
     repositories_base_dir: str,
     all_repos: List[Repository],
     preview: bool,
 ) -> None:
-    """
-    Ensure local Git state is sane (currently: 'origin' remote).
-    """
     ctx = build_context(repo, repositories_base_dir, all_repos)
 
     print("------------------------------------------------------------")
@@ -25,107 +38,53 @@ 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()
 
 
-def _probe_mirror(url: str, repo_dir: str) -> Tuple[bool, str]:
-    """
-    Probe a remote mirror by running `git ls-remote <url>`.
-
-    Returns:
-      (True, "") on success,
-      (False, error_message) on failure.
-
-    Wichtig:
-      - Wir werten ausschließlich den Exit-Code aus.
-      - STDERR kann Hinweise/Warnings enthalten und ist NICHT automatisch ein Fehler.
-    """
-    try:
-        # Wir ignorieren stdout komplett; wichtig ist nur, dass der Befehl ohne
-        # GitError (also Exit-Code 0) durchläuft.
-        run_git(["ls-remote", url], cwd=repo_dir)
-        return True, ""
-    except GitError as exc:
-        return False, str(exc)
-
-
 def _setup_remote_mirrors_for_repo(
     repo: Repository,
     repositories_base_dir: str,
     all_repos: List[Repository],
     preview: bool,
+    ensure_remote: bool,
 ) -> None:
-    """
-    Remote-side setup / validation.
-
-    Aktuell werden nur **nicht-destruktive Checks** gemacht:
-
-      - Für jeden Mirror (aus config + MIRRORS-Datei, file gewinnt):
-          * `git ls-remote <url>` wird ausgeführt.
-          * Bei Exit-Code 0 → [OK]
-          * Bei Fehler → [WARN] + Details aus der GitError-Exception
-
-    Es werden **keine** Provider-APIs aufgerufen und keine Repos angelegt.
-    """
     ctx = build_context(repo, repositories_base_dir, all_repos)
-    resolved_m = ctx.resolved_mirrors
 
     print("------------------------------------------------------------")
     print(f"[MIRROR SETUP:REMOTE] {ctx.identifier}")
     print(f"[MIRROR SETUP:REMOTE] dir: {ctx.repo_dir}")
     print("------------------------------------------------------------")
 
-    if not resolved_m:
-        # Optional: Fallback auf eine heuristisch bestimmte URL, falls wir
-        # irgendwann "automatisch anlegen" implementieren wollen.
-        primary_url = determine_primary_remote_url(repo, resolved_m)
-        if not primary_url:
-            print(
-                "[INFO] No mirrors configured (config or MIRRORS file), and no "
-                "primary URL could be derived from provider/account/repository."
-            )
+    if ensure_remote:
+        ensure_remote_repository(
+            repo,
+            repositories_base_dir,
+            all_repos,
+            preview,
+        )
+
+    # Probe only git URLs (do not try ls-remote against PyPI etc.)
+    # If there are no mirrors at all, probe the primary git URL.
+    git_mirrors = {k: v for k, v in ctx.resolved_mirrors.items() if _is_git_remote_url(v)}
+
+    if not git_mirrors:
+        primary = determine_primary_remote_url(repo, ctx)
+        if not primary or not _is_git_remote_url(primary):
+            print("[INFO] No git mirrors to probe.")
             print()
             return
 
-        ok, error_message = _probe_mirror(primary_url, ctx.repo_dir)
-        if ok:
-            print(f"[OK]   Remote mirror (primary) is reachable: {primary_url}")
-        else:
-            print("[WARN] Primary remote URL is NOT reachable:")
-            print(f"       {primary_url}")
-            if error_message:
-                print("       Details:")
-                for line in error_message.splitlines():
-                    print(f"         {line}")
-
-        print()
-        print(
-            "[INFO] Remote checks are non-destructive and only use `git ls-remote` "
-            "to probe mirror URLs."
-        )
+        ok = probe_remote_reachable(primary, cwd=ctx.repo_dir)
+        print("[OK]" if ok else "[WARN]", primary)
         print()
         return
 
-    # Normaler Fall: wir haben benannte Mirrors aus config/MIRRORS
-    for name, url in sorted(resolved_m.items()):
-        ok, error_message = _probe_mirror(url, ctx.repo_dir)
-        if ok:
-            print(f"[OK]   Remote mirror '{name}' is reachable: {url}")
-        else:
-            print(f"[WARN] Remote mirror '{name}' is NOT reachable:")
-            print(f"       {url}")
-            if error_message:
-                print("       Details:")
-                for line in error_message.splitlines():
-                    print(f"         {line}")
+    for name, url in git_mirrors.items():
+        ok = probe_remote_reachable(url, cwd=ctx.repo_dir)
+        print(f"[OK] {name}: {url}" if ok else f"[WARN] {name}: {url}")
 
     print()
-    print(
-        "[INFO] Remote checks are non-destructive and only use `git ls-remote` "
-        "to probe mirror URLs."
-    )
-    print()
 
 
 def setup_mirrors(
@@ -135,31 +94,22 @@ def setup_mirrors(
     preview: bool = False,
     local: bool = True,
     remote: bool = True,
+    ensure_remote: bool = False,
 ) -> None:
-    """
-    Setup mirrors for the selected repositories.
-
-    local:
-      - Configure local Git remotes (currently: ensure 'origin' is present and
-        points to a reasonable URL).
-
-    remote:
-      - Non-destructive remote checks using `git ls-remote` for each mirror URL.
-        Es werden keine Repositories auf dem Provider angelegt.
-    """
     for repo in selected_repos:
         if local:
             _setup_local_mirrors_for_repo(
                 repo,
-                repositories_base_dir=repositories_base_dir,
-                all_repos=all_repos,
-                preview=preview,
+                repositories_base_dir,
+                all_repos,
+                preview,
             )
 
         if remote:
             _setup_remote_mirrors_for_repo(
                 repo,
-                repositories_base_dir=repositories_base_dir,
-                all_repos=all_repos,
-                preview=preview,
+                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/files.py

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

src/pkgmgr/actions/release/git_ops.py

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

src/pkgmgr/actions/release/versioning.py

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

src/pkgmgr/actions/release/workflow.py

@@ -1,10 +1,14 @@
 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.commands import add, commit, push, tag_annotated
+from pkgmgr.core.git.queries import get_current_branch
+from pkgmgr.core.repository.paths import resolve_repo_paths
 
 from .files import (
     update_changelog,
@@ -18,7 +22,6 @@ from .files import (
 from .git_ops import (
     ensure_clean_and_synced,
     is_highest_version_tag,
-    run_git_command,
     update_latest_tag,
 )
 from .prompts import confirm_proceed_release, should_delete_branch
@@ -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,20 +118,19 @@ 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:
-            print(f"[PREVIEW] Would run: git add {path}")
-        print(f'[PREVIEW] Would run: git commit -am "{commit_msg}"')
-        print(f'[PREVIEW] Would run: git tag -a {new_tag} -m "{tag_msg}"')
-        print(f"[PREVIEW] Would run: git push origin {branch}")
-        print(f"[PREVIEW] Would run: git push origin {new_tag}")
+        add(existing_files, preview=True)
+        commit(commit_msg, all=True, preview=True)
+        tag_annotated(new_tag, tag_msg, preview=True)
+        push("origin", branch, preview=True)
+        push("origin", new_tag, preview=True)
 
         if is_highest_version_tag(new_tag):
             update_latest_tag(new_tag, preview=True)
@@ -130,15 +144,13 @@ def _release_impl(
                 print(f"[PREVIEW] Would ask whether to delete branch {branch} after release.")
         return
 
-    for path in existing_files:
-        run_git_command(f"git add {path}")
-
-    run_git_command(f'git commit -am "{commit_msg}"')
-    run_git_command(f'git tag -a {new_tag} -m "{tag_msg}"')
+    add(existing_files, preview=False)
+    commit(commit_msg, all=True, preview=False)
+    tag_annotated(new_tag, tag_msg, preview=False)
 
     # Push branch and ONLY the newly created version tag (no --tags)
-    run_git_command(f"git push origin {branch}")
-    run_git_command(f"git push origin {new_tag}")
+    push("origin", branch, preview=False)
+    push("origin", new_tag, preview=False)
 
     # Update 'latest' only if this is the highest version tag
     try:

src/pkgmgr/actions/repository/clone.py

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

src/pkgmgr/actions/repository/create.py

@@ -1,144 +0,0 @@
-import os
-import subprocess
-import sys
-import yaml
-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("/")
-    if len(parts) != 3:
-        print("Identifier must be in the format 'provider:port/account/repository' (port is optional).")
-        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
-
-    # 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
-
-    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
-        }
-        # Load or initialize the user configuration.
-        if os.path.exists(user_config_path):
-            with open(user_config_path, "r") 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}")
-        else:
-            subprocess.run(cmd_init, cwd=repo_dir, shell=True, check=True)
-            print(f"Git repository initialized in {repo_dir}.")
-    else:
-        print("Git repository is already initialized.")
-
-    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.")

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

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

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

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

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

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

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

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from pkgmgr.actions.mirror.io import write_mirrors_file
+from pkgmgr.actions.mirror.setup_cmd import setup_mirrors
+
+Repository = Dict[str, Any]
+
+
+class MirrorBootstrapper:
+    """
+    MIRRORS is the single source of truth.
+
+    Defaults are written to MIRRORS and mirror setup derives
+    git remotes exclusively from that file (git URLs only).
+    """
+
+    def write_defaults(
+        self,
+        *,
+        repo_dir: str,
+        primary: str,
+        name: str,
+        preview: bool,
+    ) -> None:
+        mirrors = {
+            primary,
+            f"https://pypi.org/project/{name}/",
+        }
+        write_mirrors_file(repo_dir, mirrors, preview=preview)
+
+    def setup(
+        self,
+        *,
+        repo: Repository,
+        repositories_base_dir: str,
+        all_repos: list[Repository],
+        preview: bool,
+        remote: bool,
+    ) -> None:
+        # IMPORTANT:
+        # Do NOT set repo["mirrors"] here.
+        # MIRRORS file is the single source of truth.
+        setup_mirrors(
+            selected_repos=[repo],
+            repositories_base_dir=repositories_base_dir,
+            all_repos=all_repos,
+            preview=preview,
+            local=True,
+            remote=True,
+            ensure_remote=remote,
+        )

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

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

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

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

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

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

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

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

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

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

src/pkgmgr/actions/repository/deinstall.py

@@ -1,15 +1,32 @@
 import os
-import sys
-from pkgmgr.core.repository.identifier import get_repo_identifier
-from pkgmgr.core.repository.dir import get_repo_dir
 
-def deinstall_repos(selected_repos, repositories_base_dir, bin_dir, all_repos, preview=False):
+from pkgmgr.core.command.run import run_command
+from pkgmgr.core.repository.dir import get_repo_dir
+from pkgmgr.core.repository.identifier import get_repo_identifier
+
+
+def deinstall_repos(
+    selected_repos,
+    repositories_base_dir,
+    bin_dir,
+    all_repos,
+    preview: bool = False,
+) -> None:
     for repo in selected_repos:
         repo_identifier = get_repo_identifier(repo, all_repos)
-        alias_path = os.path.join(bin_dir, repo_identifier)
 
+        # Resolve repository directory
+        repo_dir = get_repo_dir(repositories_base_dir, repo)
+
+        # Prefer alias if available; fall back to identifier
+        alias_name = str(repo.get("alias") or repo_identifier)
+        alias_path = os.path.join(os.path.expanduser(bin_dir), alias_name)
+
+        # Remove alias link/file (interactive)
         if os.path.exists(alias_path):
-            confirm = input(f"Are you sure you want to delete link '{alias_path}' for {repo_identifier}? [y/N]: ").strip().lower()
+            confirm = input(
+                f"Are you sure you want to delete link '{alias_path}' for {repo_identifier}? [y/N]: "
+            ).strip().lower()
             if confirm == "y":
                 if preview:
                     print(f"[Preview] Would remove link '{alias_path}'.")
@@ -19,10 +36,13 @@ def deinstall_repos(selected_repos, repositories_base_dir, bin_dir, all_repos, p
         else:
             print(f"No link found for {repo_identifier} in {bin_dir}.")
 
+        # Run make deinstall if repository exists and has a Makefile
         makefile_path = os.path.join(repo_dir, "Makefile")
         if os.path.exists(makefile_path):
             print(f"Makefile found in {repo_identifier}, running 'make deinstall'...")
             try:
                 run_command("make deinstall", cwd=repo_dir, preview=preview)
             except SystemExit as e:
-                print(f"[Warning] Failed to run 'make deinstall' for {repo_identifier}: {e}")
+                print(
+                    f"[Warning] Failed to run 'make deinstall' for {repo_identifier}: {e}"
+                )