Release version 1.8.2

* Move VS Code workspace logic (incl. guards) from cli.commands.tools into cli.tools.vscode
* Extract shared repo path resolution into cli.tools.paths and reuse for explore/terminal
* Simplify cli.commands.tools to pure orchestration via open_vscode_workspace
* Update existing tools command unit test to assert delegation instead of patching removed internals
* Add new unit tests for cli.tools.paths and cli.tools.vscode (workspace creation, reuse, guard errors)

https://chatgpt.com/share/69419a6a-c9e4-800f-9538-b6652b2da6b3

.github/workflows/ci.yml

@@ -27,3 +27,9 @@ jobs:
 
   test-virgin-root:
     uses: ./.github/workflows/test-virgin-root.yml
+
+  lint-shell:
+    uses: ./.github/workflows/lint-shell.yml
+
+  lint-python:
+    uses: ./.github/workflows/lint-python.yml

.github/workflows/lint-python.yml

@@ -0,0 +1,23 @@
+name: Ruff (Python code sniffer)
+
+on:
+  workflow_call:
+
+jobs:
+  lint-python:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install ruff
+        run: pip install ruff
+
+      - name: Run ruff
+        run: |
+          ruff check src tests

.github/workflows/lint-shell.yml

@@ -0,0 +1,14 @@
+name: ShellCheck
+
+on:
+  workflow_call:
+
+jobs:
+  lint-shell:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install ShellCheck
+        run: sudo apt-get update && sudo apt-get install -y shellcheck
+      - name: Run ShellCheck
+        run: shellcheck -x $(find scripts -type f -name '*.sh' -print)

.github/workflows/mark-stable.yml

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

.github/workflows/publish-containers.yml

@@ -1,12 +1,13 @@
 name: Publish container images (GHCR)
 
 on:
-  push:
-    tags:
-      - "v*"
+  workflow_run:
+    workflows: ["Mark stable commit"]
+    types: [completed]
 
 jobs:
   publish:
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
     runs-on: ubuntu-latest
 
     permissions:
@@ -18,29 +19,45 @@ jobs:
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
-          fetch-tags: true
+
+      - name: Checkout workflow_run commit and refresh tags
+        run: |
+          set -euo pipefail
+          git checkout -f "${{ github.event.workflow_run.head_sha }}"
+          git fetch --tags --force
+          git tag --list 'stable' 'v*' --sort=version:refname | tail -n 20
 
       - name: Compute version and stable flag
         id: info
         run: |
           set -euo pipefail
-
           SHA="$(git rev-parse HEAD)"
