Release version 1.7.1

* Introduce publish action with PyPI target detection via MIRRORS
* Resolve version from SemVer git tags on HEAD
* Support preview mode and non-interactive CI usage
* Build and upload artifacts using build + twine with token resolution
* Add CLI wiring (dispatch, command handler, parser)
* Add E2E publish help tests for pkgmgr and nix run
* Add integration tests for publish preview and mirror handling
* Add unit tests for git tag parsing, PyPI URL parsing, workflow preview, and CLI handler
* Clean up dispatch and parser structure while integrating publish

https://chatgpt.com/share/693f0f00-af68-800f-8846-193dca69bd2e

.github/workflows/ci.yml

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

.github/workflows/linter-python.yml

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

.github/workflows/linter-shell.yml

@@ -4,7 +4,7 @@ on:
   workflow_call:
 
 jobs:
-  codesniffer-shellcheck:
+  linter-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:
+  linter-shell:
-    uses: ./.github/workflows/codesniffer-shellcheck.yml
+    uses: ./.github/workflows/linter-shell.yml
 
-  codesniffer-ruff:
+  linter-python:
-    uses: ./.github/workflows/codesniffer-ruff.yml
+    uses: ./.github/workflows/linter-python.yml
 
   mark-stable:
     needs:
-      - codesniffer-shellcheck
+      - linter-shell
-      - codesniffer-ruff
+      - linter-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,72 @@
+## [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
+PKGMGR_DISTRO ?= arch
-export distro
+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.7.1";
 
             # Use the git repo as source
             src = ./.;

packaging/arch/PKGBUILD

@@ -1,7 +1,7 @@
 # Maintainer: Kevin Veen-Birkenbach <info@veen.world>
 
 pkgname=package-manager
-pkgver=0.9.1
+pkgver=1.7.1
 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,33 @@
+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.7.1
 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,24 @@ echo ">>> package-manager removed. Nix itself was not removed."
 /usr/lib/package-manager/
 
 %changelog