-          VERSION="${GITHUB_REF_NAME#v}"
+
+          V_TAG="$(git tag --points-at "${SHA}" --list 'v*' | sort -V | tail -n1)"
+          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
@@ -48,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,6 +1,113 @@
+## [1.8.2] - 2025-12-16
+
+* * ***pkgmgr tools code*** is more robust and predictable: it now fails early with clear errors if VS Code is not installed or a repository is not yet identified.
+
+
+## [1.8.1] - 2025-12-16
+
+* * Improved stability and consistency of all Git operations (clone, pull, push, release, branch handling) with clearer error messages and predictable preview behavior.
+* Mirrors are now handled cleanly: only valid Git remotes are used for Git operations, while non-Git URLs (e.g. PyPI) are excluded, preventing broken or confusing repository configs.
+* GitHub authentication is more robust: tokens are automatically resolved via the GitHub CLI (`gh`), invalid stored tokens are replaced, and interactive prompts occur only when necessary.
+* Repository creation and release workflows are more reliable, producing cleaner Git configurations and more predictable version handling.
+
+
+## [1.8.0] - 2025-12-15
+
+* *** New Features: ***
+- **Silent Updates**: You can now use the `--silent` flag during installs and updates to suppress error messages for individual repositories and get a single summary at the end. This ensures the process continues even if some repositories fail, while still preserving interactive checks when not in silent mode.
+- **Repository Scaffolding**: The process for creating new repositories has been improved. You can now use templates to scaffold repositories with a preview and automatic mirror setup.
+
+*** Bug Fixes: ***
+- **Pip Installation**: Pip is now installed automatically on all supported systems. This includes `python-pip` for Arch and `python3-pip` for CentOS, Debian, Fedora, and Ubuntu, ensuring that pip is available for Python package installations.
+- **Pacman Keyring**: Fixed an issue on Arch Linux where package installation would fail due to missing keys. The pacman keyring is now properly initialized before installing packages.
+
+
+## [1.7.2] - 2025-12-15
+
+* * Git mirrors are now resolved consistently (origin → MIRRORS file → config → default).
+* The `origin` remote is always enforced to use the primary URL for both fetch and push.
+* Additional mirrors are added as extra push targets without duplication.
+* Local and remote mirror setup behaves more predictably and consistently.
+* Improved test coverage ensures stable origin and push URL handling.
+
+
+## [1.7.1] - 2025-12-14
+
+* Patched package-manager to kpmx to publish on pypi
+
+
+## [1.7.0] - 2025-12-14
+
+* * New *pkgmgr publish* command to publish repository artifacts to PyPI based on the *MIRRORS* file.
+* Automatically selects the current repository when no explicit selection is given.
+* Publishes only when a semantic version tag is present on *HEAD*; otherwise skips with a clear info message.
+* Supports non-interactive mode for CI environments via *--non-interactive*.
+
+
+## [1.6.4] - 2025-12-14
+
+* * Improved reliability of Nix installs and updates, including automatic resolution of profile conflicts and better handling of GitHub 403 rate limits.
+* More stable launcher behavior in packaged and virtual-env setups.
+* Enhanced mirror and remote handling: repository owner/name are derived from URLs, with smoother provisioning and clearer credential handling.
+* More reliable releases and artifacts due to safer CI behavior when no version tag is present.
+
+
+## [1.6.3] - 2025-12-14
+
+* ***Fixed:*** Corrected repository path resolution so release and version logic consistently use the canonical packaging/* layout, preventing changelog and packaging files from being read or updated from incorrect locations.
+
+
+## [1.6.2] - 2025-12-14
+
+* **pkgmgr version** now also shows the installed pkgmgr version when run outside a repository.
+
+
+## [1.6.1] - 2025-12-14
+
+* * Added automatic retry handling for GitHub 403 / rate-limit errors during Nix flake installs (Fibonacci backoff with jitter).
+
+
+## [1.6.0] - 2025-12-14
+
+* *** Changed ***
+- Unified update handling via a single top-level `pkgmgr update` command, removing ambiguous update paths.
+- Improved update reliability by routing all update logic through a central UpdateManager.
+- Renamed system update flag from `--system-update` to `--system` for clarity and consistency.
+- Made mirror handling explicit and safer by separating setup, check, and provision responsibilities.
+- Improved credential resolution for remote providers (environment → keyring → interactive).
+
+*** Added ***
+- Optional system updates via `pkgmgr update --system` (Arch, Debian/Ubuntu, Fedora/RHEL).
+- `pkgmgr install --update` to force re-running installers and refresh existing installations.
+- Remote repository provisioning for mirrors on supported providers.
+- Extended end-to-end test coverage for update and mirror workflows.
+
+*** Fixed ***
+- Resolved “Unknown repos command: update” errors after CLI refactoring.
+- Improved Nix update stability and reduced CI failures caused by transient rate limits.
+
+
+## [1.5.0] - 2025-12-13
+
+* - Commands now show live output while running, making long operations easier to follow
+- Error messages include full command output, making failures easier to understand and debug
+- Deinstallation is more complete and predictable, removing CLI links and properly cleaning up repositories
+- Preview mode is more trustworthy, clearly showing what would happen without making changes
+- Repository configuration problems are detected earlier with clear, user-friendly explanations
+- More consistent behavior across different Linux distributions
+- More reliable execution in Docker containers and CI environments
+- Nix-based execution works more smoothly, especially when running as root or inside containers
+- Existing commands, scripts, and workflows continue to work without any breaking changes
+
+
+## [1.4.1] - 2025-12-12
+
+* Fixed stable release container publishing
+
+
 ## [1.4.0] - 2025-12-12
 
-* **Docker Container Building**
+**Docker Container Building**
 
 * New official container images are automatically published on each release.
 * Images are available per distribution and as a default Arch-based image.
@@ -14,7 +121,7 @@
 
 ## [1.3.0] - 2025-12-12
 
-* **Minor release – Stability & CI hardening**
+**Stability & CI hardening**
 
 * Stabilized Nix resolution and global symlink handling across Arch, CentOS, Debian, and Ubuntu
 * Ensured Nix works reliably in CI, sudo, login, and non-login shells without overriding distro-managed paths
@@ -26,7 +133,7 @@
 
 ## [1.2.1] - 2025-12-12
 
-* **Changed**
+**Changed**
 
 * Split container tests into *virtualenv* and *Nix flake* environments to clearly separate Python and Nix responsibilities.
 
@@ -43,7 +150,7 @@
 
 ## [1.2.0] - 2025-12-12
 
-* **Release workflow overhaul**
+**Release workflow overhaul**
 
 * Introduced a fully structured release workflow with clear phases and safeguards
 * Added preview-first releases with explicit confirmation before execution
@@ -60,7 +167,8 @@
 
 ## [1.0.0] - 2025-12-11
 
-* **1.0.0 – Official Stable Release 🎉**
+**Official Stable Release 🎉**
+
 *First stable release of PKGMGR, the multi-distro development and package workflow manager.*
 
 ---
@@ -153,7 +261,7 @@ PKGMGR 1.0.0 unifies repository management, build tooling, release automation an
 
 ## [0.9.1] - 2025-12-10
 
-* * Refactored installer: new `venv-create.sh`, cleaner root/user setup flow, updated README with architecture map.
+* 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.
 * Fixed repository directory resolution; improved `pkgmgr path` and `pkgmgr shell`; added full unit/E2E coverage.
 * Removed deprecated files and updated `.gitignore`.
@@ -248,47 +356,45 @@ PKGMGR 1.0.0 unifies repository management, build tooling, release automation an
 
 ## [0.7.1] - 2025-12-09
 
-* Fix floating 'latest' tag logic: dereference annotated target (vX.Y.Z^{}), add tag message to avoid Git errors, ensure best-effort update without blocking releases, and update unit tests (see ChatGPT conversation: https://chatgpt.com/share/69383024-efa4-800f-a875-129b81fa40ff).
-
+* Fix floating 'latest' tag logic
+* dereference annotated target (vX.Y.Z^{})
+* add tag message to avoid Git errors
+* ensure best-effort update without blocking releases
 
 ## [0.7.0] - 2025-12-09
 
-* Add Git helpers for branch sync and floating 'latest' tag in the release workflow, ensure main/master are updated from origin before tagging, and extend unit/e2e tests including 'pkgmgr release --help' coverage (see ChatGPT conversation: https://chatgpt.com/share/69383024-efa4-800f-a875-129b81fa40ff)
-
+* Add Git helpers for branch sync and floating 'latest' tag in the release workflow
+* ensure main/master are updated from origin before tagging
 
 ## [0.6.0] - 2025-12-09
 
-* Expose DISTROS and BASE_IMAGE_* variables as exported Makefile environment variables so all build and test commands can consume them dynamically. By exporting these values, every Make target (e.g., build, build-no-cache, build-missing, test-container, test-unit, test-e2e) and every delegated script in scripts/build/ and scripts/test/ now receives a consistent view of the supported distributions and their base container images. This change removes duplicated definitions across scripts, ensures reproducible builds, and allows build tooling to react automatically when new distros or base images are added to the Makefile.
-
+* Consistent view of the supported distributions and their base container images. 
 
 ## [0.5.1] - 2025-12-09
 
-* Refine pkgmgr release CLI close wiring and integration tests for --close flag (ChatGPT: https://chatgpt.com/share/69376b4e-8440-800f-9d06-535ec1d7a40e)
+* Refine pkgmgr release CLI close wiring and integration tests for --close flag
 
 
 ## [0.5.0] - 2025-12-09
 
-* Add pkgmgr branch close subcommand, extend CLI parser wiring, and add unit tests for branch handling and version version-selection logic (see ChatGPT conversation: https://chatgpt.com/share/693762a3-9ea8-800f-a640-bc78170953d1)
-
+* Add pkgmgr branch close subcommand, extend CLI parser wiring
 
 ## [0.4.3] - 2025-12-09
 
-* Implement current-directory repository selection for release and proxy commands, unify selection semantics across CLI layers, extend release workflow with --close, integrate branch closing logic, fix wiring for get_repo_identifier/get_repo_dir, update packaging files (PKGBUILD, spec, flake.nix, pyproject), and add comprehensive unit/e2e tests for release and branch commands (see ChatGPT conversation: https://chatgpt.com/share/69375cfe-9e00-800f-bd65-1bd5937e1696)
-
+* Implement current-directory repository selection for release and proxy commands, unify selection semantics across CLI layers, extend release workflow with --close, integrate branch closing logic, fix wiring for get_repo_identifier/get_repo_dir, update packaging files (PKGBUILD, spec, flake.nix, pyproject)
 
 ## [0.4.2] - 2025-12-09
 
-* Wire pkgmgr release CLI to new helper and add unit tests (see ChatGPT conversation: https://chatgpt.com/share/69374f09-c760-800f-92e4-5b44a4510b62)
+* Wire pkgmgr release CLI to new helpe
 
 
 ## [0.4.1] - 2025-12-08
 
-* Add branch close subcommand and integrate release close/editor flow (ChatGPT: https://chatgpt.com/share/69374f09-c760-800f-92e4-5b44a4510b62)
-
+* Add branch close subcommand and integrate release close/editor flow
 
 ## [0.4.0] - 2025-12-08
 
-* Add branch closing helper and --close flag to release command, including CLI wiring and tests (see https://chatgpt.com/share/69374aec-74ec-800f-bde3-5d91dfdb9b91)
+* Add branch closing helper and --close flag to release command
 
 ## [0.3.0] - 2025-12-08
 
@@ -299,13 +405,10 @@ PKGMGR 1.0.0 unifies repository management, build tooling, release automation an
 - New config update logic + default YAML sync
 - Improved proxy command handling
 - Full CLI routing refactor
-- Expanded E2E tests for list, proxy, and selection logic
-Konversation: https://chatgpt.com/share/693745c3-b8d8-800f-aa29-c8481a2ffae1
 
 ## [0.2.0] - 2025-12-08
 
-* Add preview-first release workflow and extended packaging support (see ChatGPT conversation: https://chatgpt.com/share/693722b4-af9c-800f-bccc-8a4036e99630)
-
+* Add preview-first release workflow and extended packaging support
 
 ## [0.1.0] - 2025-12-08
 
@@ -314,5 +417,4 @@ Konversation: https://chatgpt.com/share/693745c3-b8d8-800f-aa29-c8481a2ffae1
 
 ## [0.1.0] - 2025-12-08
 
-* Implement unified release helper with preview mode, multi-packaging version bumps, and new integration/unit tests (see ChatGPT conversation 2025-12-08: https://chatgpt.com/share/693722b4-af9c-800f-bccc-8a4036e99630)
-
+* Implement unified release helper with preview mode, multi-packaging version bumps

Dockerfile

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

MIRRORS

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

Makefile

@@ -7,8 +7,8 @@
 # Distro
 # Options: arch debian ubuntu fedora centos
 DISTROS ?= arch debian ubuntu fedora centos
-distro ?= arch
-export distro
+PKGMGR_DISTRO ?= arch
+export PKGMGR_DISTRO
 
 # ------------------------------------------------------------
 # Base images
@@ -30,6 +30,7 @@ export BASE_IMAGE_CENTOS
 # PYthon Unittest Pattern
 TEST_PATTERN	:= test_*.py
 export TEST_PATTERN
+export PYTHONPATH := src
 
 # ------------------------------------------------------------
 # System install
@@ -43,9 +44,9 @@ install:
 # ------------------------------------------------------------
 
 # Default: keep current auto-detection behavior
-setup: setup-nix setup-venv
+setup: setup-venv
 
-# Explicit: developer setup (Python venv + shell RC + main.py install)
+# Explicit: developer setup (Python venv + shell RC + install)
 setup-venv: setup-nix
 	@bash scripts/setup/venv.sh
 
@@ -74,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
 
 # ------------------------------------------------------------
@@ -100,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
 

README.md

@@ -25,52 +25,37 @@ together into repeatable development workflows.
 
 Traditional distro package managers like `apt`, `pacman` or `dnf` focus on a
 single operating system. PKGMGR instead focuses on **your repositories and
-development lifecycle**:
+development lifecycle**. It provides one configuration for all repositories,
+one unified CLI to interact with them, and a Nix-based foundation that keeps
+tooling reproducible across distributions.
 
-* one configuration for all your repos,
-* one CLI to interact with them,
-* one Nix-based layer to keep tooling reproducible across distros.
+Native package managers are still used where they make sense. PKGMGR coordinates
+the surrounding development, build and release workflows in a consistent way.
 
-You keep using your native package manager where it makes sense – PKGMGR
-coordinates the *development and release flow* around it.
+In addition, PKGMGR provides Docker images that can serve as a **reproducible
+system baseline**. These images bundle the complete PKGMGR toolchain and are
+designed to be reused as a stable execution environment across machines,
+pipelines and teams. This approach is specifically used within
+[**Infinito.Nexus**](https://s.infinito.nexus/code) to make complex systems
+distribution-independent while remaining fully reproducible.
 
 ---
 
 ## Features 🚀
 
-### Multi-distro development & packaging
+PKGMGR enables multi-distro development and packaging by managing multiple
+repositories from a single configuration file. It drives complete release
+pipelines across Linux distributions using Nix flakes, Python build metadata,
+native OS packages such as Arch, Debian and RPM formats, and additional ecosystem
+integrations like Ansible.
 
-* Manage **many repositories at once** from a single `config/config.yaml`.
-* Drive full **release pipelines** across Linux distributions using:
+All functionality is exposed through a unified `pkgmgr` command-line interface
+that works identically on every supported distribution. It combines repository
+management, Git operations, Docker and Compose orchestration, as well as
+versioning, release and changelog workflows. Many commands support a preview
+mode, allowing you to inspect the underlying actions before they are executed.
 
-  * Nix flakes (`flake.nix`)
-  * PyPI style builds (`pyproject.toml`)
-  * OS packages (PKGBUILD, Debian control/changelog, RPM spec)
-  * Ansible Galaxy metadata and more.
-
-### Rich CLI for daily work
-
-All commands are exposed via the `pkgmgr` CLI and are available on every distro:
-
-* **Repository management**
-
-  * `clone`, `update`, `install`, `delete`, `deinstall`, `path`, `list`, `config`
-* **Git proxies**
-
-  * `pull`, `push`, `status`, `diff`, `add`, `show`, `checkout`,
-    `reset`, `revert`, `rebase`, `commit`, `branch`
-* **Docker & Compose orchestration**
-
-  * `build`, `up`, `down`, `exec`, `ps`, `start`, `stop`, `restart`
-* **Release toolchain**
-
-  * `version`, `release`, `changelog`, `make`
-* **Mirror & workflow helpers**
-
-  * `mirror` (list/diff/merge/setup), `shell`, `terminal`, `code`, `explore`
-
-Many of these commands support `--preview` mode so you can inspect the
-underlying Git or Docker calls without executing them.
+---
 
 ### Full development workflows
 
@@ -83,10 +68,6 @@ versioning features it can drive **end-to-end workflows**:
 4. Build distro-specific packages.
 5. Keep all mirrors and working copies in sync.
 
-The extensive E2E tests (`tests/e2e/`) and GitHub Actions workflows (including
-“virgin user” and “virgin root” Arch tests) validate these flows across
-different Linux environments.
-
 ---
 
 ## Architecture & Setup Map 🗺️
@@ -99,25 +80,26 @@ The following diagram gives a full overview of:
 
 ![PKGMGR Architecture](assets/map.png)
 
+
 **Diagram status:** 12 December 2025
+
 **Always-up-to-date version:** [https://s.veen.world/pkgmgrmp](https://s.veen.world/pkgmgrmp)
 
 ---
 
-Perfekt, dann hier die **noch kompaktere und korrekt differenzierte Version**, die **nur** zwischen
-**`make setup`** und **`make setup-venv`** unterscheidet und exakt deinem Verhalten entspricht.
-
-README-ready, ohne Over-Engineering.
-
----
-
 ## Installation ⚙️
 
 PKGMGR can be installed using `make`.
 The setup mode defines **which runtime layers are prepared**.
-
 ---
 
+### Download
+
+```bash
+git clone https://github.com/kevinveenbirkenbach/package-manager.git
+cd package-manager
+```
+
 ### Dependency installation (optional)
 
 System dependencies required **before running any *make* commands** are installed via:
@@ -128,8 +110,13 @@ scripts/installation/dependencies.sh
 
 The script detects and normalizes the OS and installs the required **system-level dependencies** accordingly.
 
+### Install
 
----
+```bash
+git clone https://github.com/kevinveenbirkenbach/package-manager.git
+cd package-manager
+make install
+```
 
 ### Setup modes
 
@@ -138,17 +125,8 @@ The script detects and normalizes the OS and installs the required **system-leve
 | **make setup**      | Python venv **and** Nix | Full development & CI |
 | **make setup-venv** | Python venv only        | Local user setup      |
 
----
 
-### Install & setup
-
-```bash
-git clone https://github.com/kevinveenbirkenbach/package-manager.git
-cd package-manager
-make install
-```
-
-#### Full setup (venv + Nix)
+##### Full setup (venv + Nix)
 
 ```bash
 make setup
@@ -156,7 +134,7 @@ make setup
 
 Use this for CI, servers, containers and full development workflows.
 
-#### Venv-only setup
+##### Venv-only setup
 
 ```bash
 make setup-venv
@@ -167,38 +145,77 @@ Use this if you want PKGMGR isolated without Nix integration.
 
 ---
 
-## Run without installation (Nix)
+Alles klar 🙂
+Hier ist der **RUN-Abschnitt ohne Gedankenstriche**, klar nach **Nix, Docker und venv** getrennt:
 
-Run PKGMGR directly via Nix Flakes.
+---
+
+## Run PKGMGR 🧰
+
+PKGMGR can be executed in different environments.
+All modes expose the same CLI and commands.
+
+---
+
+### Run via Nix (no installation)
 
 ```bash
 nix run github:kevinveenbirkenbach/package-manager#pkgmgr -- --help
 ```
 
-Example:
+---
 
-```bash
-nix run github:kevinveenbirkenbach/package-manager#pkgmgr -- version pkgmgr
-```
+### Run via Docker 🐳
 
-Notes:
+PKGMGR can be executed **inside Docker containers** for CI, testing and isolated
+workflows.
+---
 
-* full flake URL required
-* `--` separates Nix and PKGMGR arguments
-* can be used alongside any setup mode
+#### Container types
+
+Two container types are available.
+
+
+| Image type | Contains                      | Typical use             |
+| ---------- | ----------------------------- | ----------------------- |
+| **Virgin** | Base OS + system dependencies | Clean test environments |
+| **Stable** | PKGMGR + Nix (flakes enabled) | Ready-to-use workflows  |
+
+Example images:
+
+* Virgin: `pkgmgr-arch-virgin`
+* Stable: `ghcr.io/kevinveenbirkenbach/pkgmgr:stable`
+
+
+Use **virgin images** for isolated test runs,
+use the **stable image** for fast, reproducible execution.
 
 ---
 
-## Usage 🧰
+#### Run examples
 
-After installation, the main entry point is:
+```bash
+docker run --rm -it \
+  -v "$PWD":/src \
+  -w /src \
+  ghcr.io/kevinveenbirkenbach/pkgmgr:stable \
+  pkgmgr --help
+```
+
+---
+
+### Run via virtual environment (venv)
+
+After activating the venv:
 
 ```bash
 pkgmgr --help
 ```
 
-This prints a list of all available subcommands.
-The help for each command is available via:
+---
+
+This allows you to choose between zero install execution using Nix, fully prebuilt
+Docker environments or local isolated venv setups with identical command behavior.
 
 ---
 

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.0";
+            version = "1.8.2";
 
             # Use the git repo as source
             src = ./.;
@@ -53,6 +49,7 @@
             # Runtime dependencies (matches [project.dependencies] in pyproject.toml)
             propagatedBuildInputs = [
               pyPkgs.pyyaml
+              pyPkgs.jinja2
               pyPkgs.pip
             ];
 
@@ -82,6 +79,7 @@
           pythonWithDeps = python.withPackages (ps: [
             ps.pip
             ps.pyyaml
+            ps.jinja2
           ]);
         in
         {

main.py

@@ -1,14 +0,0 @@
-#!/usr/bin/env python3
-import sys
-from pathlib import Path
-
-# Ensure local src/ overrides installed package
-ROOT = Path(__file__).resolve().parent
-SRC = ROOT / "src"
-if SRC.is_dir():
-    sys.path.insert(0, str(SRC))
-
-from pkgmgr.cli import main
-
-if __name__ == "__main__":
-    main()

packaging/arch/PKGBUILD

@@ -1,7 +1,7 @@
 # Maintainer: Kevin Veen-Birkenbach <info@veen.world>
 
 pkgname=package-manager
-pkgver=0.9.1
+pkgver=1.8.2
 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,70 @@
+package-manager (1.8.2-1) unstable; urgency=medium
+
+  * * ***pkgmgr tools code*** is more robust and predictable: it now fails early with clear errors if VS Code is not installed or a repository is not yet identified.
+
+ -- Kevin Veen-Birkenbach <kevin@veen.world>  Tue, 16 Dec 2025 19:22:41 +0100
+
+package-manager (1.8.1-1) unstable; urgency=medium
+
+  * * Improved stability and consistency of all Git operations (clone, pull, push, release, branch handling) with clearer error messages and predictable preview behavior.
+* Mirrors are now handled cleanly: only valid Git remotes are used for Git operations, while non-Git URLs (e.g. PyPI) are excluded, preventing broken or confusing repository configs.
+* GitHub authentication is more robust: tokens are automatically resolved via the GitHub CLI (`gh`), invalid stored tokens are replaced, and interactive prompts occur only when necessary.
+* Repository creation and release workflows are more reliable, producing cleaner Git configurations and more predictable version handling.
+
+ -- Kevin Veen-Birkenbach <kevin@veen.world>  Tue, 16 Dec 2025 18:06:35 +0100
+
+package-manager (1.8.0-1) unstable; urgency=medium
+
+  * *** New Features: ***
+- **Silent Updates**: You can now use the `--silent` flag during installs and updates to suppress error messages for individual repositories and get a single summary at the end. This ensures the process continues even if some repositories fail, while still preserving interactive checks when not in silent mode.
+- **Repository Scaffolding**: The process for creating new repositories has been improved. You can now use templates to scaffold repositories with a preview and automatic mirror setup.
+
+*** Bug Fixes: ***
+- **Pip Installation**: Pip is now installed automatically on all supported systems. This includes `python-pip` for Arch and `python3-pip` for CentOS, Debian, Fedora, and Ubuntu, ensuring that pip is available for Python package installations.
+- **Pacman Keyring**: Fixed an issue on Arch Linux where package installation would fail due to missing keys. The pacman keyring is now properly initialized before installing packages.
+
+ -- Kevin Veen-Birkenbach <kevin@veen.world>  Mon, 15 Dec 2025 13:37:42 +0100
+
+package-manager (1.7.2-1) unstable; urgency=medium
+
+  * * Git mirrors are now resolved consistently (origin → MIRRORS file → config → default).
+* The `origin` remote is always enforced to use the primary URL for both fetch and push.
+* Additional mirrors are added as extra push targets without duplication.
+* Local and remote mirror setup behaves more predictably and consistently.
+* Improved test coverage ensures stable origin and push URL handling.
+
+ -- Kevin Veen-Birkenbach <kevin@veen.world>  Mon, 15 Dec 2025 00:53:26 +0100
+
+package-manager (1.7.1-1) unstable; urgency=medium
+
+  * Patched package-manager to kpmx to publish on pypi
+
+ -- Kevin Veen-Birkenbach <kevin@veen.world>  Sun, 14 Dec 2025 21:19:11 +0100
+
+package-manager (1.7.0-1) unstable; urgency=medium
+
+  * * New *pkgmgr publish* command to publish repository artifacts to PyPI based on the *MIRRORS* file.
+* Automatically selects the current repository when no explicit selection is given.
+* Publishes only when a semantic version tag is present on *HEAD*; otherwise skips with a clear info message.
+* Supports non-interactive mode for CI environments via *--non-interactive*.
+
+ -- Kevin Veen-Birkenbach <kevin@veen.world>  Sun, 14 Dec 2025 21:10:06 +0100
+
+package-manager (1.6.4-1) unstable; urgency=medium
+
+  * * Improved reliability of Nix installs and updates, including automatic resolution of profile conflicts and better handling of GitHub 403 rate limits.
+* More stable launcher behavior in packaged and virtual-env setups.
+* Enhanced mirror and remote handling: repository owner/name are derived from URLs, with smoother provisioning and clearer credential handling.
+* More reliable releases and artifacts due to safer CI behavior when no version tag is present.
+
+ -- Kevin Veen-Birkenbach <kevin@veen.world>  Sun, 14 Dec 2025 19:33:07 +0100
+
+package-manager (1.6.3-1) unstable; urgency=medium
+
+  * ***Fixed:*** Corrected repository path resolution so release and version logic consistently use the canonical packaging/* layout, preventing changelog and packaging files from being read or updated from incorrect locations.
+
+ -- Kevin Veen-Birkenbach <kevin@veen.world>  Sun, 14 Dec 2025 13:39:52 +0100
+
 package-manager (0.9.1-1) unstable; urgency=medium
 
   * * Refactored installer: new `venv-create.sh`, cleaner root/user setup flow, updated README with architecture map.

packaging/debian/rules

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

packaging/fedora/package-manager.spec

@@ -1,5 +1,5 @@
 Name:           package-manager
-Version:        0.9.1
+Version:        1.8.2
 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,49 @@ echo ">>> package-manager removed. Nix itself was not removed."
 /usr/lib/package-manager/
 
 %changelog
+* Tue Dec 16 2025 Kevin Veen-Birkenbach <kevin@veen.world> - 1.8.2-1
+- * ***pkgmgr tools code*** is more robust and predictable: it now fails early with clear errors if VS Code is not installed or a repository is not yet identified.
+
+* Tue Dec 16 2025 Kevin Veen-Birkenbach <kevin@veen.world> - 1.8.1-1
+- * Improved stability and consistency of all Git operations (clone, pull, push, release, branch handling) with clearer error messages and predictable preview behavior.
+* Mirrors are now handled cleanly: only valid Git remotes are used for Git operations, while non-Git URLs (e.g. PyPI) are excluded, preventing broken or confusing repository configs.
+* GitHub authentication is more robust: tokens are automatically resolved via the GitHub CLI (`gh`), invalid stored tokens are replaced, and interactive prompts occur only when necessary.
+* Repository creation and release workflows are more reliable, producing cleaner Git configurations and more predictable version handling.
+
+* Mon Dec 15 2025 Kevin Veen-Birkenbach <kevin@veen.world> - 1.8.0-1
+- *** New Features: ***
+- **Silent Updates**: You can now use the `--silent` flag during installs and updates to suppress error messages for individual repositories and get a single summary at the end. This ensures the process continues even if some repositories fail, while still preserving interactive checks when not in silent mode.
+- **Repository Scaffolding**: The process for creating new repositories has been improved. You can now use templates to scaffold repositories with a preview and automatic mirror setup.
+
+*** Bug Fixes: ***
+- **Pip Installation**: Pip is now installed automatically on all supported systems. This includes `python-pip` for Arch and `python3-pip` for CentOS, Debian, Fedora, and Ubuntu, ensuring that pip is available for Python package installations.
+- **Pacman Keyring**: Fixed an issue on Arch Linux where package installation would fail due to missing keys. The pacman keyring is now properly initialized before installing packages.
+
+* Mon Dec 15 2025 Kevin Veen-Birkenbach <kevin@veen.world> - 1.7.2-1
+- * Git mirrors are now resolved consistently (origin → MIRRORS file → config → default).
+* The `origin` remote is always enforced to use the primary URL for both fetch and push.
+* Additional mirrors are added as extra push targets without duplication.
+* Local and remote mirror setup behaves more predictably and consistently.
+* Improved test coverage ensures stable origin and push URL handling.
+
+* Sun Dec 14 2025 Kevin Veen-Birkenbach <kevin@veen.world> - 1.7.1-1
+- Patched package-manager to kpmx to publish on pypi
+
+* Sun Dec 14 2025 Kevin Veen-Birkenbach <kevin@veen.world> - 1.7.0-1
+- * New *pkgmgr publish* command to publish repository artifacts to PyPI based on the *MIRRORS* file.
+* Automatically selects the current repository when no explicit selection is given.
+* Publishes only when a semantic version tag is present on *HEAD*; otherwise skips with a clear info message.
+* Supports non-interactive mode for CI environments via *--non-interactive*.
+
+* Sun Dec 14 2025 Kevin Veen-Birkenbach <kevin@veen.world> - 1.6.4-1
+- * Improved reliability of Nix installs and updates, including automatic resolution of profile conflicts and better handling of GitHub 403 rate limits.
+* More stable launcher behavior in packaged and virtual-env setups.
+* Enhanced mirror and remote handling: repository owner/name are derived from URLs, with smoother provisioning and clearer credential handling.
+* More reliable releases and artifacts due to safer CI behavior when no version tag is present.
+
+* Sun Dec 14 2025 Kevin Veen-Birkenbach <kevin@veen.world> - 1.6.3-1
+- ***Fixed:*** Corrected repository path resolution so release and version logic consistently use the canonical packaging/* layout, preventing changelog and packaging files from being read or updated from incorrect locations.
+
 * Wed Dec 10 2025 Kevin Veen-Birkenbach <kevin@veen.world> - 0.9.1-1
 - * Refactored installer: new `venv-create.sh`, cleaner root/user setup flow, updated README with architecture map.
 * Split virgin tests into root/user workflows; stabilized Nix installer across distros; improved test scripts with dynamic distro selection and isolated Nix stores.

pyproject.toml

@@ -6,8 +6,8 @@ requires = [
 build-backend = "setuptools.build_meta"
 
 [project]
-name = "package-manager"
-version = "1.4.0"
+name = "kpmx"
+version = "1.8.2"
 description = "Kevin's package-manager tool (pkgmgr)"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -19,16 +19,18 @@ authors = [
 
 # Base runtime dependencies
 dependencies = [
-  "PyYAML>=6.0"
+  "PyYAML>=6.0",
+  "tomli; python_version < \"3.11\"",
+  "jinja2>=3.1"
 ]
 
 [project.urls]
-Homepage = "https://github.com/kevinveenbirkenbach/package-manager"
+Homepage = "https://s.veen.world/pkgmgr"
 Source   = "https://github.com/kevinveenbirkenbach/package-manager"
 
 [project.optional-dependencies]
+keyring = ["keyring>=24.0.0"]
 dev = [
-  "pytest",
   "mypy"
 ]
 

scripts/build/base.sh

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

scripts/build/image.sh

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

scripts/build/publish.sh

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

scripts/docker/entry.sh

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

scripts/installation/arch/dependencies.sh

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

scripts/installation/centos/dependencies.sh

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

scripts/installation/debian/dependencies.sh

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

scripts/installation/fedora/dependencies.sh

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

scripts/installation/ubuntu/dependencies.sh

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

scripts/launcher.sh

@@ -1,12 +1,17 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-# Ensure NIX_CONFIG has our defaults if not already set
-if [[ -z "${NIX_CONFIG:-}" ]]; then
-  export NIX_CONFIG="experimental-features = nix-command flakes"
-fi
-
 FLAKE_DIR="/usr/lib/package-manager"
+NIX_LIB_DIR="${FLAKE_DIR}/nix/lib"
+RETRY_LIB="${NIX_LIB_DIR}/retry_403.sh"
+
+# ---------------------------------------------------------------------------
+# Hard requirement: retry helper must exist (fail if missing)
+# ---------------------------------------------------------------------------
+if [[ ! -f "${RETRY_LIB}" ]]; then
+  echo "[launcher] ERROR: Required retry helper not found: ${RETRY_LIB}" >&2
+  exit 1
+fi
 
 # ---------------------------------------------------------------------------
 # Try to ensure that "nix" is on PATH (common locations + container user)
@@ -37,12 +42,16 @@ if ! command -v nix >/dev/null 2>&1; then
 fi
 
 # ---------------------------------------------------------------------------
-# Primary path: use Nix flake if available
+# Primary path: use Nix flake if available (with GitHub 403 retry)
 # ---------------------------------------------------------------------------
-if command -v nix >/dev/null 2>&1; then
+if declare -F run_with_github_403_retry >/dev/null; then
+  # shellcheck source=./scripts/nix/lib/retry_403.sh
+  source "${RETRY_LIB}"
+  exec run_with_github_403_retry nix run "${FLAKE_DIR}#pkgmgr" -- "$@"
+else
   exec nix run "${FLAKE_DIR}#pkgmgr" -- "$@"
 fi
 
-echo "[pkgmgr-wrapper] ERROR: 'nix' binary not found on PATH after init."
-echo "[pkgmgr-wrapper] Nix is required to run pkgmgr (no Python fallback)."
+echo "[launcher] ERROR: 'nix' binary not found on PATH after init."
+echo "[launcher] Nix is required to run pkgmgr (no Python fallback)."
 exit 1

scripts/nix/README.md

@@ -22,7 +22,7 @@ It is invoked during package installation (Arch/Debian/Fedora scriptlets) and ca
 
 The entry point sources small, focused modules from *scripts/nix/lib/*:
 
-- *config.sh* — configuration defaults (installer URL, retry timing)
+- *bootstrap_config.sh* — configuration defaults (installer URL, retry timing)
 - *detect.sh* — container detection helpers
 - *path.sh* — PATH adjustments and `nix` binary resolution helpers
 - *symlinks.sh* — user/global symlink helpers for stable `nix` discovery

scripts/nix/init.sh

@@ -1,22 +1,29 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-# shellcheck source=lib/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
-
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
-source "${SCRIPT_DIR}/lib/config.sh"
+# 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..."
 
 main() {
@@ -26,6 +33,7 @@ main() {
     ensure_nix_on_path
 
     if [[ "${EUID:-0}" -eq 0 ]]; then
+      nixconf_ensure_experimental_features
       ensure_global_nix_symlinks "$(resolve_nix_bin 2>/dev/null || true)"
     else
       ensure_user_nix_symlink "$(resolve_nix_bin 2>/dev/null || true)"
@@ -106,6 +114,10 @@ main() {
   # -------------------------------------------------------------------------
   ensure_nix_on_path
 
+  if [[ "${EUID:-0}" -eq 0 ]]; then
+    nixconf_ensure_experimental_features
+  fi
+
   local nix_bin_post
   nix_bin_post="$(resolve_nix_bin 2>/dev/null || true)"
 

scripts/nix/lib/nix_conf_file.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Prevent double-sourcing
+if [[ -n "${PKGMGR_NIX_CONF_FILE_SH:-}" ]]; then
+  return 0
+fi
+PKGMGR_NIX_CONF_FILE_SH=1
+
+nixconf_file_path() {
+  echo "/etc/nix/nix.conf"
+}
+
+# Ensure a given nix.conf key contains required tokens (merged, no duplicates)
+nixconf_ensure_features_key() {
+  local nix_conf="$1"
+  local key="$2"
+  shift 2
+  local required=("$@")
+
+  mkdir -p /etc/nix
+
+  # Create file if missing (with just the required tokens)
+  if [[ ! -f "${nix_conf}" ]]; then
+    local want="${key} = ${required[*]}"
+    echo "[nix-conf] Creating ${nix_conf} with: ${want}"
+    printf "%s\n" "${want}" >"${nix_conf}"
+    return 0
+  fi
+
+  # Key exists -> merge tokens
+  if grep -qE "^\s*${key}\s*=" "${nix_conf}"; then
+    local ok=1
+    local t
+    for t in "${required[@]}"; do
+      if ! grep -qE "^\s*${key}\s*=.*\b${t}\b" "${nix_conf}"; then
+        ok=0
+        break
+      fi
+    done
+
+    if [[ "$ok" -eq 1 ]]; then
+      echo "[nix-conf] ${key} already correct"
+      return 0
+    fi
+
+    echo "[nix-conf] Extending ${key} in ${nix_conf}"
+
+    local current
+    current="$(grep -E "^\s*${key}\s*=" "${nix_conf}" | head -n1 | cut -d= -f2-)"
+    current="$(echo "${current}" | xargs)" # trim
+
+    local merged=""
+    local token
+
+    # Start with existing tokens
+    for token in ${current}; do
+      if [[ " ${merged} " != *" ${token} "* ]]; then
+        merged="${merged} ${token}"
+      fi
+    done
+
+    # 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,9 +1,11 @@
+#!/usr/bin/env bash
+
 # ------------------------------------------------------------
-# Nix shell mode: do not touch venv, only run main.py install
+# Nix shell mode: do not touch venv, only run install
 # ------------------------------------------------------------
 
 echo "[setup] Nix mode enabled (NIX_ENABLED=1)."
 echo "[setup] Skipping virtualenv creation and dependency installation."
-echo "[setup] Running main.py install via system python3..."
-python3 main.py install
+echo "[setup] Running install via system python3..."
+python3 -m pkgmgr install
 echo "[setup] Setup finished (Nix mode)."

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'
 
 # ------------------------------------------------------------
@@ -15,9 +16,6 @@ RC_LINE='if [ -d "${HOME}/.venvs/pkgmgr" ]; then . "${HOME}/.venvs/pkgmgr/bin/ac
 
 echo "[setup] Running in normal user mode (developer setup)."
 
-echo "[setup] Ensuring main.py is executable..."
-chmod +x main.py || true
-
 echo "[setup] Ensuring global virtualenv root: ${HOME}/.venvs"
 mkdir -p "${HOME}/.venvs"
 
@@ -90,8 +88,8 @@ for rc in "${HOME}/.bashrc" "${HOME}/.zshrc"; do
     fi
 done
 
-echo "[setup] Running main.py install via venv Python..."
-"${VENV_DIR}/bin/python" main.py install
+echo "[setup] Running install via venv Python..."
+"${VENV_DIR}/bin/python" -m pkgmgr install
 
 echo
 echo "[setup] Developer setup complete."

scripts/test/test-e2e.sh

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

scripts/test/test-env-nix.sh

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

scripts/test/test-env-virtual.sh

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

scripts/test/test-integration.sh

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

scripts/test/test-unit.sh

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

scripts/uninstall.sh

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

src/pkgmgr/__main__.py

@@ -0,0 +1,5 @@
+#!/usr/bin/env python3
+from pkgmgr.cli import main
+
+if __name__ == "__main__":
+    main()

src/pkgmgr/actions/__init__.py

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

src/pkgmgr/actions/branch/close_branch.py

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

src/pkgmgr/actions/branch/drop_branch.py

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

src/pkgmgr/actions/branch/open_branch.py

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

src/pkgmgr/actions/branch/utils.py

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

src/pkgmgr/actions/changelog/__init__.py

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

src/pkgmgr/actions/config/add.py

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

src/pkgmgr/actions/config/init.py

@@ -14,7 +14,7 @@ with the expected structure:
 
 For each discovered repository, the function:
   • derives provider, account, repository from the folder structure
-  • (optionally) determines the latest commit hash via git log
+  • (optionally) determines the latest commit hash via git
   • generates a unique CLI alias
   • marks ignore=True for newly discovered repos
   • skips repos already known in defaults or user config
@@ -23,11 +23,11 @@ For each discovered repository, the function:
 from __future__ import annotations
 
 import os
-import subprocess
 from typing import Any, Dict
 
 from pkgmgr.core.command.alias import generate_alias
 from pkgmgr.core.config.save import save_user_config
+from pkgmgr.core.git.queries import get_latest_commit
 
 
 def config_init(
@@ -45,7 +45,7 @@ def config_init(
     # Announce where we will write the result
     # ------------------------------------------------------------
     print("============================================================")
-    print(f"[INIT] Writing user configuration to:")
+    print("[INIT] Writing user configuration to:")
     print(f"       {user_config_path}")
     print("============================================================")
 
@@ -53,7 +53,7 @@ def config_init(
         defaults_config["directories"]["repositories"]
     )
 
-    print(f"[INIT] Scanning repository base directory:")
+    print("[INIT] Scanning repository base directory:")
     print(f"       {repositories_base_dir}")
     print("")
 
@@ -116,27 +116,18 @@ def config_init(
 
                 print(f"[ADD]      {provider}/{account}/{repo_name}")
 
-                # Determine commit hash
-                try:
-                    result = subprocess.run(
-                        ["git", "log", "-1", "--format=%H"],
-                        cwd=repo_path,
-                        stdout=subprocess.PIPE,
-                        stderr=subprocess.PIPE,
-                        text=True,
-                        check=True,
-                    )
-                    verified = result.stdout.strip()
-                    print(f"[INFO]       Latest commit: {verified}")
-                except Exception as exc:
-                    verified = ""
-                    print(f"[WARN]       Could not read commit: {exc}")
+                # Determine commit hash via git query
+                verified_commit = get_latest_commit(repo_path) or ""
+                if verified_commit:
+                    print(f"[INFO]       Latest commit: {verified_commit}")
+                else:
+                    print("[WARN]       Could not read commit (not a git repo or no commits).")
 
-                entry = {
+                entry: Dict[str, Any] = {
                     "provider": provider,
                     "account": account,
                     "repository": repo_name,
-                    "verified": {"commit": verified},
+                    "verified": {"commit": verified_commit},
                     "ignore": True,
                 }
 
@@ -173,7 +164,7 @@ def config_init(
     if new_entries:
         user_config.setdefault("repositories", []).extend(new_entries)
         save_user_config(user_config, user_config_path)
-        print(f"[SAVE] Wrote user configuration to:")
+        print("[SAVE] Wrote user configuration to:")
         print(f"       {user_config_path}")
     else:
         print("[INFO] No new repositories were added.")

src/pkgmgr/actions/install/__init__.py

@@ -1,3 +1,4 @@
+# src/pkgmgr/actions/install/__init__.py
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 
@@ -15,7 +16,7 @@ Responsibilities:
 from __future__ import annotations
 
 import os
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, Tuple
 
 from pkgmgr.core.repository.identifier import get_repo_identifier
 from pkgmgr.core.repository.dir import get_repo_dir
@@ -27,7 +28,7 @@ from pkgmgr.actions.install.installers.os_packages import (
     DebianControlInstaller,
     RpmSpecInstaller,
 )
-from pkgmgr.actions.install.installers.nix_flake import (
+from pkgmgr.actions.install.installers.nix import (
     NixFlakeInstaller,
 )
 from pkgmgr.actions.install.installers.python import PythonInstaller
@@ -36,10 +37,8 @@ from pkgmgr.actions.install.installers.makefile import (
 )
 from pkgmgr.actions.install.pipeline import InstallationPipeline
 
-
 Repository = Dict[str, Any]
 
-# All available installers, in the order they should be considered.
 INSTALLERS = [
     ArchPkgbuildInstaller(),
     DebianControlInstaller(),
@@ -50,11 +49,6 @@ INSTALLERS = [
 ]
 
 
-# ---------------------------------------------------------------------------
-# Internal helpers
-# ---------------------------------------------------------------------------
-
-
 def _ensure_repo_dir(
     repo: Repository,
     repositories_base_dir: str,
@@ -74,7 +68,7 @@ def _ensure_repo_dir(
     if not os.path.exists(repo_dir):
         print(
             f"Repository directory '{repo_dir}' does not exist. "
-            f"Cloning it now..."
+            "Cloning it now..."
         )
         clone_repos(
             [repo],
@@ -87,7 +81,7 @@ def _ensure_repo_dir(
         if not os.path.exists(repo_dir):
             print(
                 f"Cloning failed for repository {identifier}. "
-                f"Skipping installation."
+                "Skipping installation."
             )
             return None
 
@@ -99,6 +93,7 @@ def _verify_repo(
     repo_dir: str,
     no_verification: bool,
     identifier: str,
+    silent: bool,
 ) -> bool:
     """
     Verify a repository using the configured verification data.
@@ -117,10 +112,15 @@ def _verify_repo(
         print(f"Warning: Verification failed for {identifier}:")
         for err in errors:
             print(f"  - {err}")
-        choice = input("Continue anyway? [y/N]: ").strip().lower()
-        if choice != "y":
-            print(f"Skipping installation for {identifier}.")
-            return False
+
+        if silent:
+            # Non-interactive mode: continue with a warning.
+            print(f"[Warning] Continuing despite verification failure for {identifier} (--silent).")
+        else:
+            choice = input("Continue anyway? [y/N]: ").strip().lower()
+            if choice != "y":
+                print(f"Skipping installation for {identifier}.")
+                return False
 
     return True
 
@@ -137,6 +137,7 @@ def _create_context(
     quiet: bool,
     clone_mode: str,
     update_dependencies: bool,
+    force_update: bool,
 ) -> RepoContext:
     """
     Build a RepoContext instance for the given repository.
@@ -153,14 +154,10 @@ def _create_context(
         quiet=quiet,
         clone_mode=clone_mode,
         update_dependencies=update_dependencies,
+        force_update=force_update,
     )
 
 
-# ---------------------------------------------------------------------------
-# Public API
-# ---------------------------------------------------------------------------
-
-
 def install_repos(
     selected_repos: List[Repository],
     repositories_base_dir: str,
@@ -171,48 +168,82 @@ def install_repos(
     quiet: bool,
     clone_mode: str,
     update_dependencies: bool,
+    force_update: bool = False,
+    silent: bool = False,
+    emit_summary: bool = True,
 ) -> None:
     """
     Install one or more repositories according to the configured installers
     and the CLI layer precedence rules.
+
+    If force_update=True, installers of the currently active layer are allowed
+    to run again (upgrade/refresh), even if that layer is already loaded.
+
+    If silent=True, repository failures are downgraded to warnings and the
+    overall command never exits non-zero because of per-repository failures.
     """
     pipeline = InstallationPipeline(INSTALLERS)
+    failures: List[Tuple[str, str]] = []
 
     for repo in selected_repos:
         identifier = get_repo_identifier(repo, all_repos)
 
-        repo_dir = _ensure_repo_dir(
-            repo=repo,
-            repositories_base_dir=repositories_base_dir,
-            all_repos=all_repos,
-            preview=preview,
-            no_verification=no_verification,
-            clone_mode=clone_mode,
-            identifier=identifier,
-        )
-        if not repo_dir:
+        try:
+            repo_dir = _ensure_repo_dir(
+                repo=repo,
+                repositories_base_dir=repositories_base_dir,
+                all_repos=all_repos,
+                preview=preview,
+                no_verification=no_verification,
+                clone_mode=clone_mode,
+                identifier=identifier,
+            )
+            if not repo_dir:
+                failures.append((identifier, "clone/ensure repo directory failed"))
+                continue
+
+            if not _verify_repo(
+                repo=repo,
+                repo_dir=repo_dir,
+                no_verification=no_verification,
+                identifier=identifier,
+                silent=silent,
+            ):
+                continue
+
+            ctx = _create_context(
+                repo=repo,
+                identifier=identifier,
+                repo_dir=repo_dir,
+                repositories_base_dir=repositories_base_dir,
+                bin_dir=bin_dir,
+                all_repos=all_repos,
+                no_verification=no_verification,
+                preview=preview,
+                quiet=quiet,
+                clone_mode=clone_mode,
+                update_dependencies=update_dependencies,
+                force_update=force_update,
+            )
+
+            pipeline.run(ctx)
+
+        except SystemExit as exc:
+            code = exc.code if isinstance(exc.code, int) else str(exc.code)
+            failures.append((identifier, f"installer failed (exit={code})"))
+            if not quiet:
+                print(f"[Warning] install: repository {identifier} failed (exit={code}). Continuing...")
+            continue
+        except Exception as exc:
+            failures.append((identifier, f"unexpected error: {exc}"))
+            if not quiet:
+                print(f"[Warning] install: repository {identifier} hit an unexpected error: {exc}. Continuing...")
             continue
 
-        if not _verify_repo(
-            repo=repo,
-            repo_dir=repo_dir,
-            no_verification=no_verification,
-            identifier=identifier,
-        ):
-            continue
+    if failures and emit_summary and not quiet:
+        print("\n[pkgmgr] Installation finished with warnings:")
+        for ident, msg in failures:
+            print(f"  - {ident}: {msg}")
 
-        ctx = _create_context(
-            repo=repo,
-            identifier=identifier,
-            repo_dir=repo_dir,
-            repositories_base_dir=repositories_base_dir,
-            bin_dir=bin_dir,
-            all_repos=all_repos,
-            no_verification=no_verification,
-            preview=preview,
-            quiet=quiet,
-            clone_mode=clone_mode,
-            update_dependencies=update_dependencies,
-        )
-
-        pipeline.run(ctx)
+    if failures and not silent:
+        raise SystemExit(1)

src/pkgmgr/actions/install/context.py

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

src/pkgmgr/actions/install/pipeline.py

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

src/pkgmgr/actions/mirror/__init__.py

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

src/pkgmgr/actions/mirror/git_remote.py

@@ -1,20 +1,50 @@
 from __future__ import annotations
 
 import os
+from typing import Optional, Set
 
-from pkgmgr.core.command.run import run_command
-from pkgmgr.core.git import GitError, run_git
-from typing import List, Optional, Set
+from pkgmgr.core.git.errors import GitError
+from pkgmgr.core.git.commands import (
+    GitAddRemoteError,
+    GitAddRemotePushUrlError,
+    GitSetRemoteUrlError,
+    add_remote,
+    add_remote_push_url,
+    set_remote_url,
+)
+from pkgmgr.core.git.queries import get_remote_push_urls, list_remotes
 
 from .types import MirrorMap, RepoMirrorContext, Repository
 
 
-def build_default_ssh_url(repo: Repository) -> Optional[str]:
+def _is_git_remote_url(url: str) -> bool:
     """
-    Build a simple SSH URL from repo config if no explicit mirror is defined.
+    True only for URLs that should become git remotes / push URLs.
 
-    Example: git@github.com:account/repository.git
+    Accepted:
+      - git@host:owner/repo(.git)                (SCP-like SSH)
+      - ssh://git@host(:port)/owner/repo(.git)   (SSH URL)
+      - https://host/owner/repo.git              (HTTPS git remote)
+      - http://host/owner/repo.git               (rare, but possible)
+    Everything else (e.g. PyPI project page) stays metadata only.
     """
+    u = (url or "").strip()
+    if not u:
+        return False
+
+    if u.startswith("git@"):
+        return True
+
+    if u.startswith("ssh://"):
+        return True
+
+    if (u.startswith("https://") or u.startswith("http://")) and u.endswith(".git"):
+        return True
+
+    return False
+
+
+def build_default_ssh_url(repo: Repository) -> Optional[str]:
     provider = repo.get("provider")
     account = repo.get("account")
     name = repo.get("repository")
@@ -23,96 +53,80 @@ def build_default_ssh_url(repo: Repository) -> Optional[str]:
     if not provider or not account or not name:
         return None
 
-    provider = str(provider)
-    account = str(account)
-    name = str(name)
-
     if port:
         return f"ssh://git@{provider}:{port}/{account}/{name}.git"
 
-    # GitHub-style shorthand
     return f"git@{provider}:{account}/{name}.git"
 
 
+def _git_mirrors_only(m: MirrorMap) -> MirrorMap:
+    return {k: v for k, v in m.items() if v and _is_git_remote_url(v)}
+
+
 def determine_primary_remote_url(
     repo: Repository,
-    resolved_mirrors: MirrorMap,
+    ctx: RepoMirrorContext,
 ) -> Optional[str]:
     """
-    Determine the primary remote URL in a consistent way:
-
-      1. resolved_mirrors["origin"]
-      2. any resolved mirror (first by name)
-      3. default SSH URL from provider/account/repository
+    Priority order (GIT URLS ONLY):
+      1. origin from resolved mirrors (if it is a git URL)
+      2. first git URL from MIRRORS file (in file order)
+      3. first git URL from config mirrors (in config order)
+      4. default SSH URL
     """
-    if "origin" in resolved_mirrors:
-        return resolved_mirrors["origin"]
+    resolved = ctx.resolved_mirrors
+    origin = resolved.get("origin")
+    if origin and _is_git_remote_url(origin):
+        return origin
 
-    if resolved_mirrors:
-        first_name = sorted(resolved_mirrors.keys())[0]
-        return resolved_mirrors[first_name]
+    for mirrors in (ctx.file_mirrors, ctx.config_mirrors):
+        for _, url in mirrors.items():
+            if url and _is_git_remote_url(url):
+                return url
 
     return build_default_ssh_url(repo)
 
 
-def _safe_git_output(args: List[str], cwd: str) -> Optional[str]:
-    """
-    Run a Git command via run_git and return its stdout, or None on failure.
-    """
-    try:
-        return run_git(args, cwd=cwd)
-    except GitError:
-        return None
-
-
-def current_origin_url(repo_dir: str) -> Optional[str]:
-    """
-    Return the current URL for remote 'origin', or None if not present.
-    """
-    output = _safe_git_output(["remote", "get-url", "origin"], cwd=repo_dir)
-    if not output:
-        return None
-    url = output.strip()
-    return url or None
-
-
 def has_origin_remote(repo_dir: str) -> bool:
-    """
-    Check whether a remote called 'origin' exists in the repository.
-    """
-    output = _safe_git_output(["remote"], cwd=repo_dir)
-    if not output:
+    try:
+        return "origin" in list_remotes(cwd=repo_dir)
+    except GitError:
         return False
-    names = output.split()
-    return "origin" in names
 
 
-def _ensure_push_urls_for_origin(
+def _set_origin_fetch_and_push(repo_dir: str, url: str, preview: bool) -> None:
+    """
+    Ensure origin has fetch URL and push URL set to the primary URL.
+    Preview is handled by the underlying git runner.
+    """
+    set_remote_url("origin", url, cwd=repo_dir, push=False, preview=preview)
+    set_remote_url("origin", url, cwd=repo_dir, push=True, preview=preview)
+
+
+def _ensure_additional_push_urls(
     repo_dir: str,
     mirrors: MirrorMap,
+    primary: str,
     preview: bool,
 ) -> None:
     """
-    Ensure that all mirror URLs are present as push URLs on 'origin'.
+    Ensure all *git* mirror URLs (except primary) are configured as additional
+    push URLs for origin.
+
+    Non-git URLs (like PyPI) are ignored and will never land in git config.
     """
-    desired: Set[str] = {url for url in mirrors.values() if url}
+    git_only = _git_mirrors_only(mirrors)
+    desired: Set[str] = {u for u in git_only.values() if u and u != primary}
     if not desired:
         return
 
-    existing_output = _safe_git_output(
-        ["remote", "get-url", "--push", "--all", "origin"],
-        cwd=repo_dir,
-    )
-    existing = set(existing_output.splitlines()) if existing_output else set()
+    try:
+        existing = get_remote_push_urls("origin", cwd=repo_dir)
+    except GitError:
+        existing = set()
 
-    missing = sorted(desired - existing)
-    for url in missing:
-        cmd = f"git remote set-url --add --push origin {url}"
-        if preview:
-            print(f"[PREVIEW] Would run in {repo_dir!r}: {cmd}")
-        else:
-            print(f"[INFO] Adding push URL to 'origin': {url}")
-            run_command(cmd, cwd=repo_dir, preview=False)
+    for url in sorted(desired - existing):
+        add_remote_push_url("origin", url, cwd=repo_dir, preview=preview)
 
 
 def ensure_origin_remote(
@@ -120,60 +134,33 @@ def ensure_origin_remote(
     ctx: RepoMirrorContext,
     preview: bool,
 ) -> None:
-    """
-    Ensure that a usable 'origin' remote exists and has all push URLs.
-    """
     repo_dir = ctx.repo_dir
-    resolved_mirrors = ctx.resolved_mirrors
 
     if not os.path.isdir(os.path.join(repo_dir, ".git")):
-        print(f"[WARN] {repo_dir} is not a Git repository (no .git directory).")
+        print(f"[WARN] {repo_dir} is not a Git repository.")
         return
 
-    url = determine_primary_remote_url(repo, resolved_mirrors)
+    primary = determine_primary_remote_url(repo, ctx)
+    if not primary or not _is_git_remote_url(primary):
+        print("[WARN] No valid git primary mirror URL could be determined.")
+        return
 
+    # 1) Ensure origin exists
     if not has_origin_remote(repo_dir):
-        if not url:
-            print(
-                "[WARN] Could not determine URL for 'origin' remote. "
-                "Please configure mirrors or provider/account/repository."
-            )
-            return
+        try:
+            add_remote("origin", primary, cwd=repo_dir, preview=preview)
+        except GitAddRemoteError as exc:
+            print(f"[WARN] Failed to add origin remote: {exc}")
+            return  # without origin we cannot reliably proceed
 
-        cmd = f"git remote add origin {url}"
-        if preview:
-            print(f"[PREVIEW] Would run in {repo_dir!r}: {cmd}")
-        else:
-            print(f"[INFO] Adding 'origin' remote in {repo_dir}: {url}")
-            run_command(cmd, cwd=repo_dir, preview=False)
-    else:
-        current = current_origin_url(repo_dir)
-        if current == url or not url:
-            print(
-                f"[INFO] 'origin' already points to "
-                f"{current or '<unknown>'} (no change needed)."
-            )
-        else:
-            # We do not auto-change origin here, only log the mismatch.
-            print(
-                "[INFO] 'origin' exists with URL "
-                f"{current or '<unknown>'}; not changing to {url}."
-            )
-
-    # Ensure all mirrors are present as push URLs
-    _ensure_push_urls_for_origin(repo_dir, resolved_mirrors, preview)
-
-
-def is_remote_reachable(url: str, cwd: Optional[str] = None) -> bool:
-    """
-    Check whether a remote repository is reachable via `git ls-remote`.
-
-    This does NOT modify anything; it only probes the remote.
-    """
-    workdir = cwd or os.getcwd()
+    # 2) Ensure origin fetch+push URLs are correct
     try:
-        # --exit-code → non-zero exit code if the remote does not exist
-        run_git(["ls-remote", "--exit-code", url], cwd=workdir)
-        return True
-    except GitError:
-        return False
+        _set_origin_fetch_and_push(repo_dir, primary, preview)
+    except GitSetRemoteUrlError as exc:
+        print(f"[WARN] Failed to set origin URLs: {exc}")
+
+    # 3) Ensure additional push URLs for mirrors (git urls only)
+    try:
+        _ensure_additional_push_urls(repo_dir, ctx.resolved_mirrors, primary, preview)
+    except GitAddRemotePushUrlError as exc:
+        print(f"[WARN] Failed to add additional push URLs: {exc}")

src/pkgmgr/actions/mirror/io.py

@@ -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_provision.py

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

src/pkgmgr/actions/mirror/setup_cmd.py

@@ -1,23 +1,36 @@
 from __future__ import annotations
 
-from typing import List, Tuple
+from typing import List
 
-from pkgmgr.core.git import run_git, GitError
+from pkgmgr.core.git.queries import probe_remote_reachable
 
 from .context import build_context
-from .git_remote import determine_primary_remote_url, ensure_origin_remote
+from .git_remote import ensure_origin_remote, determine_primary_remote_url
+from .remote_provision import ensure_remote_repository
 from .types import Repository
 
 
+def _is_git_remote_url(url: str) -> bool:
+    # Keep the same filtering semantics as in git_remote.py (duplicated on purpose
+    # to keep setup_cmd independent of private helpers).
+    u = (url or "").strip()
+    if not u:
+        return False
+    if u.startswith("git@"):
+        return True
+    if u.startswith("ssh://"):
+        return True
+    if (u.startswith("https://") or u.startswith("http://")) and u.endswith(".git"):
+        return True
+    return False
+
+
 def _setup_local_mirrors_for_repo(
     repo: Repository,
     repositories_base_dir: str,
     all_repos: List[Repository],
     preview: bool,
 ) -> None:
-    """
-    Ensure local Git state is sane (currently: 'origin' remote).
-    """
     ctx = build_context(repo, repositories_base_dir, all_repos)
 
     print("------------------------------------------------------------")
@@ -25,107 +38,53 @@ def _setup_local_mirrors_for_repo(
     print(f"[MIRROR SETUP:LOCAL] dir: {ctx.repo_dir}")
     print("------------------------------------------------------------")
 
-    ensure_origin_remote(repo, ctx, preview=preview)
+    ensure_origin_remote(repo, ctx, preview)
     print()
 
 
-def _probe_mirror(url: str, repo_dir: str) -> Tuple[bool, str]:
-    """
-    Probe a remote mirror by running `git ls-remote <url>`.
-
-    Returns:
-      (True, "") on success,
-      (False, error_message) on failure.
-
-    Wichtig:
-      - Wir werten ausschließlich den Exit-Code aus.
-      - STDERR kann Hinweise/Warnings enthalten und ist NICHT automatisch ein Fehler.
-    """
-    try:
-        # Wir ignorieren stdout komplett; wichtig ist nur, dass der Befehl ohne
-        # GitError (also Exit-Code 0) durchläuft.
-        run_git(["ls-remote", url], cwd=repo_dir)
-        return True, ""
-    except GitError as exc:
-        return False, str(exc)
-
-
 def _setup_remote_mirrors_for_repo(
     repo: Repository,
     repositories_base_dir: str,
     all_repos: List[Repository],
     preview: bool,
+    ensure_remote: bool,
 ) -> None:
-    """
-    Remote-side setup / validation.
-
-    Aktuell werden nur **nicht-destruktive Checks** gemacht:
-
-      - Für jeden Mirror (aus config + MIRRORS-Datei, file gewinnt):
-          * `git ls-remote <url>` wird ausgeführt.
-          * Bei Exit-Code 0 → [OK]
-          * Bei Fehler → [WARN] + Details aus der GitError-Exception
-
-    Es werden **keine** Provider-APIs aufgerufen und keine Repos angelegt.
-    """
     ctx = build_context(repo, repositories_base_dir, all_repos)
-    resolved_m = ctx.resolved_mirrors
 
     print("------------------------------------------------------------")
     print(f"[MIRROR SETUP:REMOTE] {ctx.identifier}")
     print(f"[MIRROR SETUP:REMOTE] dir: {ctx.repo_dir}")
     print("------------------------------------------------------------")
 
-    if not resolved_m:
-        # Optional: Fallback auf eine heuristisch bestimmte URL, falls wir
-        # irgendwann "automatisch anlegen" implementieren wollen.
-        primary_url = determine_primary_remote_url(repo, resolved_m)
-        if not primary_url:
-            print(
-                "[INFO] No mirrors configured (config or MIRRORS file), and no "
-                "primary URL could be derived from provider/account/repository."
-            )
+    if ensure_remote:
+        ensure_remote_repository(
+            repo,
+            repositories_base_dir,
+            all_repos,
+            preview,
+        )
+
+    # Probe only git URLs (do not try ls-remote against PyPI etc.)
+    # If there are no mirrors at all, probe the primary git URL.
+    git_mirrors = {k: v for k, v in ctx.resolved_mirrors.items() if _is_git_remote_url(v)}
+
+    if not git_mirrors:
+        primary = determine_primary_remote_url(repo, ctx)
+        if not primary or not _is_git_remote_url(primary):
+            print("[INFO] No git mirrors to probe.")
             print()
             return
 
-        ok, error_message = _probe_mirror(primary_url, ctx.repo_dir)
-        if ok:
-            print(f"[OK]   Remote mirror (primary) is reachable: {primary_url}")
-        else:
-            print("[WARN] Primary remote URL is NOT reachable:")
-            print(f"       {primary_url}")
-            if error_message:
-                print("       Details:")
-                for line in error_message.splitlines():
-                    print(f"         {line}")
-
-        print()
-        print(
-            "[INFO] Remote checks are non-destructive and only use `git ls-remote` "
-            "to probe mirror URLs."
-        )
+        ok = probe_remote_reachable(primary, cwd=ctx.repo_dir)
+        print("[OK]" if ok else "[WARN]", primary)
         print()
         return
 
-    # Normaler Fall: wir haben benannte Mirrors aus config/MIRRORS
-    for name, url in sorted(resolved_m.items()):
-        ok, error_message = _probe_mirror(url, ctx.repo_dir)
-        if ok:
-            print(f"[OK]   Remote mirror '{name}' is reachable: {url}")
-        else:
-            print(f"[WARN] Remote mirror '{name}' is NOT reachable:")
-            print(f"       {url}")
-            if error_message:
-                print("       Details:")
-                for line in error_message.splitlines():
-                    print(f"         {line}")
+    for name, url in git_mirrors.items():
+        ok = probe_remote_reachable(url, cwd=ctx.repo_dir)
+        print(f"[OK] {name}: {url}" if ok else f"[WARN] {name}: {url}")
 
     print()
-    print(
-        "[INFO] Remote checks are non-destructive and only use `git ls-remote` "
-        "to probe mirror URLs."
-    )
-    print()
 
 
 def setup_mirrors(
@@ -135,31 +94,22 @@ def setup_mirrors(
     preview: bool = False,
     local: bool = True,
     remote: bool = True,
+    ensure_remote: bool = False,
 ) -> None:
-    """
-    Setup mirrors for the selected repositories.
-
-    local:
-      - Configure local Git remotes (currently: ensure 'origin' is present and
-        points to a reasonable URL).
-
-    remote:
-      - Non-destructive remote checks using `git ls-remote` for each mirror URL.
-        Es werden keine Repositories auf dem Provider angelegt.
-    """
     for repo in selected_repos:
         if local:
             _setup_local_mirrors_for_repo(
                 repo,
-                repositories_base_dir=repositories_base_dir,
-                all_repos=all_repos,
-                preview=preview,
+                repositories_base_dir,
+                all_repos,
+                preview,
             )
 
         if remote:
             _setup_remote_mirrors_for_repo(
                 repo,
-                repositories_base_dir=repositories_base_dir,
-                all_repos=all_repos,
-                preview=preview,
+                repositories_base_dir,
+                all_repos,
+                preview,
+                ensure_remote,
             )

src/pkgmgr/actions/mirror/url_utils.py

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

src/pkgmgr/actions/publish/__init__.py

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

src/pkgmgr/actions/publish/git_tags.py

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

src/pkgmgr/actions/publish/pypi_url.py

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

src/pkgmgr/actions/publish/types.py

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

src/pkgmgr/actions/publish/workflow.py

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

src/pkgmgr/actions/release/files.py

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

src/pkgmgr/actions/release/git_ops.py

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

src/pkgmgr/actions/release/versioning.py

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

src/pkgmgr/actions/release/workflow.py

@@ -1,12 +1,14 @@
 from __future__ import annotations
-from typing import Optional
 
 import os
 import sys
 from typing import Optional
 
 from pkgmgr.actions.branch import close_branch
-from pkgmgr.core.git import get_current_branch, GitError
+from pkgmgr.core.git import GitError
+from pkgmgr.core.git.commands import add, commit, push, tag_annotated
+from pkgmgr.core.git.queries import get_current_branch
+from pkgmgr.core.repository.paths import resolve_repo_paths
 
 from .files import (
     update_changelog,
@@ -20,7 +22,6 @@ from .files import (
 from .git_ops import (
     ensure_clean_and_synced,
     is_highest_version_tag,
-    run_git_command,
     update_latest_tag,
 )
 from .prompts import confirm_proceed_release, should_delete_branch
@@ -57,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,
@@ -66,38 +71,46 @@ def _release_impl(
         preview=preview,
     )
 
-    flake_path = os.path.join(repo_root, "flake.nix")
-    update_flake_version(flake_path, new_ver_str, preview=preview)
+    update_flake_version(paths.flake_nix, new_ver_str, preview=preview)
 
-    pkgbuild_path = os.path.join(repo_root, "PKGBUILD")
-    update_pkgbuild_version(pkgbuild_path, new_ver_str, preview=preview)
+    if paths.arch_pkgbuild:
+        update_pkgbuild_version(paths.arch_pkgbuild, new_ver_str, preview=preview)
+    else:
+        print("[INFO] No PKGBUILD found (packaging/arch/PKGBUILD or PKGBUILD). Skipping.")
 
-    spec_path = os.path.join(repo_root, "package-manager.spec")
-    update_spec_version(spec_path, new_ver_str, preview=preview)
+    if paths.rpm_spec:
+        update_spec_version(paths.rpm_spec, new_ver_str, preview=preview)
+    else:
+        print("[INFO] No RPM spec file found. Skipping spec version update.")
 
     effective_message: Optional[str] = message
     if effective_message is None and isinstance(changelog_message, str):
         if changelog_message.strip():
             effective_message = changelog_message.strip()
 
-    debian_changelog_path = os.path.join(repo_root, "debian", "changelog")
     package_name = os.path.basename(repo_root) or "package-manager"
 
-    update_debian_changelog(
-        debian_changelog_path,
-        package_name=package_name,
-        new_version=new_ver_str,
-        message=effective_message,
-        preview=preview,
-    )
+    if paths.debian_changelog:
+        update_debian_changelog(
+            paths.debian_changelog,
+            package_name=package_name,
+            new_version=new_ver_str,
+            message=effective_message,
+            preview=preview,
+        )
+    else:
+        print("[INFO] No debian changelog found. Skipping debian/changelog update.")
 
-    update_spec_changelog(
-        spec_path=spec_path,
-        package_name=package_name,
-        new_version=new_ver_str,
-        message=effective_message,
-        preview=preview,
-    )
+    if paths.rpm_spec:
+        update_spec_changelog(
+            spec_path=paths.rpm_spec,
+            package_name=package_name,
+            new_version=new_ver_str,
+            message=effective_message,
+            preview=preview,
+        )
+
+    # --- Git commit / tag / push ----------------------------------------------
 
     commit_msg = f"Release version {new_ver_str}"
     tag_msg = effective_message or commit_msg
@@ -105,20 +118,19 @@ def _release_impl(
     files_to_add = [
         pyproject_path,
         changelog_path,
-        flake_path,
-        pkgbuild_path,
-        spec_path,
-        debian_changelog_path,
+        paths.flake_nix,
+        paths.arch_pkgbuild,
+        paths.rpm_spec,
+        paths.debian_changelog,
     ]
-    existing_files = [p for p in files_to_add if p and os.path.exists(p)]
+    existing_files = [p for p in files_to_add if isinstance(p, str) and p and os.path.exists(p)]
 
     if preview:
-        for path in existing_files:
-            print(f"[PREVIEW] Would run: git add {path}")
-        print(f'[PREVIEW] Would run: git commit -am "{commit_msg}"')
-        print(f'[PREVIEW] Would run: git tag -a {new_tag} -m "{tag_msg}"')
-        print(f"[PREVIEW] Would run: git push origin {branch}")
-        print(f"[PREVIEW] Would run: git push origin {new_tag}")
+        add(existing_files, preview=True)
+        commit(commit_msg, all=True, preview=True)
+        tag_annotated(new_tag, tag_msg, preview=True)
+        push("origin", branch, preview=True)
+        push("origin", new_tag, preview=True)
 
         if is_highest_version_tag(new_tag):
             update_latest_tag(new_tag, preview=True)
@@ -132,15 +144,13 @@ def _release_impl(
                 print(f"[PREVIEW] Would ask whether to delete branch {branch} after release.")
         return
 
-    for path in existing_files:
-        run_git_command(f"git add {path}")
-
-    run_git_command(f'git commit -am "{commit_msg}"')
-    run_git_command(f'git tag -a {new_tag} -m "{tag_msg}"')
+    add(existing_files, preview=False)
+    commit(commit_msg, all=True, preview=False)
+    tag_annotated(new_tag, tag_msg, preview=False)
 
     # Push branch and ONLY the newly created version tag (no --tags)
-    run_git_command(f"git push origin {branch}")
-    run_git_command(f"git push origin {new_tag}")
+    push("origin", branch, preview=False)
+    push("origin", new_tag, preview=False)
 
     # Update 'latest' only if this is the highest version tag
     try:

src/pkgmgr/actions/repository/clone.py

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

src/pkgmgr/actions/repository/create.py

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

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

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

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

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

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

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

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

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

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

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