+* 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"
+name = "kpmx"
-version = "1.4.1"
+version = "1.7.1"
 description = "Kevin's package-manager tool (pkgmgr)"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -19,16 +19,17 @@ authors = [
 
 # Base runtime dependencies
 dependencies = [
-  "PyYAML>=6.0"
+  "PyYAML>=6.0",
+  "tomli; python_version < \"3.11\"",
 ]
 
 [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"
+  local PKGMGR_DISTRO="$1"
-  case "$distro" in
+  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/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 "[launcher] ERROR: 'nix' binary not found on PATH after init."
-echo "[pkgmgr-wrapper] Nix is required to run pkgmgr (no Python fallback)."
+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() {
+# Ensure a given nix.conf key contains required tokens (merged, no duplicates)
-  local nix_conf want
+nixconf_ensure_features_key() {
-  nix_conf="$(nixconf_file_path)"
+  local nix_conf="$1"
-  want="experimental-features = nix-command flakes"
+  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
+  # Key exists -> merge tokens
-    if grep -qE '^\s*experimental-features\s*=.*\bnix-command\b' "${nix_conf}" \
+  if grep -qE "^\s*${key}\s*=" "${nix_conf}"; then
-      && grep -qE '^\s*experimental-features\s*=.*\bflakes\b' "${nix_conf}"; then
+    local ok=1
-      echo "[nix-conf] experimental-features already correct"
+    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=""
-    local merged="nix-command flakes"
     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_store_${PKGMGR_DISTRO}:/nix" \
-  -v "pkgmgr_nix_cache_${distro}:/root/.cache/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_store_${PKGMGR_DISTRO}:/nix" \
-  -v "pkgmgr_nix_cache_${distro}:/root/.cache/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'
+docker image inspect "${IMAGE}" | sed -n '1,40p'
-
-echo "[test-env-virtual] Running: docker run --rm --entrypoint pkgmgr $IMAGE --help"
 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" \
+    -w /src \
-        "$IMAGE" 2>&1); then
+    "${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

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_store_${PKGMGR_DISTRO}:/nix" \
-  -v "pkgmgr_nix_cache_${distro}:/root/.cache/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_cache_${PKGMGR_DISTRO}:/root/.cache/nix" \
-  -v pkgmgr_nix_store_${distro}:/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/install/__init__.py

@@ -1,3 +1,4 @@
+# src/pkgmgr/actions/install/__init__.py
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 
@@ -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,
@@ -137,6 +131,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 +148,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,10 +162,14 @@ def install_repos(
     quiet: bool,
     clone_mode: str,
     update_dependencies: bool,
+    force_update: bool = False,
 ) -> 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.
     """
     pipeline = InstallationPipeline(INSTALLERS)
 
@@ -213,6 +208,7 @@ def install_repos(
             quiet=quiet,
             clone_mode=clone_mode,
             update_dependencies=update_dependencies,
+            force_update=force_update,
         )
 
         pipeline.run(ctx)

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(
+                print("[INFO] PKGMGR_DISABLE_MAKEFILE_INSTALLER=1 – skipping MakefileInstaller.")
-                    "[INFO] MakefileInstaller is disabled via "
-                    "PKGMGR_DISABLE_MAKEFILE_INSTALLER."
-                )
             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(
+                print(f"[pkgmgr] No 'install' target found in {makefile_path}.")
-                    f"[pkgmgr] No 'install' target found in {makefile_path}."
-                )
             return
 
         if not ctx.quiet:
-            print(
+            print(f"[pkgmgr] Running make install for {ctx.identifier} (MakefileInstaller)")
-                f"[pkgmgr] Running 'make install' in {ctx.repo_dir} "
-                "(MakefileInstaller)"
-            )
 
-        cmd = "make install"
+        run_command("make install", cwd=ctx.repo_dir, preview=ctx.preview)
-        run_command(cmd, 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
+# src/pkgmgr/actions/install/installers/python.py
-# -*- 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.
-"""
-
 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.core.command.run import run_command
-
-if TYPE_CHECKING:
 from pkgmgr.actions.install.context import RepoContext
-    from pkgmgr.actions.install import InstallContext
+from pkgmgr.core.command.run import run_command
 
 
 class PythonInstaller(BaseInstaller):
-    """Install Python projects and dependencies via pip using isolated environments."""
-
     layer = "python"
 
-    # ----------------------------------------------------------------------
+    def supports(self, ctx: RepoContext) -> bool:
-    # 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.
-        """
         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:
+    def _ensure_repo_venv(self, ctx: RepoContext) -> str:
-        """
-        Ensure that ~/.venvs/<identifier>/ exists and contains a minimal venv.
-
-        Returns the venv directory path.
-        """
         venv_dir = os.path.expanduser(f"~/.venvs/{ctx.identifier}")
         python = sys.executable
 
-        if not os.path.isdir(venv_dir):
+        if not os.path.exists(venv_dir):
-            print(f"[python-installer] Creating virtualenv: {venv_dir}")
+            run_command(f"{python} -m venv {venv_dir}", preview=ctx.preview)
-            subprocess.check_call([python, "-m", "venv", venv_dir])
 
         return venv_dir
 
-    # ----------------------------------------------------------------------
+    def _pip_cmd(self, ctx: RepoContext) -> str:
-    # 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
-        """
         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 os.path.join(venv_dir, "bin", "pip")
-        return pip_path
 
-    # ----------------------------------------------------------------------
+    def run(self, ctx: RepoContext) -> None:
-    # Execution
+        if not self.supports(ctx):
-    # ----------------------------------------------------------------------
-    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):
             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.
+        if ctx.force_update:
-        install_cmd = f"{pip_cmd} install ."
+            # test-visible marker
-
+            print(f"[python-installer] repo '{ctx.identifier}' successfully upgraded.")
-        run_command(install_cmd, cwd=ctx.repo_dir, preview=ctx.preview)
 
         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:
+                if current_prio == installer_prio and not ctx.force_update:
-                    # Same layer already provides a CLI; usually there is no
-                    # need to run another installer on top of it.
                     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:
+                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/io.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import os
 from urllib.parse import urlparse
-from typing import List, Mapping
+from typing import Mapping
 
 from .types import MirrorMap, Repository
 

src/pkgmgr/actions/mirror/remote_check.py

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

src/pkgmgr/actions/mirror/remote_provision.py

@@ -0,0 +1,70 @@
+# src/pkgmgr/actions/mirror/remote_provision.py
+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)
+    resolved_mirrors = ctx.resolved_mirrors
+
+    primary_url = determine_primary_remote_url(repo, resolved_mirrors)
+    if not primary_url:
+        print("[INFO] No remote URL could be derived; skipping remote provisioning.")
+        return
+
+    host_raw, owner_from_url, name_from_url = parse_repo_from_git_url(primary_url)
+    host = normalize_provider_host(host_raw)
+
+    if not host or not owner_from_url or not name_from_url:
+        print("[WARN] Could not derive host/owner/repository from URL; cannot ensure remote repo.")
+        print(f"       url={primary_url!r}")
+        print(f"       host={host!r}, owner={owner_from_url!r}, repository={name_from_url!r}")
+        return
+
+    print("------------------------------------------------------------")
+    print(f"[REMOTE ENSURE] {ctx.identifier}")
+    print(f"[REMOTE ENSURE] host: {host}")
+    print("------------------------------------------------------------")
+
+    spec = RepoSpec(
+        host=str(host),
+        owner=str(owner_from_url),
+        name=str(name_from_url),
+        private=bool(repo.get("private", True)),
+        description=str(repo.get("description", "")),
+    )
+
+    provider_kind = str(repo.get("provider", "")).strip().lower() or None
+
+    try:
+        result = ensure_remote_repo(
+            spec,
+            provider_hint=ProviderHint(kind=provider_kind),
+            options=EnsureOptions(
+                preview=preview,
+                interactive=True,
+                allow_prompt=True,
+                save_prompt_token_to_keyring=True,
+            ),
+        )
+        print(f"[REMOTE ENSURE] {result.status.upper()}: {result.message}")
+        if result.url:
+            print(f"[REMOTE ENSURE] URL: {result.url}")
+    except Exception as exc:  # noqa: BLE001
+        print(f"[ERROR] Remote provisioning failed: {exc}")
+
+    print()

src/pkgmgr/actions/mirror/setup_cmd.py

@@ -1,23 +1,20 @@
+# src/pkgmgr/actions/mirror/setup_cmd.py
 from __future__ import annotations
 
-from typing import List, Tuple
+from typing import List
-
-from pkgmgr.core.git import run_git, GitError
 
 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_check import probe_mirror
+from .remote_provision import ensure_remote_repository
 from .types import Repository
 
-
 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("------------------------------------------------------------")
@@ -29,103 +26,57 @@ def _setup_local_mirrors_for_repo(
     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
+    resolved_mirrors = 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:
+    if ensure_remote:
-        # Optional: Fallback auf eine heuristisch bestimmte URL, falls wir
+        ensure_remote_repository(
-        # irgendwann "automatisch anlegen" implementieren wollen.
+            repo,
-        primary_url = determine_primary_remote_url(repo, resolved_m)
+            repositories_base_dir=repositories_base_dir,
+            all_repos=all_repos,
+            preview=preview,
+        )
+
+    if not resolved_mirrors:
+        primary_url = determine_primary_remote_url(repo, resolved_mirrors)
         if not primary_url:
-            print(
+            print("[INFO] No mirrors configured and no primary URL available.")
-                "[INFO] No mirrors configured (config or MIRRORS file), and no "
-                "primary URL could be derived from provider/account/repository."
-            )
             print()
             return
 
-        ok, error_message = _probe_mirror(primary_url, ctx.repo_dir)
+        ok, error_message = probe_mirror(primary_url, ctx.repo_dir)
         if ok:
-            print(f"[OK]   Remote mirror (primary) is reachable: {primary_url}")
+            print(f"[OK] primary: {primary_url}")
         else:
-            print("[WARN] Primary remote URL is NOT reachable:")
+            print(f"[WARN] primary: {primary_url}")
-            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."
-        )
         print()
         return
 
-    # Normaler Fall: wir haben benannte Mirrors aus config/MIRRORS
+    for name, url in sorted(resolved_mirrors.items()):
-    for name, url in sorted(resolved_m.items()):
+        ok, error_message = probe_mirror(url, ctx.repo_dir)
-        ok, error_message = _probe_mirror(url, ctx.repo_dir)
         if ok:
-            print(f"[OK]   Remote mirror '{name}' is reachable: {url}")
+            print(f"[OK] {name}: {url}")
         else:
-            print(f"[WARN] Remote mirror '{name}' is NOT reachable:")
+            print(f"[WARN] {name}: {url}")
-            print(f"       {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."
-    )
-    print()
 
 
 def setup_mirrors(
@@ -135,22 +86,12 @@ 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,
+                repo=repo,
                 repositories_base_dir=repositories_base_dir,
                 all_repos=all_repos,
                 preview=preview,
@@ -158,8 +99,9 @@ def setup_mirrors(
 
         if remote:
             _setup_remote_mirrors_for_repo(
-                repo,
+                repo=repo,
                 repositories_base_dir=repositories_base_dir,
                 all_repos=all_repos,
                 preview=preview,
+                ensure_remote=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,17 @@
+from __future__ import annotations
+
+from pkgmgr.core.git import run_git
+from pkgmgr.core.version.semver import SemVer, is_semver_tag
+
+
+def head_semver_tags(cwd: str = ".") -> list[str]:
+    out = run_git(["tag", "--points-at", "HEAD"], cwd=cwd)
+    if not out:
+        return []
+
+    tags = [t.strip() for t in out.splitlines() if t.strip()]
+    tags = [t for t in tags if is_semver_tag(t) and t.startswith("v")]
+    if not tags:
+        return []
+
+    return sorted(tags, key=SemVer.parse)

src/pkgmgr/actions/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,109 @@
+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()
+    token = resolver.get_token(
+        provider_kind="pypi",
+        host=target.host,
+        owner=target.project,
+        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/workflow.py

@@ -1,10 +1,13 @@
+# src/pkgmgr/actions/release/workflow.py
 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.repository.paths import resolve_repo_paths
 
 from .files import (
     update_changelog,
@@ -55,8 +58,12 @@ def _release_impl(
     print(f"New version:     {new_ver_str} ({release_type})")
 
     repo_root = os.path.dirname(os.path.abspath(pyproject_path))
+    paths = resolve_repo_paths(repo_root)
+
+    # --- Update versioned files ------------------------------------------------
 
     update_pyproject_version(pyproject_path, new_ver_str, preview=preview)
+
     changelog_message = update_changelog(
         changelog_path,
         new_ver_str,
@@ -64,38 +71,46 @@ def _release_impl(
         preview=preview,
     )
 
-    flake_path = os.path.join(repo_root, "flake.nix")
+    update_flake_version(paths.flake_nix, new_ver_str, preview=preview)
-    update_flake_version(flake_path, new_ver_str, preview=preview)
 
-    pkgbuild_path = os.path.join(repo_root, "PKGBUILD")
+    if paths.arch_pkgbuild:
-    update_pkgbuild_version(pkgbuild_path, new_ver_str, preview=preview)
+        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")
+    if paths.rpm_spec:
-    update_spec_version(spec_path, new_ver_str, preview=preview)
+        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"
 
+    if paths.debian_changelog:
         update_debian_changelog(
-        debian_changelog_path,
+            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.")
+
+    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,
         )
 
-    update_spec_changelog(
+    # --- Git commit / tag / push ----------------------------------------------
-        spec_path=spec_path,
-        package_name=package_name,
-        new_version=new_ver_str,
-        message=effective_message,
-        preview=preview,
-    )
 
     commit_msg = f"Release version {new_ver_str}"
     tag_msg = effective_message or commit_msg
@@ -103,12 +118,12 @@ def _release_impl(
     files_to_add = [
         pyproject_path,
         changelog_path,
-        flake_path,
+        paths.flake_nix,
-        pkgbuild_path,
+        paths.arch_pkgbuild,
-        spec_path,
+        paths.rpm_spec,
-        debian_changelog_path,
+        paths.debian_changelog,
     ]
-    existing_files = [p for p in files_to_add if p and os.path.exists(p)]
+    existing_files = [p for p in files_to_add if isinstance(p, str) and p and os.path.exists(p)]
 
     if preview:
         for path in existing_files:

src/pkgmgr/actions/repository/create.py

@@ -1,6 +1,5 @@
 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

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}"
+                )

src/pkgmgr/actions/repository/pull.py

@@ -1,9 +1,12 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
 import os
 import subprocess
 import sys
 
-from pkgmgr.core.repository.identifier import get_repo_identifier
 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
 
 
@@ -17,13 +20,6 @@ def pull_with_verification(
 ) -> None:
     """
     Execute `git pull` for each repository with verification.
-
-    - Uses verify_repository() in "pull" mode.
-    - If verification fails (and verification info is set) and
-      --no-verification is not enabled, the user is prompted to confirm
-      the pull.
-    - In preview mode, no interactive prompts are performed and no
-      Git commands are executed; only the would-be command is printed.
     """
     for repo in selected_repos:
         repo_identifier = get_repo_identifier(repo, all_repos)
@@ -34,18 +30,13 @@ def pull_with_verification(
             continue
 
         verified_info = repo.get("verified")
-        verified_ok, errors, commit_hash, signing_key = verify_repository(
+        verified_ok, errors, _commit_hash, _signing_key = verify_repository(
             repo,
             repo_dir,
             mode="pull",
             no_verification=no_verification,
         )
 
-        # Only prompt the user if:
-        #   - we are NOT in preview mode
-        #   - verification is enabled
-        #   - the repo has verification info configured
-        #   - verification failed
         if (
             not preview
             and not no_verification
@@ -59,16 +50,14 @@ def pull_with_verification(
             if choice != "y":
                 continue
 
-        # Build the git pull command (include extra args if present)
         args_part = " ".join(extra_args) if extra_args else ""
         full_cmd = f"git pull{(' ' + args_part) if args_part else ''}"
 
         if preview:
-            # Preview mode: only show the command, do not execute or prompt.
             print(f"[Preview] In '{repo_dir}': {full_cmd}")
         else:
             print(f"Running in '{repo_dir}': {full_cmd}")
-            result = subprocess.run(full_cmd, cwd=repo_dir, shell=True)
+            result = subprocess.run(full_cmd, cwd=repo_dir, shell=True, check=False)
             if result.returncode != 0:
                 print(
                     f"'git pull' for {repo_identifier} failed "

src/pkgmgr/actions/repository/status.py

@@ -1,4 +1,3 @@
-import sys
 import shutil
 
 from pkgmgr.actions.proxy import exec_proxy_command

src/pkgmgr/actions/repository/update.py

@@ -1,68 +0,0 @@
-import sys
-import shutil
-
-from pkgmgr.actions.repository.pull import pull_with_verification
-from pkgmgr.actions.install import install_repos
-
-
-def update_repos(
-    selected_repos,
-    repositories_base_dir,
-    bin_dir,
-    all_repos,
-    no_verification,
-    system_update,
-    preview: bool,
-    quiet: bool,
-    update_dependencies: bool,
-    clone_mode: str,
-):
-    """
-    Update repositories by pulling latest changes and installing them.
-
-    Parameters:
-    - selected_repos: List of selected repositories.
-    - repositories_base_dir: Base directory for repositories.
-    - bin_dir: Directory for symbolic links.
-    - all_repos: All repository configurations.
-    - no_verification: Whether to skip verification.
-    - system_update: Whether to run system update.
-    - preview: If True, only show commands without executing.
-    - quiet: If True, suppress messages.
-    - update_dependencies: Whether to update dependent repositories.
-    - clone_mode: Method to clone repositories (ssh or https).
-    """
-    pull_with_verification(
-        selected_repos,
-        repositories_base_dir,
-        all_repos,
-        [],
-        no_verification,
-        preview,
-    )
-
-    install_repos(
-        selected_repos,
-        repositories_base_dir,
-        bin_dir,
-        all_repos,
-        no_verification,
-        preview,
-        quiet,
-        clone_mode,
-        update_dependencies,
-    )
-
-    if system_update:
-        from pkgmgr.core.command.run import run_command
-
-        # Nix: upgrade all profile entries (if Nix is available)
-        if shutil.which("nix") is not None:
-            try:
-                run_command("nix profile upgrade '.*'", preview=preview)
-            except SystemExit as e:
-                print(f"[Warning] 'nix profile upgrade' failed: {e}")
-
-        # Arch / AUR system update
-        run_command("sudo -u aur_builder yay -Syu --noconfirm", preview=preview)
-        run_command("sudo pacman -Syyu --noconfirm", preview=preview)

src/pkgmgr/actions/update/__init__.py

@@ -0,0 +1,10 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+from __future__ import annotations
+
+from pkgmgr.actions.update.manager import UpdateManager
+
+__all__ = [
+    "UpdateManager",
+]

src/pkgmgr/actions/update/manager.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+from __future__ import annotations
+
+from typing import Any, Iterable
+
+from pkgmgr.actions.update.system_updater import SystemUpdater
+
+
+class UpdateManager:
+    """
+    Orchestrates:
+      - repository pull + installation
+      - optional system update
+    """
+
+    def __init__(self) -> None:
+        self._system_updater = SystemUpdater()
+
+    def run(
+        self,
+        selected_repos: Iterable[Any],
+        repositories_base_dir: str,
+        bin_dir: str,
+        all_repos: Any,
+        no_verification: bool,
+        system_update: bool,
+        preview: bool,
+        quiet: bool,
+        update_dependencies: bool,
+        clone_mode: str,
+        force_update: bool = True,
+    ) -> None:
+        from pkgmgr.actions.install import install_repos
+        from pkgmgr.actions.repository.pull import pull_with_verification
+
+        pull_with_verification(
+            selected_repos,
+            repositories_base_dir,
+            all_repos,
+            [],
+            no_verification,
+            preview,
+        )
+
+        install_repos(
+            selected_repos,
+            repositories_base_dir,
+            bin_dir,
+            all_repos,
+            no_verification,
+            preview,
+            quiet,
+            clone_mode,
+            update_dependencies,
+            force_update=force_update,
+        )
+
+        if system_update:
+            self._system_updater.run(preview=preview)

src/pkgmgr/actions/update/os_release.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Dict
+
+
+def read_os_release(path: str = "/etc/os-release") -> Dict[str, str]:
+    """
+    Parse /etc/os-release into a dict. Returns empty dict if missing.
+    """
+    if not os.path.exists(path):
+        return {}
+
+    result: Dict[str, str] = {}
+    with open(path, "r", encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if not line or line.startswith("#") or "=" not in line:
+                continue
+            key, value = line.split("=", 1)
+            result[key.strip()] = value.strip().strip('"')
+    return result
+
+
+@dataclass(frozen=True)
+class OSReleaseInfo:
+    """
+    Minimal /etc/os-release representation for distro detection.
+    """
+    id: str = ""
+    id_like: str = ""
+    pretty_name: str = ""
+
+    @staticmethod
+    def load() -> "OSReleaseInfo":
+        data = read_os_release()
+        return OSReleaseInfo(
+            id=(data.get("ID") or "").lower(),
+            id_like=(data.get("ID_LIKE") or "").lower(),
+            pretty_name=(data.get("PRETTY_NAME") or ""),
+        )
+
+    def ids(self) -> set[str]:
+        ids: set[str] = set()
+        if self.id:
+            ids.add(self.id)
+        if self.id_like:
+            for part in self.id_like.split():
+                ids.add(part.strip())
+        return ids
+
+    def is_arch_family(self) -> bool:
+        ids = self.ids()
+        return ("arch" in ids) or ("archlinux" in ids)
+
+    def is_debian_family(self) -> bool:
+        ids = self.ids()
+        return bool(ids.intersection({"debian", "ubuntu"}))
+
+    def is_fedora_family(self) -> bool:
+        ids = self.ids()
+        return bool(ids.intersection({"fedora", "rhel", "centos", "rocky", "almalinux"}))

src/pkgmgr/actions/update/system_updater.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+from __future__ import annotations
+
+import platform
+import shutil
+
+from pkgmgr.actions.update.os_release import OSReleaseInfo
+
+
+class SystemUpdater:
+    """
+    Executes distro-specific system update commands, plus Nix profile upgrades if available.
+    """
+
+    def run(self, *, preview: bool) -> None:
+        from pkgmgr.core.command.run import run_command
+
+        # Distro-agnostic: Nix profile upgrades (if Nix is present).
+        if shutil.which("nix") is not None:
+            try:
+                run_command("nix profile upgrade '.*'", preview=preview)
+            except SystemExit as e:
+                print(f"[Warning] 'nix profile upgrade' failed: {e}")
+
+        osr = OSReleaseInfo.load()
+
+        if osr.is_arch_family():
+            self._update_arch(preview=preview)
+            return
+
+        if osr.is_debian_family():
+            self._update_debian(preview=preview)
+            return
+
+        if osr.is_fedora_family():
+            self._update_fedora(preview=preview)
+            return
+
+        distro = osr.pretty_name or platform.platform()
+        print(f"[Warning] Unsupported distribution for system update: {distro}")
+
+    def _update_arch(self, *, preview: bool) -> None:
+        from pkgmgr.core.command.run import run_command
+
+        yay = shutil.which("yay")
+        pacman = shutil.which("pacman")
+        sudo = shutil.which("sudo")
+
+        # Prefer yay if available (repo + AUR in one pass).
+        # Avoid running yay and pacman afterwards to prevent double update passes.
+        if yay and sudo:
+            run_command("sudo -u aur_builder yay -Syu --noconfirm", preview=preview)
+            return
+
+        if pacman and sudo:
+            run_command("sudo pacman -Syu --noconfirm", preview=preview)
+            return
+
+        print("[Warning] Cannot update Arch system: missing required tools (sudo/yay/pacman).")
+
+    def _update_debian(self, *, preview: bool) -> None:
+        from pkgmgr.core.command.run import run_command
+
+        sudo = shutil.which("sudo")
+        apt_get = shutil.which("apt-get")
+
+        if not (sudo and apt_get):
+            print("[Warning] Cannot update Debian/Ubuntu system: missing required tools (sudo/apt-get).")
+            return
+
+        env = "DEBIAN_FRONTEND=noninteractive"
+        run_command(f"sudo {env} apt-get update -y", preview=preview)
+        run_command(f"sudo {env} apt-get -y dist-upgrade", preview=preview)
+
+    def _update_fedora(self, *, preview: bool) -> None:
+        from pkgmgr.core.command.run import run_command
+
+        sudo = shutil.which("sudo")
+        dnf = shutil.which("dnf")
+        microdnf = shutil.which("microdnf")
+
+        if not sudo:
+            print("[Warning] Cannot update Fedora/RHEL-like system: missing sudo.")
+            return
+
+        if dnf:
+            run_command("sudo dnf -y upgrade", preview=preview)
+            return
+
+        if microdnf:
+            run_command("sudo microdnf -y upgrade", preview=preview)
+            return
+
+        print("[Warning] Cannot update Fedora/RHEL-like system: missing dnf/microdnf.")

src/pkgmgr/cli/commands/__init__.py

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

src/pkgmgr/cli/commands/changelog.py

@@ -8,7 +8,7 @@ from pkgmgr.cli.context import CLIContext
 from pkgmgr.core.repository.dir import get_repo_dir
 from pkgmgr.core.repository.identifier import get_repo_identifier
 from pkgmgr.core.git import get_tags
-from pkgmgr.core.version.semver import SemVer, extract_semver_from_tags
+from pkgmgr.core.version.semver import extract_semver_from_tags
 from pkgmgr.actions.changelog import generate_changelog
 
 

src/pkgmgr/cli/commands/mirror.py

@@ -1,32 +1,30 @@
+# src/pkgmgr/cli/commands/mirror.py
 from __future__ import annotations
 
 import sys
 from typing import Any, Dict, List
 
-from pkgmgr.actions.mirror import (
+from pkgmgr.actions.mirror import diff_mirrors, list_mirrors, merge_mirrors, setup_mirrors
-    diff_mirrors,
-    list_mirrors,
-    merge_mirrors,
-    setup_mirrors,
-)
 from pkgmgr.cli.context import CLIContext
 
 Repository = Dict[str, Any]
 
 
 def handle_mirror_command(
-    args,
     ctx: CLIContext,
+    args: Any,
     selected: List[Repository],
 ) -> None:
     """
     Entry point for 'pkgmgr mirror' subcommands.
 
     Subcommands:
-      - mirror list   → list configured mirrors
+      - mirror list
-      - mirror diff   → compare config vs MIRRORS file
+      - mirror diff
-      - mirror merge  → merge mirrors between config and MIRRORS file
+      - mirror merge
-      - mirror setup  → configure local Git + remote placeholders
+      - mirror setup
+      - mirror check
+      - mirror provision
     """
     if not selected:
         print("[INFO] No repositories selected for 'mirror' command.")
@@ -34,9 +32,6 @@ def handle_mirror_command(
 
     subcommand = getattr(args, "subcommand", None)
 
-    # ------------------------------------------------------------
-    # mirror list
-    # ------------------------------------------------------------
     if subcommand == "list":
         source = getattr(args, "source", "all")
         list_mirrors(
@@ -47,9 +42,6 @@ def handle_mirror_command(
         )
         return
 
-    # ------------------------------------------------------------
-    # mirror diff
-    # ------------------------------------------------------------
     if subcommand == "diff":
         diff_mirrors(
             selected_repos=selected,
@@ -58,27 +50,17 @@ def handle_mirror_command(
         )
         return
 
-    # ------------------------------------------------------------
-    # mirror merge
-    # ------------------------------------------------------------
     if subcommand == "merge":
         source = getattr(args, "source", None)
         target = getattr(args, "target", None)
         preview = getattr(args, "preview", False)
 
         if source == target:
-            print(
+            print("[ERROR] For 'mirror merge', source and target must differ (config vs file).")
-                "[ERROR] For 'mirror merge', source and target "
-                "must differ (one of: config, file)."
-            )
             sys.exit(2)
 
-        # Config file path can be passed explicitly via --config-path.
-        # If not given, fall back to the global context (if available).
         explicit_config_path = getattr(args, "config_path", None)
-        user_config_path = explicit_config_path or getattr(
+        user_config_path = explicit_config_path or getattr(ctx, "user_config_path", None)
-            ctx, "user_config_path", None
-        )
 
         merge_mirrors(
             selected_repos=selected,
@@ -91,26 +73,42 @@ def handle_mirror_command(
         )
         return
 
-    # ------------------------------------------------------------
-    # mirror setup
-    # ------------------------------------------------------------
     if subcommand == "setup":
-        local = getattr(args, "local", False)
-        remote = getattr(args, "remote", False)
         preview = getattr(args, "preview", False)
-
-        # If neither flag is set → default to both.
-        if not local and not remote:
-            local = True
-            remote = True
-
         setup_mirrors(
             selected_repos=selected,
             repositories_base_dir=ctx.repositories_base_dir,
             all_repos=ctx.all_repositories,
             preview=preview,
-            local=local,
+            local=True,
-            remote=remote,
+            remote=False,
+            ensure_remote=False,
+        )
+        return
+
+    if subcommand == "check":
+        preview = getattr(args, "preview", False)
+        setup_mirrors(
+            selected_repos=selected,
+            repositories_base_dir=ctx.repositories_base_dir,
+            all_repos=ctx.all_repositories,
+            preview=preview,
+            local=False,
+            remote=True,
+            ensure_remote=False,
+        )
+        return
+
+    if subcommand == "provision":
+        preview = getattr(args, "preview", False)
+        setup_mirrors(
+            selected_repos=selected,
+            repositories_base_dir=ctx.repositories_base_dir,
+            all_repos=ctx.all_repositories,
+            preview=preview,
+            local=False,
+            remote=True,
+            ensure_remote=True,
         )
         return
 

src/pkgmgr/cli/commands/publish.py

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

src/pkgmgr/cli/commands/repos.py

@@ -10,12 +10,10 @@ from pkgmgr.cli.context import CLIContext
 from pkgmgr.actions.install import install_repos
 from pkgmgr.actions.repository.deinstall import deinstall_repos
 from pkgmgr.actions.repository.delete import delete_repos
-from pkgmgr.actions.repository.update import update_repos
 from pkgmgr.actions.repository.status import status_repos
 from pkgmgr.actions.repository.list import list_repositories
-from pkgmgr.core.command.run import run_command
 from pkgmgr.actions.repository.create import create_repo
-from pkgmgr.core.repository.selected import get_selected_repos
+from pkgmgr.core.command.run import run_command
 from pkgmgr.core.repository.dir import get_repo_dir
 
 Repository = Dict[str, Any]
@@ -52,7 +50,7 @@ def handle_repos_command(
     selected: List[Repository],
 ) -> None:
     """
-    Handle core repository commands (install/update/deinstall/delete/.../list).
+    Handle core repository commands (install/update/deinstall/delete/status/list/path/shell/create).
     """
 
     # ------------------------------------------------------------
@@ -69,24 +67,7 @@ def handle_repos_command(
             args.quiet,
             args.clone_mode,
             args.dependencies,
-        )
+            force_update=getattr(args, "update", False),
-        return
-
-    # ------------------------------------------------------------
-    # update
-    # ------------------------------------------------------------
-    if args.command == "update":
-        update_repos(
-            selected,
-            ctx.repositories_base_dir,
-            ctx.binaries_dir,
-            ctx.all_repositories,
-            args.no_verification,
-            args.system,
-            args.preview,
-            args.quiet,
-            args.dependencies,
-            args.clone_mode,
         )
         return
 
@@ -147,9 +128,7 @@ def handle_repos_command(
                     f"{repository.get('account', '?')}/"
                     f"{repository.get('repository', '?')}"
                 )
-                print(
+                print(f"[WARN] Could not resolve directory for {ident}: {exc}")
-                    f"[WARN] Could not resolve directory for {ident}: {exc}"
-                )
                 continue
 
             print(repo_dir)

src/pkgmgr/cli/commands/version.py

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

src/pkgmgr/cli/dispatch.py

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

src/pkgmgr/cli/parser/__init__.py

@@ -1,6 +1,3 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-
 from __future__ import annotations
 
 import argparse
@@ -13,6 +10,7 @@ from .config_cmd import add_config_subparsers
 from .navigation_cmd import add_navigation_subparsers
 from .branch_cmd import add_branch_subparsers
 from .release_cmd import add_release_subparser
+from .publish_cmd import add_publish_subparser
 from .version_cmd import add_version_subparser
 from .changelog_cmd import add_changelog_subparser
 from .list_cmd import add_list_subparser
@@ -21,9 +19,6 @@ from .mirror_cmd import add_mirror_subparsers
 
 
 def create_parser(description_text: str) -> argparse.ArgumentParser:
-    """
-    Create the top-level argument parser for pkgmgr.
-    """
     parser = argparse.ArgumentParser(
         description=description_text,
         formatter_class=argparse.RawTextHelpFormatter,
@@ -34,35 +29,23 @@ def create_parser(description_text: str) -> argparse.ArgumentParser:
         action=SortedSubParsersAction,
     )
 
-    # Core repo operations
     add_install_update_subparsers(subparsers)
     add_config_subparsers(subparsers)
-
-    # Navigation / tooling around repos
     add_navigation_subparsers(subparsers)
 
-    # Branch & release workflow
     add_branch_subparsers(subparsers)
     add_release_subparser(subparsers)
+    add_publish_subparser(subparsers)
 
-    # Info commands
     add_version_subparser(subparsers)
     add_changelog_subparser(subparsers)
     add_list_subparser(subparsers)
 
-    # Make wrapper
     add_make_subparsers(subparsers)
-
-    # Mirror management
     add_mirror_subparsers(subparsers)
 
-    # Proxy commands (git, docker, docker compose, ...)
     register_proxy_commands(subparsers)
-
     return parser
 
 
-__all__ = [
+__all__ = ["create_parser", "SortedSubParsersAction"]
-    "create_parser",
-    "SortedSubParsersAction",
-]

src/pkgmgr/cli/parser/common.py

@@ -1,96 +1,134 @@
-#!/usr/bin/env python3
+# src/pkgmgr/cli/parser/common.py
-# -*- coding: utf-8 -*-
-
 from __future__ import annotations
 
 import argparse
+from typing import Optional, Tuple
 
 
 class SortedSubParsersAction(argparse._SubParsersAction):
     """
-    Subparsers action that keeps choices sorted alphabetically.
+    Subparsers action that keeps subcommands sorted alphabetically.
     """
 
     def add_parser(self, name, **kwargs):
         parser = super().add_parser(name, **kwargs)
-        # Sort choices alphabetically by dest (subcommand name)
         self._choices_actions.sort(key=lambda a: a.dest)
         return parser
 
 
+def _has_action(
+    parser: argparse.ArgumentParser,
+    *,
+    positional: Optional[str] = None,
+    options: Tuple[str, ...] = (),
+) -> bool:
+    """
+    Check whether the parser already has an action.
+
+    - positional: name of a positional argument (e.g. "identifiers")
+    - options: option strings (e.g. "--preview", "-q")
+    """
+    for action in parser._actions:
+        if positional and action.dest == positional:
+            return True
+        if options and any(opt in action.option_strings for opt in options):
+            return True
+    return False
+
+
+def _add_positional_if_missing(
+    parser: argparse.ArgumentParser,
+    name: str,
+    **kwargs,
+) -> None:
+    """Safely add a positional argument."""
+    if _has_action(parser, positional=name):
+        return
+    parser.add_argument(name, **kwargs)
+
+
+def _add_option_if_missing(
+    parser: argparse.ArgumentParser,
+    *option_strings: str,
+    **kwargs,
+) -> None:
+    """Safely add an optional argument."""
+    if _has_action(parser, options=tuple(option_strings)):
+        return
+    parser.add_argument(*option_strings, **kwargs)
+
+
 def add_identifier_arguments(subparser: argparse.ArgumentParser) -> None:
     """
     Common identifier / selection arguments for many subcommands.
-
-    Selection modes (mutual intent, not hard-enforced):
-      - identifiers (positional): select by alias / provider/account/repo
-      - --all: select all repositories
-      - --category / --string / --tag: filter-based selection on top
-        of the full repository set
     """
-    subparser.add_argument(
+    _add_positional_if_missing(
+        subparser,
         "identifiers",
         nargs="*",
         help=(
             "Identifier(s) for repositories. "
-            "Default: Repository of current folder."
+            "Default: repository of the current working directory."
         ),
     )
-    subparser.add_argument(
+
+    _add_option_if_missing(
+        subparser,
         "--all",
         action="store_true",
         default=False,
         help=(
             "Apply the subcommand to all repositories in the config. "
-            "Some subcommands ask for confirmation. If you want to give this "
+            "Pipe 'yes' to auto-confirm. Example:\n"
-            "confirmation for all repositories, pipe 'yes'. E.g: "
+            "  yes | pkgmgr <command> --all"
-            "yes | pkgmgr {subcommand} --all"
         ),
     )
-    subparser.add_argument(
+
+    _add_option_if_missing(
+        subparser,
         "--category",
         nargs="+",
         default=[],
-        help=(
+        help="Filter repositories by category (supports /regex/).",
-            "Filter repositories by category patterns derived from config "
-            "filenames or repo metadata (use filename without .yml/.yaml, "
-            "or /regex/ to use a regular expression)."
-        ),
     )
-    subparser.add_argument(
+
+    _add_option_if_missing(
+        subparser,
         "--string",
         default="",
-        help=(
+        help="Filter repositories by substring or /regex/.",
-            "Filter repositories whose identifier / name / path contains this "
-            "substring (case-insensitive). Use /regex/ for regular expressions."
-        ),
     )
-    subparser.add_argument(
+
+    _add_option_if_missing(
+        subparser,
         "--tag",
         action="append",
         default=[],
-        help=(
+        help="Filter repositories by tag (supports /regex/).",
-            "Filter repositories by tag. Matches tags from the repository "
-            "collector and category tags. Use /regex/ for regular expressions."
-        ),
     )
-    subparser.add_argument(
+
+    _add_option_if_missing(
+        subparser,
         "--preview",
         action="store_true",
-        help="Preview changes without executing commands",
+        help="Preview changes without executing commands.",
     )
-    subparser.add_argument(
+
+    _add_option_if_missing(
+        subparser,
         "--list",
         action="store_true",
-        help="List affected repositories (with preview or status)",
+        help="List affected repositories.",
     )
-    subparser.add_argument(
+
+    _add_option_if_missing(
+        subparser,
         "-a",
         "--args",
-        nargs=argparse.REMAINDER,
         dest="extra_args",
-        help="Additional parameters to be attached.",
+        nargs=argparse.REMAINDER,
         default=[],
+        help="Additional parameters to be attached.",
     )
 
 
@@ -99,29 +137,34 @@ def add_install_update_arguments(subparser: argparse.ArgumentParser) -> None:
     Common arguments for install/update commands.
     """
     add_identifier_arguments(subparser)
-    subparser.add_argument(
+
+    _add_option_if_missing(
+        subparser,
         "-q",
         "--quiet",
         action="store_true",
-        help="Suppress warnings and info messages",
+        help="Suppress warnings and info messages.",
     )
-    subparser.add_argument(
+
+    _add_option_if_missing(
+        subparser,
         "--no-verification",
         action="store_true",
         default=False,
-        help="Disable verification via commit/gpg",
+        help="Disable verification via commit / GPG.",
     )
-    subparser.add_argument(
+
+    _add_option_if_missing(
+        subparser,
         "--dependencies",
         action="store_true",
-        help="Also pull and update dependencies",
+        help="Also pull and update dependencies.",
     )
-    subparser.add_argument(
+
+    _add_option_if_missing(
+        subparser,
         "--clone-mode",
         choices=["ssh", "https", "shallow"],
         default="ssh",
-        help=(
+        help="Specify clone mode (default: ssh).",
-            "Specify the clone mode: ssh, https, or shallow "
-            "(HTTPS shallow clone; default: ssh)"
-        ),
     )

src/pkgmgr/cli/parser/install_update.py

@@ -1,11 +1,12 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 
-from __future__ import annotations
-
 import argparse
 
-from .common import add_install_update_arguments, add_identifier_arguments
+from pkgmgr.cli.parser.common import (
+    add_install_update_arguments,
+    add_identifier_arguments,
+)
 
 
 def add_install_update_subparsers(
@@ -14,11 +15,17 @@ def add_install_update_subparsers(
     """
     Register install / update / deinstall / delete commands.
     """
+
     install_parser = subparsers.add_parser(
         "install",
         help="Setup repository/repositories alias links to executables",
     )
     add_install_update_arguments(install_parser)
+    install_parser.add_argument(
+        "--update",
+        action="store_true",
+        help="Force re-run installers (upgrade/refresh) even if the CLI layer is already loaded",
+    )
 
     update_parser = subparsers.add_parser(
         "update",
@@ -27,9 +34,11 @@ def add_install_update_subparsers(
     add_install_update_arguments(update_parser)
     update_parser.add_argument(
         "--system",
+        dest="system",
         action="store_true",
         help="Include system update commands",
     )
+    # No --update here: update implies force_update=True
 
     deinstall_parser = subparsers.add_parser(
         "deinstall",

src/pkgmgr/cli/parser/mirror_cmd.py

@@ -1,3 +1,4 @@
+# src/pkgmgr/cli/parser/mirror_cmd.py
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 
@@ -8,103 +9,55 @@ import argparse
 from .common import add_identifier_arguments
 
 
-def add_mirror_subparsers(
+def add_mirror_subparsers(subparsers: argparse._SubParsersAction) -> None:
-    subparsers: argparse._SubParsersAction,
-) -> None:
-    """
-    Register mirror command and its subcommands (list, diff, merge, setup).
-    """
     mirror_parser = subparsers.add_parser(
         "mirror",
-        help="Mirror-related utilities (list, diff, merge, setup)",
+        help="Mirror-related utilities (list, diff, merge, setup, check, provision)",
     )
     mirror_subparsers = mirror_parser.add_subparsers(
         dest="subcommand",
-        help="Mirror subcommands",
+        metavar="SUBCOMMAND",
         required=True,
     )
 
-    # ------------------------------------------------------------------
+    mirror_list = mirror_subparsers.add_parser("list", help="List configured mirrors for repositories")
-    # mirror list
-    # ------------------------------------------------------------------
-    mirror_list = mirror_subparsers.add_parser(
-        "list",
-        help="List configured mirrors for repositories",
-    )
     add_identifier_arguments(mirror_list)
     mirror_list.add_argument(
         "--source",
-        choices=["all", "config", "file", "resolved"],
+        choices=["config", "file", "all"],
         default="all",
         help="Which mirror source to show.",
     )
 
-    # ------------------------------------------------------------------
+    mirror_diff = mirror_subparsers.add_parser("diff", help="Show differences between config mirrors and MIRRORS file")
-    # mirror diff
-    # ------------------------------------------------------------------
-    mirror_diff = mirror_subparsers.add_parser(
-        "diff",
-        help="Show differences between config mirrors and MIRRORS file",
-    )
     add_identifier_arguments(mirror_diff)
 
-    # ------------------------------------------------------------------
-    # mirror merge {config,file} {config,file}
-    # ------------------------------------------------------------------
     mirror_merge = mirror_subparsers.add_parser(
         "merge",
-        help=(
+        help="Merge mirrors between config and MIRRORS file (example: pkgmgr mirror merge config file --all)",
-            "Merge mirrors between config and MIRRORS file "
-            "(example: pkgmgr mirror merge config file --all)"
-        ),
     )
-
+    mirror_merge.add_argument("source", choices=["config", "file"], help="Source of mirrors.")
-    # First define merge direction positionals, then selection args.
+    mirror_merge.add_argument("target", choices=["config", "file"], help="Target of mirrors.")
-    mirror_merge.add_argument(
-        "source",
-        choices=["config", "file"],
-        help="Source of mirrors.",
-    )
-    mirror_merge.add_argument(
-        "target",
-        choices=["config", "file"],
-        help="Target of mirrors.",
-    )
-
-    # Selection / filter / preview arguments
     add_identifier_arguments(mirror_merge)
-
     mirror_merge.add_argument(
         "--config-path",
-        help=(
+        help="Path to the user config file to update. If omitted, the global config path is used.",
-            "Path to the user config file to update. "
-            "If omitted, the global config path is used."
-        ),
     )
-    # Note: --preview, --all, --category, --tag, --list, etc. are provided
-    # by add_identifier_arguments().
 
-    # ------------------------------------------------------------------
-    # mirror setup
-    # ------------------------------------------------------------------
     mirror_setup = mirror_subparsers.add_parser(
         "setup",
-        help=(
+        help="Configure local Git remotes and push URLs (origin, pushurl list).",
-            "Setup mirror configuration for repositories.\n"
-            " --local  → configure local Git (remotes, pushurls)\n"
-            " --remote → create remote repositories if missing\n"
-            "Default: both local and remote."
-        ),
     )
     add_identifier_arguments(mirror_setup)
-    mirror_setup.add_argument(
+
-        "--local",
+    mirror_check = mirror_subparsers.add_parser(
-        action="store_true",
+        "check",
-        help="Only configure the local Git repository.",
+        help="Check remote mirror reachability (git ls-remote). Read-only.",
     )
-    mirror_setup.add_argument(
+    add_identifier_arguments(mirror_check)
-        "--remote",
+
-        action="store_true",
+    mirror_provision = mirror_subparsers.add_parser(
-        help="Only operate on remote repositories.",
+        "provision",
+        help="Provision remote repositories via provider APIs (create missing repos).",
     )
-    # Note: --preview also comes from add_identifier_arguments().
+    add_identifier_arguments(mirror_provision)

src/pkgmgr/cli/parser/publish_cmd.py

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

src/pkgmgr/core/command/layer.py

@@ -0,0 +1,30 @@
+# src/pkgmgr/core/command/layer.py
+from __future__ import annotations
+
+from enum import Enum
+
+
+class CliLayer(str, Enum):
+    """
+    CLI layer precedence (lower number = stronger layer).
+    """
+    OS_PACKAGES = "os-packages"
+    NIX = "nix"
+    PYTHON = "python"
+    MAKEFILE = "makefile"
+
+
+_LAYER_PRIORITY: dict[CliLayer, int] = {
+    CliLayer.OS_PACKAGES: 0,
+    CliLayer.NIX: 1,
+    CliLayer.PYTHON: 2,
+    CliLayer.MAKEFILE: 3,
+}
+
+
+def layer_priority(layer: CliLayer) -> int:
+    """
+    Return precedence priority for the given layer.
+    Lower value means higher priority (stronger layer).
+    """
+    return _LAYER_PRIORITY.get(layer, 999)

src/pkgmgr/core/command/run.py

@@ -1,8 +1,10 @@
+from __future__ import annotations
+
+import selectors
 import subprocess
 import sys
 from typing import List, Optional, Union
 
-
 CommandType = Union[str, List[str]]
 
 
@@ -13,32 +15,97 @@ def run_command(
     allow_failure: bool = False,
 ) -> subprocess.CompletedProcess:
     """
-    Run a command and optionally exit on error.
+    Run a command with live output while capturing stdout/stderr.
 
-    - If `cmd` is a string, it is executed with `shell=True`.
+    - Output is streamed live to the terminal.
-    - If `cmd` is a list of strings, it is executed without a shell.
+    - Output is captured in memory.
+    - On failure, captured stdout/stderr are printed again so errors are never lost.
+    - Command is executed exactly once.
     """
-    if isinstance(cmd, str):
+    display = cmd if isinstance(cmd, str) else " ".join(cmd)
-        display = cmd
-    else:
-        display = " ".join(cmd)
-
     where = cwd or "."
 
     if preview:
         print(f"[Preview] In '{where}': {display}")
-        # Fake a successful result; most callers ignore the return value anyway
         return subprocess.CompletedProcess(cmd, 0)  # type: ignore[arg-type]
 
     print(f"Running in '{where}': {display}")
 
-    if isinstance(cmd, str):
+    process = subprocess.Popen(
-        result = subprocess.run(cmd, cwd=cwd, shell=True)
+        cmd,
+        cwd=cwd,
+        shell=isinstance(cmd, str),
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        bufsize=1,
+    )
+
+    assert process.stdout is not None
+    assert process.stderr is not None
+
+    sel = selectors.DefaultSelector()
+    sel.register(process.stdout, selectors.EVENT_READ, data="stdout")
+    sel.register(process.stderr, selectors.EVENT_READ, data="stderr")
+
+    stdout_lines: List[str] = []
+    stderr_lines: List[str] = []
+
+    try:
+        while sel.get_map():
+            for key, _ in sel.select():
+                stream = key.fileobj
+                which = key.data
+
+                line = stream.readline()
+                if line == "":
+                    # EOF: stop watching this stream
+                    try:
+                        sel.unregister(stream)
+                    except Exception:
+                        pass
+                    continue
+
+                if which == "stdout":
+                    stdout_lines.append(line)
+                    print(line, end="")
                 else:
-        result = subprocess.run(cmd, cwd=cwd)
+                    stderr_lines.append(line)
+                    print(line, end="", file=sys.stderr)
+    finally:
+        # Ensure we don't leak FDs
+        try:
+            sel.close()
+        finally:
+            try:
+                process.stdout.close()
+            except Exception:
+                pass
+            try:
+                process.stderr.close()
+            except Exception:
+                pass
 
-    if result.returncode != 0 and not allow_failure:
+    returncode = process.wait()
-        print(f"Command failed with exit code {result.returncode}. Exiting.")
-        sys.exit(result.returncode)
 
-    return result
+    if returncode != 0 and not allow_failure:
+        print("\n[pkgmgr] Command failed, captured diagnostics:", file=sys.stderr)
+        print(f"[pkgmgr] Failed command: {display}", file=sys.stderr)
+
+        if stdout_lines:
+            print("----- stdout -----")
+            print("".join(stdout_lines), end="")
+
+        if stderr_lines:
+            print("----- stderr -----", file=sys.stderr)
+            print("".join(stderr_lines), end="", file=sys.stderr)
+
+        print(f"Command failed with exit code {returncode}. Exiting.")
+        sys.exit(returncode)
+
+    return subprocess.CompletedProcess(
+        cmd,
+        returncode,
+        stdout="".join(stdout_lines),
+        stderr="".join(stderr_lines),
+    )

src/pkgmgr/core/credentials/__init__.py

@@ -0,0 +1,21 @@
+# src/pkgmgr/core/credentials/__init__.py
+"""Credential resolution for provider APIs."""
+
+from .resolver import ResolutionOptions, TokenResolver
+from .types import (
+    CredentialError,
+    KeyringUnavailableError,
+    NoCredentialsError,
+    TokenRequest,
+    TokenResult,
+)
+
+__all__ = [
+    "TokenResolver",
+    "ResolutionOptions",
+    "CredentialError",
+    "NoCredentialsError",
+    "KeyringUnavailableError",
+    "TokenRequest",
+    "TokenResult",
+]

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

@@ -0,0 +1,11 @@
+"""Credential providers used by TokenResolver."""
+
+from .env import EnvTokenProvider
+from .keyring import KeyringTokenProvider
+from .prompt import PromptTokenProvider
+
+__all__ = [
+    "EnvTokenProvider",
+    "KeyringTokenProvider",
+    "PromptTokenProvider",
+]

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

@@ -0,0 +1,23 @@
+# src/pkgmgr/core/credentials/providers/env.py
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Optional
+
+from ..store_keys import env_var_candidates
+from ..types import TokenRequest, TokenResult
+
+
+@dataclass(frozen=True)
+class EnvTokenProvider:
+    """Resolve tokens from environment variables."""
+
+    source_name: str = "env"
+
+    def get(self, request: TokenRequest) -> Optional[TokenResult]:
+        for key in env_var_candidates(request.provider_kind, request.host, request.owner):
+            val = os.environ.get(key)
+            if val:
+                return TokenResult(token=val.strip(), source=self.source_name)
+        return None

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

@@ -0,0 +1,57 @@
+# src/pkgmgr/core/credentials/providers/keyring.py
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from ..store_keys import build_keyring_key
+from ..types import KeyringUnavailableError, TokenRequest, TokenResult
+
+
+def _import_keyring():
+    """
+    Import python-keyring.
+
+    Raises:
+      KeyringUnavailableError if:
+        - library is missing
+        - no backend is configured / usable
+        - import fails for any reason
+    """
+    try:
+        import keyring  # type: ignore
+    except Exception as exc:  # noqa: BLE001
+        raise KeyringUnavailableError(
+            "python-keyring is not installed."
+        ) from exc
+
+    # Some environments have keyring installed but no usable backend.
+    # We do a lightweight "backend sanity check" by attempting to read the backend.
+    try:
+        _ = keyring.get_keyring()
+    except Exception as exc:  # noqa: BLE001
+        raise KeyringUnavailableError(
+            "python-keyring is installed but no usable keyring backend is configured."
+        ) from exc
+
+    return keyring
+
+
+@dataclass(frozen=True)
+class KeyringTokenProvider:
+    """Resolve/store tokens from/to OS keyring via python-keyring."""
+
+    source_name: str = "keyring"
+
+    def get(self, request: TokenRequest) -> Optional[TokenResult]:
+        keyring = _import_keyring()
+        key = build_keyring_key(request.provider_kind, request.host, request.owner)
+        token = keyring.get_password(key.service, key.username)
+        if token:
+            return TokenResult(token=token.strip(), source=self.source_name)
+        return None
+
+    def set(self, request: TokenRequest, token: str) -> None:
+        keyring = _import_keyring()
+        key = build_keyring_key(request.provider_kind, request.host, request.owner)
+        keyring.set_password(key.service, key.username, token)

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

@@ -0,0 +1,68 @@
+# src/pkgmgr/core/credentials/providers/prompt.py
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass
+from getpass import getpass
+from typing import Optional
+
+from ..types import TokenRequest, TokenResult
+
+
+def _token_help_url(provider_kind: str, host: str) -> Optional[str]:
+    """
+    Return a provider-specific URL where a user can create/get an API token.
+
+    Keep this conservative and stable:
+    - GitHub: official token settings URL
+    - Gitea/Forgejo: common settings path on the given host
+    - GitLab: common personal access token path
+    """
+    kind = (provider_kind or "").strip().lower()
+    h = (host or "").strip()
+
+    # GitHub (cloud)
+    if kind == "github":
+        return "https://github.com/settings/tokens"
+
+    # Gitea / Forgejo (self-hosted)
+    if kind in ("gitea", "forgejo"):
+        # Typical UI path: Settings -> Applications -> Access Tokens
+        # In many installations this is available at /user/settings/applications
+        base = f"https://{h}".rstrip("/")
+        return f"{base}/user/settings/applications"
+
+    # GitLab (cloud or self-hosted)
+    if kind == "gitlab":
+        base = "https://gitlab.com" if not h else f"https://{h}".rstrip("/")
+        return f"{base}/-/profile/personal_access_tokens"
+
+    return None
+
+
+@dataclass(frozen=True)
+class PromptTokenProvider:
+    """Interactively prompt for a token.
+
+    Only used when:
+    - interactive mode is enabled
+    - stdin is a TTY
+    """
+
+    source_name: str = "prompt"
+
+    def get(self, request: TokenRequest) -> Optional[TokenResult]:
+        if not sys.stdin.isatty():
+            return None
+
+        owner_info = f" (owner: {request.owner})" if request.owner else ""
+        help_url = _token_help_url(request.provider_kind, request.host)
+
+        if help_url:
+            print(f"[INFO] Create/get your token here: {help_url}")
+
+        prompt = f"Enter API token for {request.provider_kind} on {request.host}{owner_info}: "
+        token = (getpass(prompt) or "").strip()
+        if not token:
+            return None
+        return TokenResult(token=token, source=self.source_name)

src/pkgmgr/core/credentials/resolver.py

@@ -0,0 +1,96 @@
+# src/pkgmgr/core/credentials/resolver.py
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass
+from typing import Optional
+
+from .providers.env import EnvTokenProvider
+from .providers.keyring import KeyringTokenProvider
+from .providers.prompt import PromptTokenProvider
+from .types import KeyringUnavailableError, NoCredentialsError, TokenRequest, TokenResult
+
+
+@dataclass(frozen=True)
+class ResolutionOptions:
+    """Controls token resolution behavior."""
+
+    interactive: bool = True
+    allow_prompt: bool = True
+    save_prompt_token_to_keyring: bool = True
+
+
+class TokenResolver:
+    """Resolve tokens from multiple sources (ENV -> Keyring -> Prompt)."""
+
+    def __init__(self) -> None:
+        self._env = EnvTokenProvider()
+        self._keyring = KeyringTokenProvider()
+        self._prompt = PromptTokenProvider()
+        self._warned_keyring: bool = False
+
+    def _warn_keyring_unavailable(self, exc: Exception) -> None:
+        if self._warned_keyring:
+            return
+        self._warned_keyring = True
+
+        msg = str(exc).strip() or "Keyring is unavailable."
+        print("[WARN] Keyring support is not available.", file=sys.stderr)
+        print(f"       {msg}", file=sys.stderr)
+        print("       Tokens will NOT be persisted securely.", file=sys.stderr)
+        print("", file=sys.stderr)
+        print("       To enable secure token storage, install python-keyring:", file=sys.stderr)
+        print("         pip install keyring", file=sys.stderr)
+        print("", file=sys.stderr)
+        print("       Or install via system packages:", file=sys.stderr)
+        print("         sudo apt install python3-keyring", file=sys.stderr)
+        print("         sudo pacman -S python-keyring", file=sys.stderr)
+        print("         sudo dnf install python3-keyring", file=sys.stderr)
+        print("", file=sys.stderr)
+
+    def get_token(
+        self,
+        provider_kind: str,
+        host: str,
+        owner: Optional[str] = None,
+        options: Optional[ResolutionOptions] = None,
+    ) -> TokenResult:
+        opts = options or ResolutionOptions()
+        request = TokenRequest(provider_kind=provider_kind, host=host, owner=owner)
+
+        # 1) ENV
+        env_res = self._env.get(request)
+        if env_res:
+            return env_res
+
+        # 2) Keyring
+        try:
+            kr_res = self._keyring.get(request)
+            if kr_res:
+                return kr_res
+        except KeyringUnavailableError as exc:
+            # Show a helpful warning once, then continue (prompt fallback).
+            self._warn_keyring_unavailable(exc)
+        except Exception:
+            # Unknown keyring errors: do not block prompting; still avoid hard crash.
+            pass
+
+        # 3) Prompt (optional)
+        if opts.interactive and opts.allow_prompt:
+            prompt_res = self._prompt.get(request)
+            if prompt_res:
+                if opts.save_prompt_token_to_keyring:
+                    try:
+                        self._keyring.set(request, prompt_res.token)
+                    except KeyringUnavailableError as exc:
+                        self._warn_keyring_unavailable(exc)
+                    except Exception:
+                        # If keyring cannot store, still use token for this run.
+                        pass
+                return prompt_res
+
+        raise NoCredentialsError(
+            f"No token available for {provider_kind}@{host}"
+            + (f" (owner: {owner})" if owner else "")
+            + ". Provide it via environment variable or keyring."
+        )