Merge branch 'fix/self-install'

- Register --system-update for `pkgmgr update`
- Expose args.system_update for update workflow
- Align CLI with update_repos and E2E tests

https://chatgpt.com/share/693db645-c420-800f-b921-9d5c0356d0ac

.dockerignore

@@ -25,7 +25,5 @@ venv/
 .DS_Store
 Thumbs.db
 
-# Arch pkg artifacts
-*.pkg.tar.*
-*.log
-package-manager-*
+# Logs
+*.log

.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  push:
+    branches-ignore:
+      - main
+  pull_request:
+
+jobs:
+  test-unit:
+    uses: ./.github/workflows/test-unit.yml
+
+  test-integration:
+    uses: ./.github/workflows/test-integration.yml
+
+  test-env-virtual:
+    uses: ./.github/workflows/test-env-virtual.yml
+
+  test-env-nix:
+    uses: ./.github/workflows/test-env-nix.yml
+
+  test-e2e:
+    uses: ./.github/workflows/test-e2e.yml
+
+  test-virgin-user:
+    uses: ./.github/workflows/test-virgin-user.yml
+
+  test-virgin-root:
+    uses: ./.github/workflows/test-virgin-root.yml
+
+  codesniffer-shellcheck:
+    uses: ./.github/workflows/codesniffer-shellcheck.yml
+
+  codesniffer-ruff:
+    uses: ./.github/workflows/codesniffer-ruff.yml

.github/workflows/codesniffer-ruff.yml

@@ -0,0 +1,23 @@
+name: Ruff (Python code sniffer)
+
+on:
+  workflow_call:
+
+jobs:
+  codesniffer-ruff:
+    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/codesniffer-shellcheck.yml

@@ -0,0 +1,14 @@
+name: ShellCheck
+
+on:
+  workflow_call:
+
+jobs:
+  codesniffer-shellcheck:
+    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

@@ -0,0 +1,110 @@
+name: Mark stable commit
+
+on:
+  push:
+    branches:
+      - main          # still run tests for main
+    tags:
+      - 'v*'          # run tests for version tags (e.g. v0.9.1)
+
+jobs:
+  test-unit:
+    uses: ./.github/workflows/test-unit.yml
+
+  test-integration:
+    uses: ./.github/workflows/test-integration.yml
+
+  test-env-virtual:
+    uses: ./.github/workflows/test-env-virtual.yml
+
+  test-env-nix:
+    uses: ./.github/workflows/test-env-nix.yml
+
+  test-e2e:
+    uses: ./.github/workflows/test-e2e.yml
+
+  test-virgin-user:
+    uses: ./.github/workflows/test-virgin-user.yml
+
+  test-virgin-root:
+    uses: ./.github/workflows/test-virgin-root.yml
+
+  codesniffer-shellcheck:
+    uses: ./.github/workflows/codesniffer-shellcheck.yml
+
+  codesniffer-ruff:
+    uses: ./.github/workflows/codesniffer-ruff.yml
+
+  mark-stable:
+    needs:
+      - codesniffer-shellcheck
+      - codesniffer-ruff
+      - test-unit
+      - test-integration
+      - test-env-nix
+      - test-env-virtual
+      - test-e2e
+      - test-virgin-user
+      - test-virgin-root
+    runs-on: ubuntu-latest
+
+    # Only run this job if the push is for a version tag (v*)
+    if: startsWith(github.ref, 'refs/tags/v')
+
+    permissions:
+      contents: write  # Required to move/update the tag
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          fetch-tags: true  # We need all tags for version comparison
+
+      - name: Move 'stable' tag only if this version is the highest
+        run: |
+          set -euo pipefail
+
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+          echo "Ref: $GITHUB_REF"
+          echo "SHA: $GITHUB_SHA"
+
+          VERSION="${GITHUB_REF#refs/tags/}"
+          echo "Current version tag: ${VERSION}"
+
+          echo "Collecting all version tags..."
+          ALL_V_TAGS="$(git tag --list 'v*' || true)"
+
+          if [[ -z "${ALL_V_TAGS}" ]]; then
+            echo "No version tags found. Skipping stable update."
+            exit 0
+          fi
+
+          echo "All version tags:"
+          echo "${ALL_V_TAGS}"
+
+          # Determine highest version using natural version sorting
+          LATEST_TAG="$(printf '%s\n' ${ALL_V_TAGS} | sort -V | tail -n1)"
+
+          echo "Highest version tag: ${LATEST_TAG}"
+
+          if [[ "${VERSION}" != "${LATEST_TAG}" ]]; then
+            echo "Current version ${VERSION} is NOT the highest version."
+            echo "Stable tag will NOT be updated."
+            exit 0
+          fi
+
+          echo "Current version ${VERSION} IS the highest version."
+          echo "Updating 'stable' tag..."
+
+          # Delete existing stable tag (local + remote)
+          git tag -d stable 2>/dev/null || true
+          git push origin :refs/tags/stable || true
+
+          # Create new stable tag
+          git tag stable "$GITHUB_SHA"
+          git push origin stable
+
+          echo "✅ Stable tag updated to ${VERSION}."

.github/workflows/publish-containers.yml

@@ -0,0 +1,66 @@
+name: Publish container images (GHCR)
+
+on:
+  workflow_run:
+    workflows: ["Mark stable commit"]
+    types: [completed]
+
+jobs:
+  publish:
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout repository (with tags)
+        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)"
+
+          V_TAG="$(git tag --points-at "${SHA}" --list 'v*' | sort -V | tail -n1)"
+          [[ -n "$V_TAG" ]] || { echo "No version tag found"; exit 1; }
+          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 "version=${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "is_stable=${IS_STABLE}" >> "$GITHUB_OUTPUT"
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+        with:
+          use: true
+
+      - name: Login to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Publish all images
+        run: |
+          set -euo pipefail
+          OWNER="${{ github.repository_owner }}" \
+          VERSION="${{ steps.info.outputs.version }}" \
+          IS_STABLE="${{ steps.info.outputs.is_stable }}" \
+          bash scripts/build/publish.sh

.github/workflows/test-container.yml

@@ -1,25 +0,0 @@
-name: Test OS Containers
-
-on:
-  push:
-    branches:
-      - main
-      - master
-      - develop
-      - "*"
-  pull_request:
-
-jobs:
-  test-container:
-    runs-on: ubuntu-latest
-    timeout-minutes: 30
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-
-      - name: Show Docker version
-        run: docker version
-
-      - name: Run container tests
-        run: make test-container

.github/workflows/test-e2e.yml

@@ -1,18 +1,16 @@
 name: Test End-To-End
 
 on:
-  push:
-    branches:
-      - main
-      - master
-      - develop
-      - "*"
-  pull_request:
+  workflow_call:
 
 jobs:
   test-e2e:
     runs-on: ubuntu-latest
-    timeout-minutes: 60  # E2E + all distros can be heavier
+    timeout-minutes: 60  # E2E can be heavier
+    strategy:
+      fail-fast: false
+      matrix:
+        distro: [arch, debian, ubuntu, fedora, centos]
 
     steps:
       - name: Checkout repository
@@ -21,5 +19,7 @@ jobs:
       - name: Show Docker version
         run: docker version
 
-      - name: Run E2E tests via make (all distros)
-        run: make test-e2e
+      - name: Run E2E tests via make (${{ matrix.distro }})
+        run: |
+          set -euo pipefail
+          PKGMGR_DISTRO="${{ matrix.distro }}" make test-e2e

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

@@ -0,0 +1,26 @@
+name: Test Virgin Nix (flake only)
+
+on:
+  workflow_call:
+
+jobs:
+  test-env-nix:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+
+    strategy:
+      fail-fast: false
+      matrix:
+        distro: [arch, debian, ubuntu, fedora, centos]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Show Docker version
+        run: docker version
+
+      - name: Nix flake-only test (${{ matrix.distro }})
+        run: |
+          set -euo pipefail
+          PKGMGR_DISTRO="${{ matrix.distro }}" make test-env-nix

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

@@ -0,0 +1,28 @@
+name: Test OS Containers
+
+on:
+  workflow_call:
+
+jobs:
+  test-env-virtual:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        distro: [arch, debian, ubuntu, fedora, centos]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Show commit SHA
+        run: git rev-parse HEAD
+
+      - name: Show Docker version
+        run: docker version
+
+      - name: Run container tests (${{ matrix.distro }})
+        run: |
+          set -euo pipefail
+          PKGMGR_DISTRO="${{ matrix.distro }}" make test-env-virtual

.github/workflows/test-integration.yml

@@ -1,13 +1,7 @@
 name: Test Code Integration
 
 on:
-  push:
-    branches:
-      - main
-      - master
-      - develop
-      - "*"
-  pull_request:
+  workflow_call:
 
 jobs:
   test-integration:
@@ -22,4 +16,4 @@ jobs:
         run: docker version
 
       - name: Run integration tests via make (Arch container)
-        run: make test-integration DISTROS="arch"
+        run: make test-integration PKGMGR_DISTRO="arch"

.github/workflows/test-unit.yml

@@ -1,13 +1,7 @@
 name: Test Units
 
 on:
-  push:
-    branches:
-      - main
-      - master
-      - develop
-      - "*"
-  pull_request:
+  workflow_call:
 
 jobs:
   test-unit:
@@ -22,4 +16,4 @@ jobs:
         run: docker version
 
       - name: Run unit tests via make (Arch container)
-        run: make test-unit DISTROS="arch"
+        run: make test-unit PKGMGR_DISTRO="arch"

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

@@ -0,0 +1,56 @@
+name: Test Virgin Root
+
+on:
+  workflow_call:
+
+jobs:
+  test-virgin-root:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    strategy:
+      fail-fast: false
+      matrix:
+        distro: [arch, debian, ubuntu, fedora, centos]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Show Docker version
+        run: docker version
+
+      # 🔹 BUILD virgin image if missing
+      - name: Build virgin container (${{ matrix.distro }})
+        run: |
+          set -euo pipefail
+          PKGMGR_DISTRO="${{ matrix.distro }}" make build-missing-virgin
+
+      # 🔹 RUN test inside virgin image
+      - name: Virgin ${{ matrix.distro }} pkgmgr test (root)
+        run: |
+          set -euo pipefail
+
+          docker run --rm \
+            -v "$PWD":/src \
+            -v pkgmgr_repos:/root/Repositories \
+            -v pkgmgr_pip_cache:/root/.cache/pip \
+            -w /src \
+            "pkgmgr-${{ matrix.distro }}-virgin" \
+            bash -lc '
+              set -euo pipefail
+
+              git config --global --add safe.directory /src
+
+              make install
+              make setup
+
+              . "$HOME/.venvs/pkgmgr/bin/activate"
+
+              export NIX_CONFIG="experimental-features = nix-command flakes"
+
+              pkgmgr update pkgmgr --clone-mode shallow --no-verification
+              pkgmgr version pkgmgr
+
+              echo ">>> Running Nix-based: nix run .#pkgmgr -- version pkgmgr"
+              nix run /src#pkgmgr -- version pkgmgr
+            '

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

@@ -0,0 +1,65 @@
+name: Test Virgin User
+
+on:
+  workflow_call:
+
+jobs:
+  test-virgin-user:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    strategy:
+      fail-fast: false
+      matrix:
+        distro: [arch, debian, ubuntu, fedora, centos]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Show Docker version
+        run: docker version
+
+      # 🔹 BUILD virgin image if missing
+      - name: Build virgin container (${{ matrix.distro }})
+        run: |
+          set -euo pipefail
+          PKGMGR_DISTRO="${{ matrix.distro }}" make build-missing-virgin
+
+      # 🔹 RUN test inside virgin image as non-root
+      - name: Virgin ${{ matrix.distro }} pkgmgr test (user)
+        run: |
+          set -euo pipefail
+
+          docker run --rm \
+            -v "$PWD":/src \
+            -w /src \
+            "pkgmgr-${{ matrix.distro }}-virgin" \
+            bash -lc '
+              set -euo pipefail
+
+              make install
+
+              useradd -m dev
+              echo "dev ALL=(ALL) NOPASSWD: ALL" > /etc/sudoers.d/dev
+              chmod 0440 /etc/sudoers.d/dev
+              chown -R dev:dev /src
+
+              mkdir -p /nix/store /nix/var/nix /nix/var/log/nix /nix/var/nix/profiles
+              chown -R dev:dev /nix
+              chmod 0755 /nix
+              chmod 1777 /nix/store
+
+              sudo -H -u dev env HOME=/home/dev PKGMGR_DISABLE_NIX_FLAKE_INSTALLER=1 bash -lc "
+                set -euo pipefail
+                cd /src
+
+                make setup-venv
+                . \"\$HOME/.venvs/pkgmgr/bin/activate\"
+
+                pkgmgr version pkgmgr
+
+                export NIX_REMOTE=local
+                export NIX_CONFIG=\"experimental-features = nix-command flakes\"
+                nix run /src#pkgmgr -- version pkgmgr
+              "
+            '

.gitignore

@@ -1,9 +1,6 @@
 
 # Prevents unwanted files from being committed to version control.
 
-# Custom Config file
-config/config.yaml
-
 # Python bytecode
 __pycache__/
 *.pyc
@@ -17,6 +14,7 @@ venv/
 dist/
 build/*
 *.egg-info/
+package-manager-*
 
 # Editor files
 .vscode/
@@ -28,14 +26,10 @@ Thumbs.db
 
 # Nix Cache to speed up tests
 .nix/
+.nix-dev-installed
+flake.lock
 
 # Ignore logs
 *.log
-package-manager-*
 
-# debian 
-debian/package-manager/
-debian/debhelper-build-stamp
-debian/files
-debian/.debhelper/
-debian/package-manager.substvars
+result

CHANGELOG.md

@@ -1,3 +1,225 @@
+## [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**
+
+* New official container images are automatically published on each release.
+* Images are available per distribution and as a default Arch-based image.
+* Stable releases now provide an additional `stable` container tag.
+
+
+## [1.3.1] - 2025-12-12
+
+* Updated documentation with better run and installation instructions
+
+
+## [1.3.0] - 2025-12-12
+
+**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
+* Improved error handling and deterministic behavior for non-root environments
+* Refactored Docker and CI workflows for reproducible multi-distro virgin tests
+* Made E2E tests more realistic by executing real CLI commands
+* Fixed Python compatibility and missing dependencies on affected distros
+
+
+## [1.2.1] - 2025-12-12
+
+**Changed**
+
+* Split container tests into *virtualenv* and *Nix flake* environments to clearly separate Python and Nix responsibilities.
+
+**Fixed**
+
+* Fixed Nix installer permission issues when running under a different user in containers.
+* Improved reliability of post-install Nix initialization across all distro packages.
+
+**CI**
+
+* Replaced generic container tests with explicit environment checks.
+* Validate Nix availability via *nix flake* tests instead of Docker build-time side effects.
+
+
+## [1.2.0] - 2025-12-12
+
+**Release workflow overhaul**
+
+* Introduced a fully structured release workflow with clear phases and safeguards
+* Added preview-first releases with explicit confirmation before execution
+* Automatic handling of *latest* tag when a release is the newest version
+* Optional branch closing after successful releases with interactive confirmation
+* Improved safety by syncing with remote before any changes
+* Clear separation of concerns (workflow, git handling, prompts, versioning)
+
+
+## [1.1.0] - 2025-12-12
+
+* Added *branch drop* for destructive branch deletion and introduced *--force/-f* flags for branch close and branch drop to skip confirmation prompts.
+
+
+## [1.0.0] - 2025-12-11
+
+**Official Stable Release 🎉**
+
+*First stable release of PKGMGR, the multi-distro development and package workflow manager.*
+
+---
+
+**Key Features**
+
+**Core Functionality**
+
+* Manage many repositories with one CLI: `clone`, `update`, `install`, `list`, `path`, `config`
+* Proxy wrappers for Git, Docker/Compose and Make
+* Multi-repo execution with safe *preview mode*
+* Mirror management: `mirror list/diff/merge/setup`
+
+**Releases & Versioning**
+
+* Automated SemVer bumps, tagging and changelog generation
+* Supports PKGBUILD, Debian, RPM, pyproject.toml, flake.nix
+
+**Developer Tools**
+
+* Open repositories in VS Code, file manager or terminal
+* Unified workflows across all major Linux distros
+
+**Nix Integration**
+
+* Cross-distro reproducible builds via Nix flakes
+* CI-tested across all supported environments
+
+---
+
+**Summary**
+PKGMGR 1.0.0 unifies repository management, build tooling, release automation and reproducible multi-distro workflows into one cohesive CLI tool.
+
+*This is the first official stable release.*
+
+
+## [0.10.2] - 2025-12-11
+
+* * Stable tag now updates only when a new highest version is released.
+* Debian package now includes sudo to ensure privilege escalation works reliably.
+* Nix setup is significantly more resilient with retries, correct permissions, and better environment handling.
+* AUR builder setup uses retries so yay installs succeed even under network instability.
+* Nix flake installation now fails only on mandatory parts; optional outputs no longer block installation.
+
+
+## [0.10.1] - 2025-12-11
+
+* Fixed Debian\Ubuntu to pass container e2e tests
+
+
+## [0.10.0] - 2025-12-11
+
+**Mirror System**
+
+* Added SSH mirror support including multi-push and remote probing
+* Introduced mirror management commands and refactored the CLI parser into modules
+
+**CI/CD**
+
+* Migrated to reusable workflows with improved debugging instrumentation
+* Made stable-tag automation reliable for workflow_run events and permissions
+* Ensured deterministic test results by rebuilding all test containers with no-cache
+
+**E2E and Container Tests**
+
+* Fixed Git safe.directory handling across all containers
+* Restored Dockerfile ENTRYPOINT to resolve Nix TLS issues
+* Fixed missing volume errors and hardened the E2E runner
+* Added full Nix flake E2E test matrix across all distro containers
+* Disabled Nix sandboxing for cross-distro builds where required
+
+**Nix and Python Environment**
+
+* Unified Nix Python environment and introduced lazy CLI imports
+* Ensured PyYAML availability and improved Python 3.13 compatibility
+* Refactored flake.nix to remove side effects and rely on generic python3
+
+**Packaging**
+
+* Removed Debian’s hard dependency on Nix
+* Restructured packaging layout and refined build paths
+* Excluded assets from Arch PKGBUILD rsync
+* Cleaned up obsolete ignore files
+
+**Repository Layout**
+
+* Restructured repository to align local, Nix-based, and distro-based build workflows
+* Added Arch support and refined build/purge scripts
+
+
+## [0.9.1] - 2025-12-10
+
+* 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`.
+
+
+## [0.9.0] - 2025-12-10
+
+* Introduce a virgin Arch-based Nix flake E2E workflow that validates pkgmgr’s full flake installation path using shared caches for faster and reproducible CI runs.
+
+
+## [0.8.0] - 2025-12-10
+
+* **v0.7.15 — Installer & Command Resolution Improvements**
+
+* Introduced a unified **layer-based installer pipeline** with clear precedence (OS-packages, Nix, Python, Makefile).
+* Reworked installer structure and improved Python/Nix/Makefile installers, including isolated Python venvs and refined flake-output handling.
+* Fully rewrote **command resolution** with stronger typing, safer fallbacks, and explicit support for `command: null` to mark library-only repositories.
+* Added extensive **unit and integration tests** for installer capability ordering, command resolution, and Nix/Python installer behavior.
+* Expanded documentation with capability hierarchy diagrams and scenario matrices.
+* Removed deprecated repository entries and obsolete configuration files.
+
+
+## [0.7.14] - 2025-12-10
+
+* Fixed the clone-all integration test so that `SystemExit(0)` from the proxy is treated as a successful command instead of a failure.
+
+
+## [0.7.13] - 2025-12-10
+
+### Fix tools path resolution and add tests
+
+- Fixed a crash in `pkgmgr code` caused by missing `directory` metadata by introducing `_resolve_repository_path()` with proper fallbacks to `repositories_base_dir` / `repositories_dir`.
+- Updated `explore`, `terminal` and `code` tool commands to use the new resolver.
+- Improved VS Code workspace generation and path handling.
+- Added unit & E2E tests for tool commands.
+
+
+## [0.7.12] - 2025-12-09
+
+* Fixed self refering alias during setup
+
+
+## [0.7.11] - 2025-12-09
+
+* test: fix installer unit tests for OS packages and Nix dev shell
+
+
 ## [0.7.10] - 2025-12-09
 
 * Fixed test_install_pkgmgr_shallow.py
@@ -45,47 +267,45 @@
 
 ## [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
 
@@ -96,13 +316,10 @@
 - 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
 
@@ -111,5 +328,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

@@ -1,58 +1,58 @@
-# ------------------------------------------------------------
-# Base image selector — overridden by Makefile
-# ------------------------------------------------------------
-ARG BASE_IMAGE=archlinux:latest
-FROM ${BASE_IMAGE}
+# syntax=docker/dockerfile:1
 
 # ------------------------------------------------------------
-# Nix environment defaults
-#
-# Nix itself is installed by your system packages (via init-nix.sh).
-# Here we only define default configuration options.
+# Base image selector — overridden by build args / Makefile
 # ------------------------------------------------------------
-ENV NIX_CONFIG="experimental-features = nix-command flakes"
+ARG BASE_IMAGE
 
-# ------------------------------------------------------------
-# Unprivileged user for Arch package build (makepkg)
-# ------------------------------------------------------------
-RUN useradd -m aur_builder || true
+# ============================================================
+# Target: virgin
+# - installs distro deps (incl. make)
+# - no pkgmgr build
+# - no entrypoint
+# ============================================================
+FROM ${BASE_IMAGE} AS virgin
+SHELL ["/bin/bash", "-lc"]
+
+RUN echo "BASE_IMAGE=${BASE_IMAGE}" && cat /etc/os-release || true
 
-# ------------------------------------------------------------
-# Copy scripts and install distro dependencies
-# ------------------------------------------------------------
 WORKDIR /build
 
-# Copy only scripts first so dependency installation can run early
-COPY scripts/ scripts/
-RUN find scripts -type f -name '*.sh' -exec chmod +x {} \;
+# Copy scripts first so dependency installation can be cached
+COPY scripts/installation/ scripts/installation/
 
-# Install distro-specific build dependencies (and AUR builder on Arch)
-RUN scripts/installation/run-dependencies.sh
+# Install distro-specific build dependencies (including make)
+RUN bash scripts/installation/dependencies.sh
 
-# ------------------------------------------------------------
-# Select distro-specific Docker entrypoint
-# ------------------------------------------------------------
-# Docker entrypoint (distro-agnostic, nutzt run-package.sh)
-# ------------------------------------------------------------
-COPY scripts/docker/entry.sh /usr/local/bin/docker-entry.sh
-RUN chmod +x /usr/local/bin/docker-entry.sh
+# Virgin default
+CMD ["bash"]
 
-# ------------------------------------------------------------
-# Build and install distro-native package-manager package
-# via Makefile `install` target (calls scripts/installation/run-package.sh)
-# ------------------------------------------------------------
+
+# ============================================================
+# Target: full
+# - inherits from virgin
+# - builds + installs pkgmgr
+# - sets entrypoint + default cmd
+# ============================================================
+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
 COPY . .
-RUN find scripts -type f -name '*.sh' -exec chmod +x {} \;
 
-RUN set -e; \
-    echo "Building and installing package-manager via make install..."; \
-    make install; \
-    rm -rf /build
+# Build and install distro-native package-manager package
+RUN set -euo pipefail; \
+  echo "Building and installing package-manager via make install..."; \
+  make install; \
+  cd /; rm -rf /build
+
+# Entry point
+COPY scripts/docker/entry.sh /usr/local/bin/docker-entry.sh
 
-# ------------------------------------------------------------
-# Runtime working directory and dev entrypoint
-# ------------------------------------------------------------
 WORKDIR /src
-
 ENTRYPOINT ["/usr/local/bin/docker-entry.sh"]
 CMD ["pkgmgr", "--help"]

MIRRORS

@@ -0,0 +1,3 @@
+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

Makefile

@@ -1,18 +1,19 @@
-.PHONY: install setup uninstall \
-        test build build-no-cache test-unit test-e2e test-integration \
-        test-container
+.PHONY: install uninstall \
+        build build-no-cache build-no-cache-all build-missing \
+		delete-volumes purge \
+        test test-unit test-e2e test-integration test-env-virtual test-env-nix \
+		setup setup-venv setup-nix
+
+# Distro
+# Options: arch debian ubuntu fedora centos
+DISTROS ?= arch debian ubuntu fedora centos
+PKGMGR_DISTRO ?= arch
+export PKGMGR_DISTRO
 
 # ------------------------------------------------------------
-# Local Nix cache directories in the repo
-# ------------------------------------------------------------
-NIX_STORE_VOLUME := pkgmgr_nix_store
-NIX_CACHE_VOLUME := pkgmgr_nix_cache
-
-# ------------------------------------------------------------
-# Distro list and base images
+# Base images
 # (kept for documentation/reference; actual build logic is in scripts/build)
 # ------------------------------------------------------------
-DISTROS 		  := arch debian ubuntu fedora centos
 BASE_IMAGE_ARCH   := archlinux:latest
 BASE_IMAGE_DEBIAN := debian:stable-slim
 BASE_IMAGE_UBUNTU := ubuntu:latest
@@ -20,7 +21,6 @@ BASE_IMAGE_FEDORA := fedora:latest
 BASE_IMAGE_CENTOS := quay.io/centos/centos:stream9
 
 # Make them available in scripts
-export DISTROS
 export BASE_IMAGE_ARCH  
 export BASE_IMAGE_DEBIAN
 export BASE_IMAGE_UBUNTU
@@ -30,21 +30,53 @@ export BASE_IMAGE_CENTOS
 # PYthon Unittest Pattern
 TEST_PATTERN	:= test_*.py
 export TEST_PATTERN
+export PYTHONPATH := src
 
 # ------------------------------------------------------------
-# PKGMGR setup (developer wrapper -> scripts/installation/main.sh)
+# System install
 # ------------------------------------------------------------
-setup:
-	@bash scripts/installation/main.sh
+install:
+	@echo "Building and installing distro-native package-manager for this system..."
+	@bash scripts/installation/init.sh
+
+# ------------------------------------------------------------
+# PKGMGR setup
+# ------------------------------------------------------------
+
+# Default: keep current auto-detection behavior
+setup: setup-nix setup-venv
+
+# Explicit: developer setup (Python venv + shell RC + install)
+setup-venv: setup-nix
+	@bash scripts/setup/venv.sh
+
+# Explicit: Nix shell mode (no venv, no RC changes)
+setup-nix:
+	@bash scripts/setup/nix.sh
 
 # ------------------------------------------------------------
 # Docker build targets (delegated to scripts/build)
 # ------------------------------------------------------------
-build-no-cache:
-	@bash scripts/build/build-image-no-cache.sh
-
 build:
-	@bash scripts/build/build-image.sh
+	@bash scripts/build/image.sh --target virgin
+	@bash scripts/build/image.sh
+
+build-missing-virgin:
+	@bash scripts/build/image.sh --target virgin --missing
+
+build-missing: build-missing-virgin
+	@bash scripts/build/image.sh --missing
+
+build-no-cache:
+	@bash scripts/build/image.sh --target virgin --no-cache
+	@bash scripts/build/image.sh --no-cache
+
+build-no-cache-all:
+	@set -e; \
+	for d in $(DISTROS); do \
+	  echo "=== build-no-cache: $$d ==="; \
+	  PKGMGR_DISTRO="$$d" $(MAKE) build-no-cache; \
+	done
 
 # ------------------------------------------------------------
 # Test targets (delegated to scripts/test)
@@ -59,24 +91,19 @@ test-integration: build-missing
 test-e2e: build-missing
 	@bash scripts/test/test-e2e.sh
 
-test-container: build-missing
-	@bash scripts/test/test-container.sh
+test-env-virtual: build-missing
+	@bash scripts/test/test-env-virtual.sh
 
-# ------------------------------------------------------------
-# Build only missing container images
-# ------------------------------------------------------------
-build-missing:
-	@bash scripts/build/build-image-missing.sh
+test-env-nix: build-missing
+	@bash scripts/test/test-env-nix.sh
 
-# Combined test target for local + CI (unit + e2e + integration)
-test: test-container test-unit test-e2e test-integration
+# Combined test target for local + CI (unit + integration + e2e)
+test: test-env-virtual test-unit test-integration test-e2e
 
-# ------------------------------------------------------------
-# System install (native packages, calls scripts/installation/run-package.sh)
-# ------------------------------------------------------------
-install:
-	@echo "Building and installing distro-native package-manager for this system..."
-	@bash scripts/installation/run-package.sh
+delete-volumes: 
+	@docker volume rm "pkgmgr_nix_store_${PKGMGR_DISTRO}" "pkgmgr_nix_cache_${PKGMGR_DISTRO}" || echo "No volumes to delete."
+
+purge: delete-volumes build-no-cache
 
 # ------------------------------------------------------------
 # Uninstall target

README.md

@@ -1,116 +1,232 @@
-# Package Manager🤖📦
+# Package Manager 🤖📦
+
+![PKGMGR Banner](assets/banner.jpg)
+
 [![GitHub Sponsors](https://img.shields.io/badge/Sponsor-GitHub%20Sponsors-blue?logo=github)](https://github.com/sponsors/kevinveenbirkenbach)
-[![Patreon](https://img.shields.io/badge/Support-Patreon-orange?logo=patreon)](https://www.patreon.com/c/kevinveenbirkenbach) 
-[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20me%20a%20Coffee-Funding-yellow?logo=buymeacoffee)](https://buymeacoffee.com/kevinveenbirkenbach) [![PayPal](https://img.shields.io/badge/Donate-PayPal-blue?logo=paypal)](https://s.veen.world/paypaldonate)
+[![Patreon](https://img.shields.io/badge/Support-Patreon-orange?logo=patreon)](https://www.patreon.com/c/kevinveenbirkenbach)
+[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20me%20a%20Coffee-Funding-yellow?logo=buymeacoffee)](https://buymeacoffee.com/kevinveenbirkenbach)
+[![PayPal](https://img.shields.io/badge/Donate-PayPal-blue?logo=paypal)](https://s.veen.world/paypaldonate)
 [![GitHub license](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![GitHub repo size](https://img.shields.io/github/repo-size/kevinveenbirkenbach/package-manager)](https://github.com/kevinveenbirkenbach/package-manager)
+[![Mark stable commit](https://github.com/kevinveenbirkenbach/package-manager/actions/workflows/mark-stable.yml/badge.svg)](https://github.com/kevinveenbirkenbach/package-manager/actions/workflows/mark-stable.yml)
 
-*Kevins's* Package Manager is a configurable Python tool designed to manage multiple repositories via Bash. It automates common Git operations such as clone, pull, push, status, and more. Additionally, it handles the creation of executable wrappers and alias links for your repositories.
+[**Kevin's Package Manager (PKGMGR)**](https://s.veen.world/pkgmgr) is a *multi-distro* package manager and workflow orchestrator.
+It helps you **develop, package, release and manage projects across multiple Linux-based
+operating systems** (Arch, Debian, Ubuntu, Fedora, CentOS, …).
+
+PKGMGR is implemented in **Python** and uses **Nix (flakes)** as a foundation for
+distribution-independent builds and tooling. On top of that it provides a rich
+CLI that proxies common developer tools (Git, Docker, Make, …) and glues them
+together into repeatable development workflows.
+
+---
+
+## Why PKGMGR? 🧠
+
+Traditional distro package managers like `apt`, `pacman` or `dnf` focus on a
+single operating system. PKGMGR instead focuses on **your repositories and
+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.
+
+Native package managers are still used where they make sense. PKGMGR coordinates
+the surrounding development, build and release workflows in a consistent way.
+
+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 🚀
 
-- **Installation & Setup:**  
-  Create executable wrappers with auto-detected commands (e.g. `main.sh` or `main.py`).
-  
-- **Git Operations:**  
-  Easily perform `git pull`, `push`, `status`, `commit`, `diff`, `add`, `show`, and `checkout` with extra parameters passed through.
-  
-- **Configuration Management:**  
-  Manage repository configurations via a default file (`config/defaults.yaml`) and a user-specific file (`config/config.yaml`). Initialize, add, delete, or ignore entries using subcommands.
-  
-- **Path & Listing:**  
-  Display repository paths or list all configured packages with their details.
-  
-- **Custom Aliases:**  
-  Generate and manage custom aliases for easy command invocation.
+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.
 
+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.
+
+---
+
+### Full development workflows
+
+PKGMGR is not just a helper around Git commands. Combined with its release and
+versioning features it can drive **end-to-end workflows**:
+
+1. Clone and mirror repositories.
+2. Run tests and builds through `make` or Nix.
+3. Bump versions, update changelogs and tags.
+4. Build distro-specific packages.
+5. Keep all mirrors and working copies in sync.
+
+---
+
+## Architecture & Setup Map 🗺️
+
+The following diagram gives a full overview of:
+
+* PKGMGR’s package structure,
+* the layered installers (OS, foundation, Python, Makefile),
+* and the setup controller that decides which layer to use on a given system.
+
+![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)
+
+---
 
 ## Installation ⚙️
 
-Clone the repository and ensure your `~/.local/bin` is in your system PATH:
+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
 ```
 
-Install make and pip if not installed yet:
+### Dependency installation (optional)
 
-```bash
-pacman -S make python-pip
+System dependencies required **before running any *make* commands** are installed via:
+
+```
+scripts/installation/dependencies.sh
 ```
 
-Then, run the following command to set up the project:
+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
+
+| Command             | Prepares                | Use case              |
+| ------------------- | ----------------------- | --------------------- |
+| **make setup**      | Python venv **and** Nix | Full development & CI |
+| **make setup-venv** | Python venv only        | Local user setup      |
+
+
+##### Full setup (venv + Nix)
 
 ```bash
 make setup
 ```
 
-The `make setup` command will:
-- Make `main.py` executable.
-- Install required packages from `requirements.txt`.
-- Execute `python main.py install` to complete the installation.
+Use this for CI, servers, containers and full development workflows.
 
-## Docker Quickstart 🐳
-
-Alternatively to installing locally, you can use Docker: build the image with
+##### Venv-only setup
 
 ```bash
-docker build --no-cache -t pkgmgr .
+make setup-venv
+source ~/.venvs/pkgmgr/bin/activate
 ```
 
-or alternativ pull it via
+Use this if you want PKGMGR isolated without Nix integration.
+
+---
+
+Alles klar 🙂
+Hier ist der **RUN-Abschnitt ohne Gedankenstriche**, klar nach **Nix, Docker und venv** getrennt:
+
+---
+
+## Run PKGMGR 🧰
+
+PKGMGR can be executed in different environments.
+All modes expose the same CLI and commands.
+
+---
+
+### Run via Nix (no installation)
 
 ```bash
-docker pull kevinveenbirkenbach/pkgmgr:latest
+nix run github:kevinveenbirkenbach/package-manager#pkgmgr -- --help
 ```
 
-and then run
+---
+
+### Run via Docker 🐳
+
+PKGMGR can be executed **inside Docker containers** for CI, testing and isolated
+workflows.
+---
+
+#### 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.
+
+---
+
+#### Run examples
 
 ```bash
-docker run --rm pkgmgr --help
+docker run --rm -it \
+  -v "$PWD":/src \
+  -w /src \
+  ghcr.io/kevinveenbirkenbach/pkgmgr:stable \
+  pkgmgr --help
 ```
 
-## Usage 📖
+---
 
-Run the script with different commands. For example:
+### Run via virtual environment (venv)
 
-- **Install all packages:**
-  ```bash
-  pkgmgr install --all
-  ```
-- **Pull updates for a specific repository:**
-  ```bash
-  pkgmgr pull pkgmgr
-  ```
-- **Commit changes with extra Git parameters:**
-  ```bash
-  pkgmgr commit pkgmgr -- -m "Your commit message"
-  ```
-- **List all configured packages:**
-  ```bash
-  pkgmgr config show
-  ```
-- **Manage configuration:**
-  ```bash
-  pkgmgr config init
-  pkgmgr config add
-  pkgmgr config edit
-  pkgmgr config delete <identifier>
-  pkgmgr config ignore <identifier> --set true
-  ```
+After activating the venv:
+
+```bash
+pkgmgr --help
+```
+
+---
+
+This allows you to choose between zero install execution using Nix, fully prebuilt
+Docker environments or local isolated venv setups with identical command behavior.
+
+---
 
 ## License 📄
 
 This project is licensed under the MIT License.
-
-## Author 👤
-
-Kevin Veen-Birkenbach  
-[https://www.veen.world](https://www.veen.world)
+See the [LICENSE](LICENSE) file for details.
 
 ---
 
-**Repository:** [github.com/kevinveenbirkenbach/package-manager](https://github.com/kevinveenbirkenbach/package-manager)
+## Author 👤
 
-*Created with AI 🤖 - [View conversation](https://chatgpt.com/share/67c728c4-92d0-800f-8945-003fa9bf27c6)*
+Kevin Veen-Birkenbach
+[https://www.veen.world](https://www.veen.world)

TODO.md

@@ -0,0 +1,6 @@
+# to-dos
+
+For the following checkout the implementation map:
+
+- Implement TAGS
+- Implement SIGNING_KEY

_requirements.txt

@@ -1,4 +0,0 @@
-# Legacy file used only if pip still installs from requirements.txt.
-# You may delete this file once you switch entirely to pyproject.toml.
-
-PyYAML

config/defaults.yaml

@@ -380,17 +380,6 @@ repositories:
       - 44D8F11FD62F878E
       - B5690EEEBB952194
 
-- account: kevinveenbirkenbach
-  alias: infinito-presentation
-  description: This repository contains a Infinito.Nexus presentation designed for customers, end-users, investors, developers, and administrators, offering tailored content and insights for each group.
-  homepage: https://github.com/kevinveenbirkenbach/infinito-presentation
-  provider: github.com
-  repository: infinito-presentation
-  verified:
-    gpg_keys:
-      - 44D8F11FD62F878E
-      - B5690EEEBB952194
-
 - account: kevinveenbirkenbach
   description: A lightweight Python utility to generate dynamic color schemes from a single base color. Provides HSL-based color transformations for theming, UI design, and CSS variable generation. Optimized for integration in Python projects, Flask applications, and Ansible roles.
   homepage: https://github.com/kevinveenbirkenbach/colorscheme-generator
@@ -599,17 +588,6 @@ repositories:
       - 44D8F11FD62F878E
       - B5690EEEBB952194
 
-- account: kevinveenbirkenbach
-  desciption: Infinito Inventory Builder — a containerized web application that dynamically generates Ansible inventory files from invokable Infinito.Nexus roles through an interactive, browser-based interface.
-  homepage: https://github.com/kevinveenbirkenbach/infinito-inventory-builder
-  alias: invbuild
-  provider: github.com
-  repository: infinito-inventory-builder
-  verified:
-    gpg_keys:
-      - 44D8F11FD62F878E
-      - B5690EEEBB952194
-
 - account: kevinveenbirkenbach
   desciption: A simple Python CLI tool to safely rename Linux user accounts using usermod — including home directory migration and validation checks.
   homepage: https://github.com/kevinveenbirkenbach/user-rename

config/wip.yml

@@ -1,7 +0,0 @@
-- account: kevinveenbirkenbach
-  alias: gkfdrtdtcntr
-  provider: github.com
-  repository: federated-to-central-social-network-bridge
-  verified:
-    gpg_keys:
-    - 44D8F11FD62F878E

debian/postinst

@@ -1,14 +0,0 @@
-#!/bin/sh
-set -e
-
-case "$1" in
-    configure)
-        if [ -x /usr/lib/package-manager/init-nix.sh ]; then
-            /usr/lib/package-manager/init-nix.sh || true
-        else
-            echo ">>> Warning: /usr/lib/package-manager/init-nix.sh not found or not executable."
-        fi
-        ;;
-esac
-
-exit 0

flake.nix

@@ -26,12 +26,13 @@
       packages = forAllSystems (system:
         let
           pkgs = nixpkgs.legacyPackages.${system};
+          python = pkgs.python311;
           pyPkgs = pkgs.python311Packages;
         in
         rec {
           pkgmgr = pyPkgs.buildPythonApplication {
             pname   = "package-manager";
-            version = "0.7.10";
+            version = "1.5.0";
 
             # Use the git repo as source
             src = ./.;
@@ -45,18 +46,17 @@
               pyPkgs.wheel
             ];
 
-            # Runtime dependencies (matches [project.dependencies])
+            # Runtime dependencies (matches [project.dependencies] in pyproject.toml)
             propagatedBuildInputs = [
               pyPkgs.pyyaml
-              # Add more here if needed, e.g.:
-              # pyPkgs.click
-              # pyPkgs.rich
+              pyPkgs.pip
             ];
 
             doCheck = false;
 
             pythonImportsCheck = [ "pkgmgr" ];
           };
+
           default = pkgmgr;
         }
       );
@@ -67,23 +67,42 @@
       devShells = forAllSystems (system:
         let
           pkgs = nixpkgs.legacyPackages.${system};
-          pkgmgrPkg = self.packages.${system}.pkgmgr;
 
           ansiblePkg =
             if pkgs ? ansible-core then pkgs.ansible-core
             else pkgs.ansible;
+
+          # Use the same Python version as the package (3.11)
+          python = pkgs.python311;
+
+          pythonWithDeps = python.withPackages (ps: [
+            ps.pip
+            ps.pyyaml
+          ]);
         in
         {
           default = pkgs.mkShell {
             buildInputs = [
-              pkgmgrPkg
+              pythonWithDeps
               pkgs.git
               ansiblePkg
             ];
 
             shellHook = ''
+              # Ensure our Python with dependencies is preferred on PATH
+              export PATH=${pythonWithDeps}/bin:$PATH
+
+              # Ensure src/ layout is importable:
+              #   pkgmgr lives in ./src/pkgmgr
+              export PYTHONPATH="$PWD/src:${PYTHONPATH:-}"
+              # Also add repo root in case tools/tests rely on it
+              export PYTHONPATH="$PWD:$PYTHONPATH"
+
               echo "Entered pkgmgr development shell for ${system}"
-              echo "pkgmgr CLI is available via the flake build"
+              echo "Python used in this shell:"
+              python --version
+              echo "pkgmgr CLI (from source) is available via:"
+              echo "  python -m pkgmgr.cli --help"
             '';
           };
         }

package-manager.install

@@ -1,11 +0,0 @@
-post_install() {
-  /usr/lib/package-manager/init-nix.sh || true
-}
-
-post_upgrade() {
-  /usr/lib/package-manager/init-nix.sh || true
-}
-
-post_remove() {
-  echo ">>> package-manager removed. Nix itself was not removed."
-}

packaging/arch/.gitignore

@@ -0,0 +1,6 @@
+# Arch pkg artifacts
+*.pkg.tar.*
+*.log
+package-manager-*
+src/
+pkg/

packaging/arch/PKGBUILD

@@ -1,7 +1,7 @@
 # Maintainer: Kevin Veen-Birkenbach <info@veen.world>
 
 pkgname=package-manager
-pkgver=0.7.10
+pkgver=0.9.1
 pkgrel=1
 pkgdesc="Local-flake wrapper for Kevin's package-manager (Nix-based)."
 arch=('any')
@@ -15,7 +15,7 @@ makedepends=('rsync')
 install=${pkgname}.install
 
 # Local source checkout — avoids the tarball requirement.
-# This assumes you build the package from inside the main project repository.
+# We build from the project root (two levels above packaging/arch/).
 source=()
 sha256sums=()
 
@@ -24,12 +24,18 @@ _srcdir_name="source"
 
 prepare() {
   mkdir -p "$srcdir/$_srcdir_name"
+
+  local project_root
+  project_root="$(cd "$startdir/../.." && pwd)"
+
   rsync -a \
     --exclude=".git" \
     --exclude=".github" \
     --exclude="pkg" \
     --exclude="srcpkg" \
-    "$startdir/" "$srcdir/$_srcdir_name/"
+    --exclude="packaging" \
+    --exclude="assets" \
+    "$project_root/" "$srcdir/$_srcdir_name/"
 }
 
 build() {
@@ -44,9 +50,10 @@ package() {
   install -Dm0755 "scripts/pkgmgr-wrapper.sh" \
     "$pkgdir/usr/bin/pkgmgr"
 
-  # Install Nix init helper
-  install -Dm0755 "scripts/init-nix.sh" \
-    "$pkgdir/usr/lib/package-manager/init-nix.sh"
+  # Install Nix bootstrap (init + lib)
+  install -d "$pkgdir/usr/lib/package-manager/nix"
+  cp -a scripts/nix/* "$pkgdir/usr/lib/package-manager/nix/"
+  chmod 0755 "$pkgdir/usr/lib/package-manager/nix/init.sh"
 
   # Install the full repository into /usr/lib/package-manager
   mkdir -p "$pkgdir/usr/lib/package-manager"
@@ -62,7 +69,8 @@ package() {
     "$pkgdir/usr/lib/package-manager/PKGBUILD" \
     "$pkgdir/usr/lib/package-manager/Dockerfile" \
     "$pkgdir/usr/lib/package-manager/debian" \
+    "$pkgdir/usr/lib/package-manager/packaging" \
     "$pkgdir/usr/lib/package-manager/.gitignore" \
     "$pkgdir/usr/lib/package-manager/__pycache__" \
-    "$pkgdir/usr/lib/package-manager/.gitkeep"
+    "$pkgdir/usr/lib/package-manager/.gitkeep" || true
 }

packaging/arch/package-manager.install

@@ -0,0 +1,11 @@
+post_install() {
+  /usr/lib/package-manager/nix/init.sh || echo ">>> ERROR: /usr/lib/package-manager/nix/init.sh not found or not executable."
+}
+
+post_upgrade() {
+  /usr/lib/package-manager/nix/init.sh || echo ">>> ERROR: /usr/lib/package-manager/nix/init.sh not found or not executable."
+}
+
+post_remove() {
+  echo ">>> package-manager removed. Nix itself was not removed."
+}

packaging/debian/.gitignore

@@ -0,0 +1,6 @@
+# debian 
+package-manager/
+debhelper-build-stamp
+files
+.debhelper/
+package-manager.substvars

packaging/debian/changelog

@@ -1,3 +1,55 @@
+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.
+* 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`.
+
+ -- Kevin Veen-Birkenbach <kevin@veen.world>  Wed, 10 Dec 2025 22:56:01 +0100
+
+package-manager (0.9.0-1) unstable; urgency=medium
+
+  * Introduce a virgin Arch-based Nix flake E2E workflow that validates pkgmgr’s full flake installation path using shared caches for faster and reproducible CI runs.
+
+ -- Kevin Veen-Birkenbach <kevin@veen.world>  Wed, 10 Dec 2025 18:38:07 +0100
+
+package-manager (0.8.0-1) unstable; urgency=medium
+
+  * **v0.7.15 — Installer & Command Resolution Improvements**
+
+* Introduced a unified **layer-based installer pipeline** with clear precedence (OS-packages, Nix, Python, Makefile).
+* Reworked installer structure and improved Python/Nix/Makefile installers, including isolated Python venvs and refined flake-output handling.
+* Fully rewrote **command resolution** with stronger typing, safer fallbacks, and explicit support for `command: null` to mark library-only repositories.
+* Added extensive **unit and integration tests** for installer capability ordering, command resolution, and Nix/Python installer behavior.
+* Expanded documentation with capability hierarchy diagrams and scenario matrices.
+* Removed deprecated repository entries and obsolete configuration files.
+
+ -- Kevin Veen-Birkenbach <kevin@veen.world>  Wed, 10 Dec 2025 17:31:57 +0100
+
+package-manager (0.7.14-1) unstable; urgency=medium
+
+  * Fixed the clone-all integration test so that `SystemExit(0)` from the proxy is treated as a successful command instead of a failure.
+
+ -- Kevin Veen-Birkenbach <kevin@veen.world>  Wed, 10 Dec 2025 10:38:33 +0100
+
+package-manager (0.7.13-1) unstable; urgency=medium
+
+  * Automated release.
+
+ -- Kevin Veen-Birkenbach <kevin@veen.world>  Wed, 10 Dec 2025 10:27:24 +0100
+
+package-manager (0.7.12-1) unstable; urgency=medium
+
+  * Fixed self refering alias during setup
+
+ -- Kevin Veen-Birkenbach <kevin@veen.world>  Tue, 09 Dec 2025 23:36:35 +0100
+
+package-manager (0.7.11-1) unstable; urgency=medium
+
+  * test: fix installer unit tests for OS packages and Nix dev shell
+
+ -- Kevin Veen-Birkenbach <kevin@veen.world>  Tue, 09 Dec 2025 23:16:46 +0100
+
 package-manager (0.7.10-1) unstable; urgency=medium
 
   * Fixed test_install_pkgmgr_shallow.py

packaging/debian/control

@@ -9,7 +9,7 @@ Homepage: https://github.com/kevinveenbirkenbach/package-manager
 
 Package: package-manager
 Architecture: any
-Depends: nix, ${misc:Depends}
+Depends: sudo, ${misc:Depends}
 Description: Wrapper that runs Kevin's package-manager via Nix flake
  This package provides the `pkgmgr` command, which runs Kevin's package
  manager via a local Nix flake

packaging/debian/postinst

@@ -0,0 +1,10 @@
+#!/bin/sh
+set -e
+
+case "$1" in
+    configure)
+        /usr/lib/package-manager/nix/init.sh || echo ">>> ERROR: /usr/lib/package-manager/nix/init.sh not found or not executable."
+        ;;
+esac
+
+exit 0

packaging/debian/rules

@@ -20,7 +20,7 @@ override_dh_auto_test:
 	:
 
 # ---------------------------------------------------------------------------
-# Install phase: copy wrapper + init script + full project source
+# Install phase: copy wrapper + Nix bootstrap (init + lib) + full project source
 # ---------------------------------------------------------------------------
 override_dh_auto_install:
 	# Create target directories
@@ -31,9 +31,11 @@ override_dh_auto_install:
 	install -m0755 scripts/pkgmgr-wrapper.sh \
 		debian/package-manager/usr/bin/pkgmgr
 
-	# Install shared Nix init script
-	install -m0755 scripts/init-nix.sh \
-		debian/package-manager/usr/lib/package-manager/init-nix.sh
+	# Install Nix bootstrap (init + lib)
+	install -d debian/package-manager/usr/lib/package-manager/nix
+	cp -a scripts/nix/* \
+		debian/package-manager/usr/lib/package-manager/nix/
+	chmod 0755 debian/package-manager/usr/lib/package-manager/nix/init.sh
 
 	# Copy full project source into /usr/lib/package-manager,
 	# but do not include the debian/ directory itself.

packaging/fedora/package-manager.spec

@@ -1,5 +1,5 @@
 Name:           package-manager
-Version:        0.7.10
+Version:        0.9.1
 Release:        1%{?dist}
 Summary:        Wrapper that runs Kevin's package-manager via Nix flake
 
@@ -12,7 +12,7 @@ BuildArch:      noarch
 # NOTE:
 # Nix is a runtime requirement, but it is *not* declared here as a hard
 # RPM dependency, because many distributions do not ship a "nix" RPM.
-# Instead, Nix is installed and initialized by init-nix.sh, which is
+# Instead, Nix is installed and initialized by nix/init.sh, which is
 # called in the %post scriptlet below.
 
 %description
@@ -22,7 +22,7 @@ manager via a local Nix flake:
   nix run /usr/lib/package-manager#pkgmgr -- ...
 
 Nix is a runtime requirement and is installed/initialized by the
-init-nix.sh helper during package installation if it is not yet
+nix/init.sh helper during package installation if it is not yet
 available on the system.
 
 %prep
@@ -34,8 +34,8 @@ available on the system.
 
 %install
 rm -rf %{buildroot}
+
 install -d %{buildroot}%{_bindir}
-# Install project tree into a fixed, architecture-independent location.
 install -d %{buildroot}/usr/lib/package-manager
 
 # Copy full project source into /usr/lib/package-manager
@@ -44,8 +44,10 @@ cp -a . %{buildroot}/usr/lib/package-manager/
 # Wrapper
 install -m0755 scripts/pkgmgr-wrapper.sh %{buildroot}%{_bindir}/pkgmgr
 
-# Shared Nix init script (ensure it is executable in the installed tree)
-install -m0755 scripts/init-nix.sh %{buildroot}/usr/lib/package-manager/init-nix.sh
+# Nix bootstrap (init + lib)
+install -d %{buildroot}/usr/lib/package-manager/nix
+cp -a scripts/nix/* %{buildroot}/usr/lib/package-manager/nix/
+chmod 0755 %{buildroot}/usr/lib/package-manager/nix/init.sh
 
 # Remove packaging-only and development artefacts from the installed tree
 rm -rf \
@@ -60,12 +62,7 @@ rm -rf \
   %{buildroot}/usr/lib/package-manager/.gitkeep || true
 
 %post
-# Initialize Nix (if needed) after installing the package-manager files.
-if [ -x /usr/lib/package-manager/init-nix.sh ]; then
-    /usr/lib/package-manager/init-nix.sh || true
-else
-    echo ">>> Warning: /usr/lib/package-manager/init-nix.sh not found or not executable."
-fi
+/usr/lib/package-manager/nix/init.sh || echo ">>> ERROR: /usr/lib/package-manager/nix/init.sh not found or not executable."
 
 %postun
 echo ">>> package-manager removed. Nix itself was not removed."
@@ -77,6 +74,37 @@ echo ">>> package-manager removed. Nix itself was not removed."
 /usr/lib/package-manager/
 
 %changelog
+* 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.
+* Fixed repository directory resolution; improved `pkgmgr path` and `pkgmgr shell`; added full unit/E2E coverage.
+* Removed deprecated files and updated `.gitignore`.
+
+* Wed Dec 10 2025 Kevin Veen-Birkenbach <kevin@veen.world> - 0.9.0-1
+- Introduce a virgin Arch-based Nix flake E2E workflow that validates pkgmgr’s full flake installation path using shared caches for faster and reproducible CI runs.
+
+* Wed Dec 10 2025 Kevin Veen-Birkenbach <kevin@veen.world> - 0.8.0-1
+- **v0.7.15 — Installer & Command Resolution Improvements**
+
+* Introduced a unified **layer-based installer pipeline** with clear precedence (OS-packages, Nix, Python, Makefile).
+* Reworked installer structure and improved Python/Nix/Makefile installers, including isolated Python venvs and refined flake-output handling.
+* Fully rewrote **command resolution** with stronger typing, safer fallbacks, and explicit support for `command: null` to mark library-only repositories.
+* Added extensive **unit and integration tests** for installer capability ordering, command resolution, and Nix/Python installer behavior.
+* Expanded documentation with capability hierarchy diagrams and scenario matrices.
+* Removed deprecated repository entries and obsolete configuration files.
+
+* Wed Dec 10 2025 Kevin Veen-Birkenbach <kevin@veen.world> - 0.7.14-1
+- Fixed the clone-all integration test so that `SystemExit(0)` from the proxy is treated as a successful command instead of a failure.
+
+* Wed Dec 10 2025 Kevin Veen-Birkenbach <kevin@veen.world> - 0.7.13-1
+- Automated release.
+
+* Tue Dec 09 2025 Kevin Veen-Birkenbach <kevin@veen.world> - 0.7.12-1
+- Fixed self refering alias during setup
+
+* Tue Dec 09 2025 Kevin Veen-Birkenbach <kevin@veen.world> - 0.7.11-1
+- test: fix installer unit tests for OS packages and Nix dev shell
+
 * Tue Dec 09 2025 Kevin Veen-Birkenbach <kevin@veen.world> - 0.7.10-1
 - Fixed test_install_pkgmgr_shallow.py
 

pkgmgr.yml

@@ -1,7 +0,0 @@
-version: 1
-
-author: "Kevin Veen-Birkenbach"
-url: "https://github.com/kevinveenbirkenbach/package-manager"
-description: "A configurable Python-based package manager for managing multiple repositories via Bash."
-
-dependencies: []

pkgmgr/actions/branch/__init__.py

@@ -1,235 +0,0 @@
-# pkgmgr/actions/branch/__init__.py
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-
-"""
-High-level helpers for branch-related operations.
-
-This module encapsulates the actual Git logic so the CLI layer
-(pkgmgr.cli.commands.branch) stays thin and testable.
-"""
-
-from __future__ import annotations
-
-from typing import Optional
-
-from pkgmgr.core.git import run_git, GitError, get_current_branch
-
-
-# ---------------------------------------------------------------------------
-# Branch creation (open)
-# ---------------------------------------------------------------------------
-
-def open_branch(
-    name: Optional[str],
-    base_branch: str = "main",
-    fallback_base: str = "master",
-    cwd: str = ".",
-) -> None:
-    """
-    Create and push a new feature branch on top of a base branch.
-
-    The base branch is resolved by:
-        1. Trying 'base_branch' (default: 'main')
-        2. Falling back to 'fallback_base' (default: 'master')
-
-    Steps:
-        1) git fetch origin
-        2) git checkout <resolved_base>
-        3) git pull origin <resolved_base>
-        4) git checkout -b <name>
-        5) git push -u origin <name>
-
-    If `name` is None or empty, the user is prompted to enter one.
-    """
-
-    # Request name interactively if not provided
-    if not name:
-        name = input("Enter new branch name: ").strip()
-
-    if not name:
-        raise RuntimeError("Branch name must not be empty.")
-
-    # Resolve which base branch to use (main or master)
-    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
-
-    # 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 for base branch
-    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 to origin
-    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
-
-
-# ---------------------------------------------------------------------------
-# Base branch resolver (shared by open/close)
-# ---------------------------------------------------------------------------
-
-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."
-    )
-
-
-# ---------------------------------------------------------------------------
-# Branch closing (merge + deletion)
-# ---------------------------------------------------------------------------
-
-def close_branch(
-    name: Optional[str],
-    base_branch: str = "main",
-    fallback_base: str = "master",
-    cwd: str = ".",
-) -> None:
-    """
-    Merge a feature branch into the base branch and delete it afterwards.
-
-    Steps:
-        1) Determine the branch name (argument or current branch)
-        2) Resolve base branch (main/master)
-        3) Ask for confirmation
-        4) git fetch origin
-        5) git checkout <base>
-        6) git pull origin <base>
-        7) git merge --no-ff <name>
-        8) git push origin <base>
-        9) Delete branch locally
-       10) Delete branch on origin (best effort)
-    """
-
-    # 1) Determine which branch should be closed
-    if not name:
-        try:
-            name = get_current_branch(cwd=cwd)
-        except GitError as exc:
-            raise RuntimeError(f"Failed to detect current branch: {exc}") from exc
-
-    if not name:
-        raise RuntimeError("Branch name must not be empty.")
-
-    # 2) Resolve base branch
-    target_base = _resolve_base_branch(base_branch, fallback_base, cwd=cwd)
-
-    if name == target_base:
-        raise RuntimeError(
-            f"Refusing to close base branch {target_base!r}. "
-            "Please specify a feature branch."
-        )
-
-    # 3) Ask user for confirmation
-    prompt = (
-        f"Merge branch '{name}' into '{target_base}' and delete it afterwards? "
-        "(y/N): "
-    )
-    answer = input(prompt).strip().lower()
-    if answer != "y":
-        print("Aborted closing branch.")
-        return
-
-    # 4) Fetch from origin
-    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
-
-    # 5) 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
-
-    # 6) Pull latest base state
-    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
-
-    # 7) Merge the feature branch
-    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
-
-    # 8) Push updated base
-    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
-
-    # 9) Delete branch locally
-    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
-
-    # 10) Delete branch on origin (best effort)
-    try:
-        run_git(["push", "origin", "--delete", name], cwd=cwd)
-    except GitError as exc:
-        raise RuntimeError(
-            f"Branch {name!r} was deleted locally, but remote deletion failed: {exc}"
-        ) from exc

pkgmgr/actions/release/git_ops.py

@@ -1,95 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-
-"""
-Git-related helpers for the release workflow.
-
-Responsibilities:
-  - Run Git (or shell) commands with basic error reporting.
-  - Ensure main/master are synchronized with origin before tagging.
-  - Maintain the floating 'latest' tag that always points to the newest
-    release tag.
-"""
-
-from __future__ import annotations
-
-import subprocess
-
-from pkgmgr.core.git import GitError
-
-
-def run_git_command(cmd: str) -> None:
-    """
-    Run a Git (or shell) command with basic error reporting.
-
-    The command is executed via the shell, primarily for readability
-    when printed (as in 'git commit -am "msg"').
-    """
-    print(f"[GIT] {cmd}")
-    try:
-        subprocess.run(cmd, shell=True, check=True)
-    except subprocess.CalledProcessError as exc:
-        print(f"[ERROR] Git command failed: {cmd}")
-        print(f"        Exit code: {exc.returncode}")
-        if exc.stdout:
-            print("--- stdout ---")
-            print(exc.stdout)
-        if exc.stderr:
-            print("--- stderr ---")
-            print(exc.stderr)
-        raise GitError(f"Git command failed: {cmd}") from exc
-
-
-def sync_branch_with_remote(branch: str, preview: bool = False) -> None:
-    """
-    Ensure the local main/master branch is up-to-date before tagging.
-
-    Behaviour:
-      - For main/master: run 'git fetch origin' and 'git pull origin <branch>'.
-      - For all other branches: only log that no automatic sync is performed.
-    """
-    if branch not in ("main", "master"):
-        print(
-            f"[INFO] Skipping automatic git pull for non-main/master branch "
-            f"{branch}."
-        )
-        return
-
-    print(
-        f"[INFO] Updating branch {branch} from origin before creating tags..."
-    )
-
-    if preview:
-        print("[PREVIEW] Would run: git fetch origin")
-        print(f"[PREVIEW] Would run: git pull origin {branch}")
-        return
-
-    run_git_command("git fetch origin")
-    run_git_command(f"git pull origin {branch}")
-
-
-def update_latest_tag(new_tag: str, preview: bool = False) -> None:
-    """
-    Move the floating 'latest' tag to the newly created release tag.
-
-    Implementation details:
-      - We explicitly dereference the tag object via `<tag>^{}` so that
-        'latest' always points at the underlying commit, not at another tag.
-      - We create/update 'latest' as an annotated tag with a short message so
-        Git configurations that enforce annotated/signed tags do not fail
-        with "no tag message".
-    """
-    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} '
-        f'-m "Floating latest tag for {new_tag}"'
-    )
-    run_git_command("git push origin latest --force")

pkgmgr/actions/repository/install/__init__.py

@@ -1,294 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-
-"""
-Repository installation pipeline for pkgmgr.
-
-This module orchestrates the installation of repositories by:
-
-  1. Ensuring the repository directory exists (cloning if necessary).
-  2. Verifying the repository according to the configured policies.
-  3. Creating executable links using create_ink(), after resolving the
-     appropriate command via resolve_command_for_repo().
-  4. Running a sequence of modular installer components that handle
-     specific technologies or manifests (PKGBUILD, Nix flakes, Python
-     via pyproject.toml, Makefile, OS-specific package metadata).
-
-The goal is to keep this file thin and delegate most logic to small,
-focused installer classes.
-"""
-
-import os
-from typing import List, Dict, Any
-
-from pkgmgr.core.repository.identifier import get_repo_identifier
-from pkgmgr.core.repository.dir import get_repo_dir
-from pkgmgr.core.command.ink import create_ink
-from pkgmgr.core.repository.verify import verify_repository
-from pkgmgr.actions.repository.clone import clone_repos
-from pkgmgr.actions.repository.install.context import RepoContext
-from pkgmgr.core.command.resolve import resolve_command_for_repo
-
-# Installer implementations
-from pkgmgr.actions.repository.install.installers.os_packages import (
-    ArchPkgbuildInstaller,
-    DebianControlInstaller,
-    RpmSpecInstaller,
-)
-from pkgmgr.actions.repository.install.installers.nix_flake import NixFlakeInstaller
-from pkgmgr.actions.repository.install.installers.python import PythonInstaller
-from pkgmgr.actions.repository.install.installers.makefile import MakefileInstaller
-
-
-# Layering:
-#   1) OS packages: PKGBUILD / debian/control / RPM spec  → os-deps.*
-#   2) Nix flakes (flake.nix)                            → e.g. python-runtime, make-install
-#   3) Python (pyproject.toml)                           → e.g. python-runtime, make-install
-#   4) Makefile fallback                                 → e.g. make-install
-INSTALLERS = [
-    ArchPkgbuildInstaller(),        # Arch
-    DebianControlInstaller(),       # Debian/Ubuntu
-    RpmSpecInstaller(),             # Fedora/RHEL/CentOS
-    NixFlakeInstaller(),            # flake.nix (Nix layer)
-    PythonInstaller(),              # pyproject.toml
-    MakefileInstaller(),            # generic 'make install'
-]
-
-
-def _ensure_repo_dir(
-    repo: Dict[str, Any],
-    repositories_base_dir: str,
-    all_repos: List[Dict[str, Any]],
-    preview: bool,
-    no_verification: bool,
-    clone_mode: str,
-    identifier: str,
-) -> str:
-    """
-    Ensure the repository directory exists. If not, attempt to clone it.
-
-    Returns the repository directory path or an empty string if cloning failed.
-    """
-    repo_dir = get_repo_dir(repositories_base_dir, repo)
-
-    if not os.path.exists(repo_dir):
-        print(f"Repository directory '{repo_dir}' does not exist. Cloning it now...")
-        clone_repos(
-            [repo],
-            repositories_base_dir,
-            all_repos,
-            preview,
-            no_verification,
-            clone_mode,
-        )
-        if not os.path.exists(repo_dir):
-            print(f"Cloning failed for repository {identifier}. Skipping installation.")
-            return ""
-
-    return repo_dir
-
-
-def _verify_repo(
-    repo: Dict[str, Any],
-    repo_dir: str,
-    no_verification: bool,
-    identifier: str,
-) -> bool:
-    """
-    Verify the repository using verify_repository().
-
-    Returns True if installation should proceed, False if it should be skipped.
-    """
-    verified_info = repo.get("verified")
-    verified_ok, errors, commit_hash, signing_key = verify_repository(
-        repo,
-        repo_dir,
-        mode="local",
-        no_verification=no_verification,
-    )
-
-    if not no_verification and verified_info and not verified_ok:
-        print(f"Warning: Verification failed for {identifier}:")
-        for err in errors:
-            print(f"  - {err}")
-        choice = input("Proceed with installation? (y/N): ").strip().lower()
-        if choice != "y":
-            print(f"Skipping installation for {identifier}.")
-            return False
-
-    return True
-
-
-def _create_context(
-    repo: Dict[str, Any],
-    identifier: str,
-    repo_dir: str,
-    repositories_base_dir: str,
-    bin_dir: str,
-    all_repos: List[Dict[str, Any]],
-    no_verification: bool,
-    preview: bool,
-    quiet: bool,
-    clone_mode: str,
-    update_dependencies: bool,
-) -> RepoContext:
-    """
-    Build a RepoContext for the given repository and parameters.
-    """
-    return RepoContext(
-        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,
-    )
-
-
-def install_repos(
-    selected_repos: List[Dict[str, Any]],
-    repositories_base_dir: str,
-    bin_dir: str,
-    all_repos: List[Dict[str, Any]],
-    no_verification: bool,
-    preview: bool,
-    quiet: bool,
-    clone_mode: str,
-    update_dependencies: bool,
-) -> None:
-    """
-    Install repositories by creating symbolic links and processing standard
-    manifest files (PKGBUILD, flake.nix, Python manifests, Makefile, etc.)
-    via dedicated installer components.
-
-    Any installer failure (SystemExit) is treated as fatal and will abort
-    the current installation.
-    """
-    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:
-            continue
-
-        if not _verify_repo(
-            repo=repo,
-            repo_dir=repo_dir,
-            no_verification=no_verification,
-            identifier=identifier,
-        ):
-            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,
-        )
-
-        # ------------------------------------------------------------
-        # Resolve the command for this repository before creating the link.
-        # If no command is resolved, no link will be created.
-        # ------------------------------------------------------------
-        resolved_command = resolve_command_for_repo(
-            repo=repo,
-            repo_identifier=identifier,
-            repo_dir=repo_dir,
-        )
-
-        if resolved_command:
-            repo["command"] = resolved_command
-        else:
-            repo.pop("command", None)
-
-        # ------------------------------------------------------------
-        # Create the symlink using create_ink (if a command is set).
-        # ------------------------------------------------------------
-        create_ink(
-            repo,
-            repositories_base_dir,
-            bin_dir,
-            all_repos,
-            quiet=quiet,
-            preview=preview,
-        )
-
-        # Track which logical capabilities have already been provided by
-        # earlier installers for this repository. This allows us to skip
-        # installers that would only duplicate work (e.g. Python runtime
-        # already provided by Nix flake → skip pyproject/Makefile).
-        provided_capabilities: set[str] = set()
-
-        # Run all installers that support this repository, but only if they
-        # provide at least one capability that is not yet satisfied.
-        for installer in INSTALLERS:
-            if not installer.supports(ctx):
-                continue
-
-            caps = installer.discover_capabilities(ctx)
-
-            # If the installer declares capabilities and *all* of them are
-            # already provided, we can safely skip it.
-            if caps and caps.issubset(provided_capabilities):
-                if not quiet:
-                    print(
-                        f"Skipping installer {installer.__class__.__name__} "
-                        f"for {identifier} – capabilities {caps} already provided."
-                    )
-                continue
-
-            # ------------------------------------------------------------
-            # Debug output + clear error if an installer fails
-            # ------------------------------------------------------------
-            if not quiet:
-                print(
-                    f"[pkgmgr] Running installer {installer.__class__.__name__} "
-                    f"for {identifier} in '{repo_dir}' "
-                    f"(new capabilities: {caps or '∅'})..."
-                )
-
-            try:
-                installer.run(ctx)
-            except SystemExit as exc:
-                exit_code = exc.code if isinstance(exc.code, int) else str(exc.code)
-
-                print(
-                    f"[ERROR] Installer {installer.__class__.__name__} failed "
-                    f"for repository {identifier} (dir: {repo_dir}) "
-                    f"with exit code {exit_code}."
-                )
-                print(
-                    "[ERROR] This usually means an underlying command failed "
-                    "(e.g. 'make install', 'nix build', 'pip install', ...)."
-                )
-                print(
-                    "[ERROR] Check the log above for the exact command output. "
-                    "You can also run this repository in isolation via:\n"
-                    f"        pkgmgr install {identifier} --clone-mode shallow --no-verification"
-                )
-
-                # Re-raise so that CLI/tests fail clearly,
-                # but now with much more context.
-                raise
-
-            # Only merge capabilities if the installer succeeded
-            provided_capabilities.update(caps)

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

@@ -1,19 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-
-"""
-Installer package for pkgmgr.
-
-This exposes all installer classes so users can import them directly from
-pkgmgr.actions.repository.install.installers.
-"""
-
-from pkgmgr.actions.repository.install.installers.base import BaseInstaller  # noqa: F401
-from pkgmgr.actions.repository.install.installers.nix_flake import NixFlakeInstaller  # noqa: F401
-from pkgmgr.actions.repository.install.installers.python import PythonInstaller  # noqa: F401
-from pkgmgr.actions.repository.install.installers.makefile import MakefileInstaller  # noqa: F401
-
-# OS-specific installers
-from pkgmgr.actions.repository.install.installers.os_packages.arch_pkgbuild import ArchPkgbuildInstaller  # noqa: F401
-from pkgmgr.actions.repository.install.installers.os_packages.debian_control import DebianControlInstaller  # noqa: F401
-from pkgmgr.actions.repository.install.installers.os_packages.rpm_spec import RpmSpecInstaller  # noqa: F401

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

@@ -1,93 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-
-"""
-Installer that triggers `make install` if a Makefile is present and
-the Makefile actually defines an 'install' target.
-
-This is useful for repositories that expose a standard Makefile-based
-installation step.
-"""
-
-import os
-import re
-
-from pkgmgr.actions.repository.install.context import RepoContext
-from pkgmgr.actions.repository.install.installers.base import BaseInstaller
-from pkgmgr.core.command.run import run_command
-
-
-class MakefileInstaller(BaseInstaller):
-    """Run `make install` if a Makefile with an 'install' target exists."""
-
-    # Logical layer name, used by capability matchers.
-    layer = "makefile"
-
-    MAKEFILE_NAME = "Makefile"
-
-    def supports(self, ctx: RepoContext) -> bool:
-        """Return True if a Makefile exists in the repository directory."""
-        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:
-        """
-        Check whether the Makefile defines an 'install' target.
-
-        We treat the presence of a real install target as either:
-          - a line starting with 'install:' (optionally preceded by whitespace), or
-          - a .PHONY line that lists 'install' as one of the targets.
-        """
-        try:
-            with open(makefile_path, "r", encoding="utf-8", errors="ignore") as f:
-                content = f.read()
-        except OSError:
-            # If we cannot read the Makefile for some reason, assume no target.
-            return False
-
-        # install: ...
-        if re.search(r"^\s*install\s*:", content, flags=re.MULTILINE):
-            return True
-
-        # .PHONY: ... install ...
-        if re.search(r"^\s*\.PHONY\s*:\s*.*\binstall\b", content, flags=re.MULTILINE):
-            return True
-
-        return False
-
-    def run(self, ctx: RepoContext) -> None:
-        """
-        Execute `make install` in the repository directory, but only if an
-        'install' target is actually defined in the Makefile.
-
-        Any failure in `make install` is treated as a fatal error and will
-        propagate as SystemExit from run_command().
-        """
-        makefile_path = os.path.join(ctx.repo_dir, self.MAKEFILE_NAME)
-
-        if not os.path.exists(makefile_path):
-            # Should normally not happen if supports() was checked before,
-            # but keep this guard for robustness.
-            if not ctx.quiet:
-                print(
-                    f"[pkgmgr] Makefile '{makefile_path}' not found, "
-                    "skipping make install."
-                )
-            return
-
-        if not self._has_install_target(makefile_path):
-            if not ctx.quiet:
-                print(
-                    "[pkgmgr] Skipping Makefile install: no 'install' target "
-                    f"found in {makefile_path}."
-                )
-            return
-
-        if not ctx.quiet:
-            print(
-                f"[pkgmgr] Running 'make install' in {ctx.repo_dir} "
-                "(install target detected in Makefile)."
-            )
-
-        cmd = "make install"
-        run_command(cmd, cwd=ctx.repo_dir, preview=ctx.preview)

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

@@ -1,157 +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 the flake outputs (`pkgmgr`, `default`) via `nix profile install`.
-  - Failure installing `pkgmgr` is treated as fatal.
-  - Failure installing `default` is logged as an error/warning but does not abort.
-
-Special handling for dev shells / CI:
-  - If IN_NIX_SHELL is set (e.g. inside `nix develop`), the installer is
-    disabled. In that environment the flake outputs are already provided
-    by the dev shell and we must not touch the user profile.
-  - If PKGMGR_DISABLE_NIX_FLAKE_INSTALLER=1 is set, the installer is
-    globally disabled (useful for CI or debugging).
-"""
-
-import os
-import shutil
-from typing import TYPE_CHECKING
-
-from pkgmgr.actions.repository.install.installers.base import BaseInstaller
-from pkgmgr.core.command.run import run_command
-
-if TYPE_CHECKING:
-    from pkgmgr.actions.repository.install.context import RepoContext
-    from pkgmgr.actions.repository.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 _in_nix_shell(self) -> bool:
-        """
-        Return True if we appear to be running inside a Nix dev shell.
-
-        Nix sets IN_NIX_SHELL in `nix develop` environments. In that case
-        the flake outputs are already available, and touching the user
-        profile (nix profile install/remove) is undesirable.
-        """
-        return bool(os.environ.get("IN_NIX_SHELL"))
-
-    def supports(self, ctx: "RepoContext") -> bool:
-        """
-        Only support repositories that:
-          - Are NOT inside a Nix dev shell (IN_NIX_SHELL unset),
-          - Are NOT explicitly disabled via PKGMGR_DISABLE_NIX_FLAKE_INSTALLER=1,
-          - Have a flake.nix,
-          - And have the `nix` command available.
-        """
-        # 1) Skip when running inside a dev shell – flake is already active.
-        if self._in_nix_shell():
-            print(
-                "[INFO] IN_NIX_SHELL detected; skipping NixFlakeInstaller. "
-                "Flake outputs are provided by the development shell."
-            )
-            return False
-
-        # 2) 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
-
-        # 3) Nix must be available.
-        if shutil.which("nix") is None:
-            return False
-
-        # 4) 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 run(self, ctx: "InstallContext") -> None:
-        """
-        Install Nix flake profile outputs (pkgmgr, default).
-
-        Any failure installing `pkgmgr` is treated as fatal (SystemExit).
-        A failure installing `default` is logged but does not abort.
-        """
-        # Extra guard in case run() is called directly without supports().
-        if self._in_nix_shell():
-            print(
-                "[INFO] IN_NIX_SHELL detected in run(); "
-                "skipping Nix flake profile installation."
-            )
-            return
-
-        # Reuse supports() to keep logic in one place
-        if not self.supports(ctx):  # type: ignore[arg-type]
-            return
-
-        print("Nix flake detected, attempting to install profile outputs...")
-
-        # Handle the "already installed" case up-front:
-        self._ensure_old_profile_removed(ctx)  # type: ignore[arg-type]
-
-        for output in ("pkgmgr", "default"):
-            cmd = f"nix profile install {ctx.repo_dir}#{output}"
-
-            try:
-                # For 'default' we don't want the process to exit on error
-                allow_failure = output == "default"
-                run_command(
-                    cmd,
-                    cwd=ctx.repo_dir,
-                    preview=ctx.preview,
-                    allow_failure=allow_failure,
-                )
-                print(f"Nix flake output '{output}' successfully installed.")
-            except SystemExit as e:
-                print(f"[Error] Failed to install Nix flake output '{output}': {e}")
-                if output == "pkgmgr":
-                    # Broken main CLI install → fatal
-                    raise
-                # For 'default' we log and continue
-                print(
-                    "[Warning] Continuing despite failure to install 'default' "
-                    "because 'pkgmgr' is already installed."
-                )
-                break

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

@@ -1,127 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-
-"""
-Installer for Python projects based on pyproject.toml.
-
-Strategy:
-  - Determine a pip command in this order:
-      1. $PKGMGR_PIP (explicit override, e.g. ~/.venvs/pkgmgr/bin/pip)
-      2. sys.executable -m pip (current interpreter)
-      3. "pip" from PATH as last resort
-  - If pyproject.toml exists: pip install .
-
-All installation failures are treated as fatal errors (SystemExit),
-except when we explicitly skip the installer:
-
-  - If IN_NIX_SHELL is set, we assume Python is managed by Nix and
-    skip this installer entirely.
-  - If PKGMGR_DISABLE_PYTHON_INSTALLER=1 is set, the installer is
-    globally disabled (useful for CI or debugging).
-"""
-
-from __future__ import annotations
-
-import os
-import sys
-from typing import TYPE_CHECKING
-
-from pkgmgr.actions.repository.install.installers.base import BaseInstaller
-from pkgmgr.core.command.run import run_command
-
-if TYPE_CHECKING:
-    from pkgmgr.actions.repository.install.context import RepoContext
-    from pkgmgr.actions.repository.install import InstallContext
-
-
-class PythonInstaller(BaseInstaller):
-    """Install Python projects and dependencies via pip."""
-
-    # Logical layer name, used by capability matchers.
-    layer = "python"
-
-    def _in_nix_shell(self) -> bool:
-        """
-        Return True if we appear to be running inside a Nix dev shell.
-
-        Nix sets IN_NIX_SHELL in `nix develop` environments. In that case
-        the Python environment is already provided by Nix, so we must not
-        attempt an additional pip-based installation.
-        """
-        return bool(os.environ.get("IN_NIX_SHELL"))
-
-    def supports(self, ctx: "RepoContext") -> bool:
-        """
-        Return True if this installer should handle the given repository.
-
-        Only pyproject.toml is supported as the single source of truth
-        for Python dependencies and packaging metadata.
-
-        The installer is *disabled* when:
-          - IN_NIX_SHELL is set (Python managed by Nix dev shell), or
-          - PKGMGR_DISABLE_PYTHON_INSTALLER=1 is set.
-        """
-        # 1) Skip in Nix dev shells – Python is managed by the flake/devShell.
-        if self._in_nix_shell():
-            print(
-                "[INFO] IN_NIX_SHELL detected; skipping PythonInstaller. "
-                "Python runtime is provided by the Nix dev shell."
-            )
-            return False
-
-        # 2) Optional global kill-switch.
-        if os.environ.get("PKGMGR_DISABLE_PYTHON_INSTALLER") == "1":
-            print(
-                "[INFO] PKGMGR_DISABLE_PYTHON_INSTALLER=1 – "
-                "PythonInstaller is disabled."
-            )
-            return False
-
-        repo_dir = ctx.repo_dir
-        return os.path.exists(os.path.join(repo_dir, "pyproject.toml"))
-
-    def _pip_cmd(self) -> str:
-        """
-        Resolve the pip command to use.
-
-        Order:
-          1) PKGMGR_PIP (explicit override)
-          2) sys.executable -m pip
-          3) plain "pip"
-        """
-        explicit = os.environ.get("PKGMGR_PIP", "").strip()
-        if explicit:
-            return explicit
-
-        if sys.executable:
-            return f"{sys.executable} -m pip"
-
-        return "pip"
-
-    def run(self, ctx: "InstallContext") -> None:
-        """
-        Install Python project defined via pyproject.toml.
-
-        Any pip failure is propagated as SystemExit.
-        """
-        # Extra guard in case run() is called directly without supports().
-        if self._in_nix_shell():
-            print(
-                "[INFO] IN_NIX_SHELL detected in PythonInstaller.run(); "
-                "skipping pip-based installation."
-            )
-            return
-
-        if not self.supports(ctx):  # type: ignore[arg-type]
-            return
-
-        pip_cmd = self._pip_cmd()
-
-        pyproject = os.path.join(ctx.repo_dir, "pyproject.toml")
-        if os.path.exists(pyproject):
-            print(
-                f"pyproject.toml found in {ctx.identifier}, "
-                f"installing Python project..."
-            )
-            cmd = f"{pip_cmd} install ."
-            run_command(cmd, cwd=ctx.repo_dir, preview=ctx.preview)

pkgmgr/cli/__init__.py

@@ -1,110 +0,0 @@
-# -*- coding: utf-8 -*-
-from __future__ import annotations
-
-import os
-
-from pkgmgr.core.config.load import load_config
-
-from .context import CLIContext
-from .parser import create_parser
-from .dispatch import dispatch_command
-
-__all__ = ["CLIContext", "create_parser", "dispatch_command", "main"]
-
-
-# User config lives in the home directory:
-#   ~/.config/pkgmgr/config.yaml
-USER_CONFIG_PATH = os.path.expanduser("~/.config/pkgmgr/config.yaml")
-
-DESCRIPTION_TEXT = """\
-\033[1;32mPackage Manager 🤖📦\033[0m
-\033[3mKevin's Package Manager is a multi-repository, multi-package, and multi-format 
-development tool crafted by and designed for:\033[0m
-  \033[1;34mKevin Veen-Birkenbach\033[0m
-  \033[4mhttps://www.veen.world/\033[0m
-
-\033[1mOverview:\033[0m
-A powerful toolchain that unifies and automates workflows across heterogeneous
-project ecosystems. pkgmgr is not only a package manager — it is a full 
-developer-oriented orchestration tool.
-
-It automatically detects, merges, and processes metadata from multiple 
-dependency formats, including:
-  • \033[1;33mPython:\033[0m pyproject.toml, requirements.txt  
-  • \033[1;33mNix:\033[0m flake.nix  
-  • \033[1;33mArch Linux:\033[0m PKGBUILD  
-  • \033[1;33mAnsible:\033[0m requirements.yml  
-  • \033[1;33mpkgmgr-native:\033[0m pkgmgr.yml  
-
-This allows pkgmgr to perform installation, updates, verification, dependency
-resolution, and synchronization across complex multi-repo environments — with a
-single unified command-line interface.
-
-\033[1mDeveloper Tools:\033[0m
-pkgmgr includes an integrated toolbox to enhance daily development workflows:
-
-  • \033[1;33mVS Code integration:\033[0m Auto-generate and open multi-repo workspaces  
-  • \033[1;33mTerminal integration:\033[0m Open repositories in new GNOME Terminal tabs  
-  • \033[1;33mExplorer integration:\033[0m Open repositories in your file manager  
-  • \033[1;33mRelease automation:\033[0m Version bumping, changelog updates, and tagging  
-  • \033[1;33mBatch operations:\033[0m Execute shell commands across multiple repositories  
-  • \033[1;33mGit/Docker/Make wrappers:\033[0m Unified command proxying for many tools 
-
-\033[1mCapabilities:\033[0m
-  • Clone, pull, verify, update, and manage many repositories at once  
-  • Resolve dependencies across languages and ecosystems  
-  • Standardize install/update workflows  
-  • Create symbolic executable wrappers for any project  
-  • Merge configuration from default + user config layers  
-
-Use pkgmgr as both a robust package management framework and a versatile 
-development orchestration tool.
-
-For detailed help on each command, use:
-    \033[1mpkgmgr <command> --help\033[0m
-"""
-
-
-def main() -> None:
-    """
-    Entry point for the pkgmgr CLI.
-    """
-
-    config_merged = load_config(USER_CONFIG_PATH)
-
-    # Directories: be robust and provide sane defaults if missing
-    directories = config_merged.get("directories") or {}
-    repositories_dir = os.path.expanduser(
-        directories.get("repositories", "~/Repositories")
-    )
-    binaries_dir = os.path.expanduser(
-        directories.get("binaries", "~/.local/bin")
-    )
-
-    # Ensure the merged config actually contains the resolved directories
-    config_merged.setdefault("directories", {})
-    config_merged["directories"]["repositories"] = repositories_dir
-    config_merged["directories"]["binaries"] = binaries_dir
-
-    all_repositories = config_merged.get("repositories", [])
-
-    ctx = CLIContext(
-        config_merged=config_merged,
-        repositories_base_dir=repositories_dir,
-        all_repositories=all_repositories,
-        binaries_dir=binaries_dir,
-        user_config_path=USER_CONFIG_PATH,
-    )
-
-    parser = create_parser(DESCRIPTION_TEXT)
-    args = parser.parse_args()
-
-    if not getattr(args, "command", None):
-        parser.print_help()
-        return
-
-    dispatch_command(args, ctx)
-
-
-if __name__ == "__main__":
-    main()

pkgmgr/cli/commands/tools.py

@@ -1,83 +0,0 @@
-from __future__ import annotations
-
-import json
-import os
-
-from typing import Any, Dict, List
-
-from pkgmgr.cli.context import CLIContext
-from pkgmgr.core.command.run import run_command
-from pkgmgr.core.repository.identifier import get_repo_identifier
-
-
-Repository = Dict[str, Any]
-
-
-def handle_tools_command(
-    args,
-    ctx: CLIContext,
-    selected: List[Repository],
-) -> None:
-    """
-    Handle integration commands:
-    - explore (file manager)
-    - terminal (GNOME Terminal)
-    - code (VS Code workspace)
-    """
-
-    # --------------------------------------------------------
-    # explore
-    # --------------------------------------------------------
-    if args.command == "explore":
-        for repository in selected:
-            run_command(
-                f"nautilus {repository['directory']} & disown"
-            )
-        return
-
-    # --------------------------------------------------------
-    # terminal
-    # --------------------------------------------------------
-    if args.command == "terminal":
-        for repository in selected:
-            run_command(
-                f'gnome-terminal --tab --working-directory="{repository["directory"]}"'
-            )
-        return
-
-    # --------------------------------------------------------
-    # code
-    # --------------------------------------------------------
-    if args.command == "code":
-        if not selected:
-            print("No repositories selected.")
-            return
-
-        identifiers = [
-            get_repo_identifier(repo, ctx.all_repositories)
-            for repo in selected
-        ]
-        sorted_identifiers = sorted(identifiers)
-        workspace_name = "_".join(sorted_identifiers) + ".code-workspace"
-
-        workspaces_dir = os.path.expanduser(
-            ctx.config_merged.get("directories").get("workspaces")
-        )
-        os.makedirs(workspaces_dir, exist_ok=True)
-        workspace_file = os.path.join(workspaces_dir, workspace_name)
-
-        folders = [{"path": repository["directory"]} for repository in selected]
-
-        workspace_data = {
-            "folders": folders,
-            "settings": {},
-        }
-        if not os.path.exists(workspace_file):
-            with open(workspace_file, "w") as f:
-                json.dump(workspace_data, f, indent=4)
-            print(f"Created workspace file: {workspace_file}")
-        else:
-            print(f"Using existing workspace file: {workspace_file}")
-
-        run_command(f'code "{workspace_file}"')
-        return

pkgmgr/cli/parser.py

@@ -1,505 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-
-from __future__ import annotations
-
-import argparse
-
-from pkgmgr.cli.proxy import register_proxy_commands
-
-
-class SortedSubParsersAction(argparse._SubParsersAction):
-    """
-    Subparsers action that keeps choices sorted alphabetically.
-    """
-
-    def add_parser(self, name, **kwargs):
-        parser = super().add_parser(name, **kwargs)
-        # Sort choices alphabetically by dest (subcommand name)
-        self._choices_actions.sort(key=lambda a: a.dest)
-        return parser
-
-
-def add_identifier_arguments(subparser: argparse.ArgumentParser) -> None:
-    """
-    Common identifier / selection arguments for many subcommands.
-
-    Selection modes (mutual intent, not hard-enforced):
-      - identifiers (positional): select by alias / provider/account/repo
-      - --all: select all repositories
-      - --category / --string / --tag: filter-based selection on top
-        of the full repository set
-    """
-    subparser.add_argument(
-        "identifiers",
-        nargs="*",
-        help=(
-            "Identifier(s) for repositories. "
-            "Default: Repository of current folder."
-        ),
-    )
-    subparser.add_argument(
-        "--all",
-        action="store_true",
-        default=False,
-        help=(
-            "Apply the subcommand to all repositories in the config. "
-            "Some subcommands ask for confirmation. If you want to give this "
-            "confirmation for all repositories, pipe 'yes'. E.g: "
-            "yes | pkgmgr {subcommand} --all"
-        ),
-    )
-    subparser.add_argument(
-        "--category",
-        nargs="+",
-        default=[],
-        help=(
-            "Filter repositories by category patterns derived from config "
-            "filenames or repo metadata (use filename without .yml/.yaml, "
-            "or /regex/ to use a regular expression)."
-        ),
-    )
-    subparser.add_argument(
-        "--string",
-        default="",
-        help=(
-            "Filter repositories whose identifier / name / path contains this "
-            "substring (case-insensitive). Use /regex/ for regular expressions."
-        ),
-    )
-    subparser.add_argument(
-        "--tag",
-        action="append",
-        default=[],
-        help=(
-            "Filter repositories by tag. Matches tags from the repository "
-            "collector and category tags. Use /regex/ for regular expressions."
-        ),
-    )
-    subparser.add_argument(
-        "--preview",
-        action="store_true",
-        help="Preview changes without executing commands",
-    )
-    subparser.add_argument(
-        "--list",
-        action="store_true",
-        help="List affected repositories (with preview or status)",
-    )
-    subparser.add_argument(
-        "-a",
-        "--args",
-        nargs=argparse.REMAINDER,
-        dest="extra_args",
-        help="Additional parameters to be attached.",
-        default=[],
-    )
-
-
-def add_install_update_arguments(subparser: argparse.ArgumentParser) -> None:
-    """
-    Common arguments for install/update commands.
-    """
-    add_identifier_arguments(subparser)
-    subparser.add_argument(
-        "-q",
-        "--quiet",
-        action="store_true",
-        help="Suppress warnings and info messages",
-    )
-    subparser.add_argument(
-        "--no-verification",
-        action="store_true",
-        default=False,
-        help="Disable verification via commit/gpg",
-    )
-    subparser.add_argument(
-        "--dependencies",
-        action="store_true",
-        help="Also pull and update dependencies",
-    )
-    subparser.add_argument(
-        "--clone-mode",
-        choices=["ssh", "https", "shallow"],
-        default="ssh",
-        help=(
-            "Specify the clone mode: ssh, https, or shallow "
-            "(HTTPS shallow clone; default: ssh)"
-        ),
-    )
-
-
-def create_parser(description_text: str) -> argparse.ArgumentParser:
-    """
-    Create the top-level argument parser for pkgmgr.
-    """
-    parser = argparse.ArgumentParser(
-        description=description_text,
-        formatter_class=argparse.RawTextHelpFormatter,
-    )
-    subparsers = parser.add_subparsers(
-        dest="command",
-        help="Subcommands",
-        action=SortedSubParsersAction,
-    )
-
-    # ------------------------------------------------------------
-    # install / update / deinstall / delete
-    # ------------------------------------------------------------
-    install_parser = subparsers.add_parser(
-        "install",
-        help="Setup repository/repositories alias links to executables",
-    )
-    add_install_update_arguments(install_parser)
-
-    update_parser = subparsers.add_parser(
-        "update",
-        help="Update (pull + install) repository/repositories",
-    )
-    add_install_update_arguments(update_parser)
-    update_parser.add_argument(
-        "--system",
-        action="store_true",
-        help="Include system update commands",
-    )
-
-    deinstall_parser = subparsers.add_parser(
-        "deinstall",
-        help="Remove alias links to repository/repositories",
-    )
-    add_identifier_arguments(deinstall_parser)
-
-    delete_parser = subparsers.add_parser(
-        "delete",
-        help="Delete repository/repositories alias links to executables",
-    )
-    add_identifier_arguments(delete_parser)
-
-    # ------------------------------------------------------------
-    # create
-    # ------------------------------------------------------------
-    create_cmd_parser = subparsers.add_parser(
-        "create",
-        help=(
-            "Create new repository entries: add them to the config if not "
-            "already present, initialize the local repository, and push "
-            "remotely if --remote is set."
-        ),
-    )
-    add_identifier_arguments(create_cmd_parser)
-    create_cmd_parser.add_argument(
-        "--remote",
-        action="store_true",
-        help="If set, add the remote and push the initial commit.",
-    )
-
-    # ------------------------------------------------------------
-    # status
-    # ------------------------------------------------------------
-    status_parser = subparsers.add_parser(
-        "status",
-        help="Show status for repository/repositories or system",
-    )
-    add_identifier_arguments(status_parser)
-    status_parser.add_argument(
-        "--system",
-        action="store_true",
-        help="Show system status",
-    )
-
-    # ------------------------------------------------------------
-    # config
-    # ------------------------------------------------------------
-    config_parser = subparsers.add_parser(
-        "config",
-        help="Manage configuration",
-    )
-    config_subparsers = config_parser.add_subparsers(
-        dest="subcommand",
-        help="Config subcommands",
-        required=True,
-    )
-
-    config_show = config_subparsers.add_parser(
-        "show",
-        help="Show configuration",
-    )
-    add_identifier_arguments(config_show)
-
-    config_subparsers.add_parser(
-        "add",
-        help="Interactively add a new repository entry",
-    )
-
-    config_subparsers.add_parser(
-        "edit",
-        help="Edit configuration file with nano",
-    )
-
-    config_subparsers.add_parser(
-        "init",
-        help="Initialize user configuration by scanning the base directory",
-    )
-
-    config_delete = config_subparsers.add_parser(
-        "delete",
-        help="Delete repository entry from user config",
-    )
-    add_identifier_arguments(config_delete)
-
-    config_ignore = config_subparsers.add_parser(
-        "ignore",
-        help="Set ignore flag for repository entries in user config",
-    )
-    add_identifier_arguments(config_ignore)
-    config_ignore.add_argument(
-        "--set",
-        choices=["true", "false"],
-        required=True,
-        help="Set ignore to true or false",
-    )
-
-    config_subparsers.add_parser(
-        "update",
-        help=(
-            "Update default config files in ~/.config/pkgmgr/ from the "
-            "installed pkgmgr package (does not touch config.yaml)."
-        ),
-    )
-
-    # ------------------------------------------------------------
-    # path / explore / terminal / code / shell
-    # ------------------------------------------------------------
-    path_parser = subparsers.add_parser(
-        "path",
-        help="Print the path(s) of repository/repositories",
-    )
-    add_identifier_arguments(path_parser)
-
-    explore_parser = subparsers.add_parser(
-        "explore",
-        help="Open repository in Nautilus file manager",
-    )
-    add_identifier_arguments(explore_parser)
-
-    terminal_parser = subparsers.add_parser(
-        "terminal",
-        help="Open repository in a new GNOME Terminal tab",
-    )
-    add_identifier_arguments(terminal_parser)
-
-    code_parser = subparsers.add_parser(
-        "code",
-        help="Open repository workspace with VS Code",
-    )
-    add_identifier_arguments(code_parser)
-
-    shell_parser = subparsers.add_parser(
-        "shell",
-        help="Execute a shell command in each repository",
-    )
-    add_identifier_arguments(shell_parser)
-    shell_parser.add_argument(
-        "-c",
-        "--command",
-        nargs=argparse.REMAINDER,
-        dest="shell_command",
-        help=(
-            "The shell command (and its arguments) to execute in each "
-            "repository"
-        ),
-        default=[],
-    )
-
-    # ------------------------------------------------------------
-    # branch
-    # ------------------------------------------------------------
-    branch_parser = subparsers.add_parser(
-        "branch",
-        help="Branch-related utilities (e.g. open/close feature branches)",
-    )
-    branch_subparsers = branch_parser.add_subparsers(
-        dest="subcommand",
-        help="Branch subcommands",
-        required=True,
-    )
-
-    branch_open = branch_subparsers.add_parser(
-        "open",
-        help="Create and push a new branch on top of a base branch",
-    )
-    branch_open.add_argument(
-        "name",
-        nargs="?",
-        help=(
-            "Name of the new branch (optional; will be asked interactively "
-            "if omitted)"
-        ),
-    )
-    branch_open.add_argument(
-        "--base",
-        default="main",
-        help="Base branch to create the new branch from (default: main)",
-    )
-
-    branch_close = branch_subparsers.add_parser(
-        "close",
-        help="Merge a feature branch into base and delete it",
-    )
-    branch_close.add_argument(
-        "name",
-        nargs="?",
-        help=(
-            "Name of the branch to close (optional; current branch is used "
-            "if omitted)"
-        ),
-    )
-    branch_close.add_argument(
-        "--base",
-        default="main",
-        help=(
-            "Base branch to merge into (default: main; falls back to master "
-            "internally if main does not exist)"
-        ),
-    )
-
-    # ------------------------------------------------------------
-    # release
-    # ------------------------------------------------------------
-    release_parser = subparsers.add_parser(
-        "release",
-        help=(
-            "Create a release for repository/ies by incrementing version "
-            "and updating the changelog."
-        ),
-    )
-    release_parser.add_argument(
-        "release_type",
-        choices=["major", "minor", "patch"],
-        help="Type of version increment for the release (major, minor, patch).",
-    )
-    release_parser.add_argument(
-        "-m",
-        "--message",
-        default=None,
-        help=(
-            "Optional release message to add to the changelog and tag."
-        ),
-    )
-    # Generic selection / preview / list / extra_args
-    add_identifier_arguments(release_parser)
-    # Close current branch after successful release
-    release_parser.add_argument(
-        "--close",
-        action="store_true",
-        help=(
-            "Close the current branch after a successful release in each "
-            "repository, if it is not main/master."
-        ),
-    )
-    # Force: skip preview+confirmation and run release directly
-    release_parser.add_argument(
-        "-f",
-        "--force",
-        action="store_true",
-        help=(
-            "Skip the interactive preview+confirmation step and run the "
-            "release directly."
-        ),
-    )
-
-    # ------------------------------------------------------------
-    # version
-    # ------------------------------------------------------------
-    version_parser = subparsers.add_parser(
-        "version",
-        help=(
-            "Show version information for repository/ies "
-            "(git tags, pyproject.toml, flake.nix, PKGBUILD, debian, spec, "
-            "Ansible Galaxy)."
-        ),
-    )
-    add_identifier_arguments(version_parser)
-
-    # ------------------------------------------------------------
-    # changelog
-    # ------------------------------------------------------------
-    changelog_parser = subparsers.add_parser(
-        "changelog",
-        help=(
-            "Show changelog derived from Git history. "
-            "By default, shows the changes between the last two SemVer tags."
-        ),
-    )
-    changelog_parser.add_argument(
-        "range",
-        nargs="?",
-        default="",
-        help=(
-            "Optional tag or range (e.g. v1.2.3 or v1.2.0..v1.2.3). "
-            "If omitted, the changelog between the last two SemVer "
-            "tags is shown."
-        ),
-    )
-    add_identifier_arguments(changelog_parser)
-
-    # ------------------------------------------------------------
-    # list
-    # ------------------------------------------------------------
-    list_parser = subparsers.add_parser(
-        "list",
-        help="List all repositories with details and status",
-    )
-    # dieselbe Selektionslogik wie bei install/update/etc.:
-    add_identifier_arguments(list_parser)
-    list_parser.add_argument(
-        "--status",
-        type=str,
-        default="",
-        help=(
-            "Filter repositories by status (case insensitive). "
-            "Use /regex/ for regular expressions."
-        ),
-    )
-    list_parser.add_argument(
-        "--description",
-        action="store_true",
-        help=(
-            "Show an additional detailed section per repository "
-            "(description, homepage, tags, categories, paths)."
-        ),
-    )
-
-
-    # ------------------------------------------------------------
-    # make
-    # ------------------------------------------------------------
-    make_parser = subparsers.add_parser(
-        "make",
-        help="Executes make commands",
-    )
-    add_identifier_arguments(make_parser)
-    make_subparsers = make_parser.add_subparsers(
-        dest="subcommand",
-        help="Make subcommands",
-        required=True,
-    )
-
-    make_install = make_subparsers.add_parser(
-        "install",
-        help="Executes the make install command",
-    )
-    add_identifier_arguments(make_install)
-
-    make_deinstall = make_subparsers.add_parser(
-        "deinstall",
-        help="Executes the make deinstall command",
-    )
-    add_identifier_arguments(make_deinstall)
-
-    # ------------------------------------------------------------
-    # Proxy commands (git, docker, docker compose, ...)
-    # ------------------------------------------------------------
-    register_proxy_commands(subparsers)
-
-    return parser

pkgmgr/core/command/resolve.py

@@ -1,113 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-
-"""
-Command resolver for repositories.
-
-This module determines the correct command to expose via symlink.
-It implements the following priority:
-
-1. Explicit command in repo config                 → command
-2. System package manager binary (/usr/...)        → NO LINK (respect OS)
-3. Nix profile binary (~/.nix-profile/bin/<id>)    → command
-4. Python / non-system console script on PATH      → command
-5. Fallback: repository's main.sh or main.py       → command
-6. If nothing is available                         → raise error
-
-The actual symlink creation is handled by create_ink(). This resolver
-only decides *what* should be used as the entrypoint, or whether no
-link should be created at all.
-"""
-
-import os
-import shutil
-from typing import Optional
-
-
-def resolve_command_for_repo(repo, repo_identifier: str, repo_dir: str) -> Optional[str]:
-    """
-    Determine the command for this repository.
-
-    Returns:
-        str  → path to the command (a symlink should be created)
-        None → do NOT create a link (e.g. system package already provides it)
-
-    On total failure (no suitable command found at any layer), this function
-    raises SystemExit with a descriptive error message.
-    """
-    # ------------------------------------------------------------
-    # 1. Explicit command defined by repository config
-    # ------------------------------------------------------------
-    explicit = repo.get("command")
-    if explicit:
-        return explicit
-
-    home = os.path.expanduser("~")
-
-    def is_executable(path: str) -> bool:
-        return os.path.exists(path) and os.access(path, os.X_OK)
-
-    # ------------------------------------------------------------
-    # 2. System package manager binary via PATH
-    #
-    #    If the binary lives under /usr/, we treat it as a system-managed
-    #    package (e.g. installed via pacman/apt/yum). In that case, pkgmgr
-    #    does NOT create a link at all and defers entirely to the OS.
-    # ------------------------------------------------------------
-    path_candidate = shutil.which(repo_identifier)
-    system_binary: Optional[str] = None
-    non_system_binary: Optional[str] = None
-
-    if path_candidate:
-        if path_candidate.startswith("/usr/"):
-            system_binary = path_candidate
-        else:
-            non_system_binary = path_candidate
-
-    if system_binary:
-        # Respect system package manager: do not create a link.
-        if repo.get("debug", False):
-            print(
-                f"[pkgmgr] System binary for '{repo_identifier}' found at "
-                f"{system_binary}; no symlink will be created."
-            )
-        return None
-
-    # ------------------------------------------------------------
-    # 3. Nix profile binary (~/.nix-profile/bin/<identifier>)
-    # ------------------------------------------------------------
-    nix_candidate = os.path.join(home, ".nix-profile", "bin", repo_identifier)
-    if is_executable(nix_candidate):
-        return nix_candidate
-
-    # ------------------------------------------------------------
-    # 4. Python / non-system console script on PATH
-    #
-    #    Here we reuse the non-system PATH candidate (e.g. from a venv or
-    #    a user-local install like ~/.local/bin). This is treated as a
-    #    valid command target.
-    # ------------------------------------------------------------
-    if non_system_binary and is_executable(non_system_binary):
-        return non_system_binary
-
-    # ------------------------------------------------------------
-    # 5. Fallback: main.sh / main.py inside the repository
-    # ------------------------------------------------------------
-    main_sh = os.path.join(repo_dir, "main.sh")
-    main_py = os.path.join(repo_dir, "main.py")
-
-    if is_executable(main_sh):
-        return main_sh
-
-    if is_executable(main_py) or os.path.exists(main_py):
-        return main_py
-
-    # ------------------------------------------------------------
-    # 6. Nothing found → treat as a hard error
-    # ------------------------------------------------------------
-    raise SystemExit(
-        f"No executable command could be resolved for repository '{repo_identifier}'. "
-        "No explicit 'command' configured, no system-managed binary under /usr/, "
-        "no Nix profile binary, no non-system console script on PATH, and no "
-        "main.sh/main.py found in the repository."
-    )

pkgmgr/core/command/run.py

@@ -1,45 +0,0 @@
-# pkgmgr/run_command.py
-import subprocess
-import sys
-from typing import List, Optional, Union
-
-
-CommandType = Union[str, List[str]]
-
-
-def run_command(
-    cmd: CommandType,
-    cwd: Optional[str] = None,
-    preview: bool = False,
-    allow_failure: bool = False,
-) -> subprocess.CompletedProcess:
-    """
-    Run a command and optionally exit on error.
-
-    - If `cmd` is a string, it is executed with `shell=True`.
-    - If `cmd` is a list of strings, it is executed without a shell.
-    """
-    if isinstance(cmd, str):
-        display = cmd
-    else:
-        display = " ".join(cmd)
-
-    where = cwd or "."
-
-    if preview:
-        print(f"[Preview] In '{where}': {display}")
-        # Fake a successful result; most callers ignore the return value anyway
-        return subprocess.CompletedProcess(cmd, 0)  # type: ignore[arg-type]
-
-    print(f"Running in '{where}': {display}")
-
-    if isinstance(cmd, str):
-        result = subprocess.run(cmd, cwd=cwd, shell=True)
-    else:
-        result = subprocess.run(cmd, cwd=cwd)
-
-    if result.returncode != 0 and not allow_failure:
-        print(f"Command failed with exit code {result.returncode}. Exiting.")
-        sys.exit(result.returncode)
-
-    return result

pkgmgr/core/repository/dir.py

@@ -1,15 +0,0 @@
-import sys
-import os
-
-def get_repo_dir(repositories_base_dir:str,repo:{})->str:
-    try:
-        return os.path.join(repositories_base_dir, repo.get("provider"), repo.get("account"), repo.get("repository"))
-    except TypeError as e:
-        if repositories_base_dir:
-            print(f"Error: {e} \nThe repository {repo} seems not correct configured.\nPlease configure it correct.")
-            for key in ["provider","account","repository"]:
-                if not repo.get(key,False):
-                   print(f"Key '{key}' is missing.")
-        else:
-            print(f"Error: {e} \nThe base {base} seems not correct configured.\nPlease configure it correct.")
-        sys.exit(3)

pyproject.toml

@@ -7,10 +7,10 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "package-manager"
-version = "0.7.10"
+version = "1.5.0"
 description = "Kevin's package-manager tool (pkgmgr)"
 readme = "README.md"
-requires-python = ">=3.11"
+requires-python = ">=3.9"
 license = { text = "MIT" }
 
 authors = [
@@ -39,13 +39,13 @@ pkgmgr = "pkgmgr.cli:main"
 # -----------------------------
 # setuptools configuration
 # -----------------------------
-# We use find_packages(), not a fixed list,
-# and explicitly include pkgmgr* and config*
+# Source layout: all packages live under "src/"
+[tool.setuptools]
+package-dir = { "" = "src", "config" = "config" }
 
 [tool.setuptools.packages.find]
-where = ["."]
+where = ["src", "."]
 include = ["pkgmgr*", "config*"]
 
-# Ensure defaults.yaml is shipped inside wheels & nix builds
 [tool.setuptools.package-data]
 "config" = ["defaults.yaml"]

scripts/build/base.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+: "${BASE_IMAGE_ARCH:=archlinux:latest}"
+: "${BASE_IMAGE_DEBIAN:=debian:stable-slim}"
+: "${BASE_IMAGE_UBUNTU:=ubuntu:latest}"
+: "${BASE_IMAGE_FEDORA:=fedora:latest}"
+: "${BASE_IMAGE_CENTOS:=quay.io/centos/centos:stream9}"
+
+resolve_base_image() {
+  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 '$PKGMGR_DISTRO'" >&2; exit 1 ;;
+  esac
+}

scripts/build/build-image-missing.sh

@@ -1,35 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-source "${SCRIPT_DIR}/resolve-base-image.sh"
-
-echo "============================================================"
-echo ">>> Building ONLY missing container images"
-echo "============================================================"
-
-for distro in $DISTROS; do
-    IMAGE="package-manager-test-$distro"
-    BASE_IMAGE="$(resolve_base_image "$distro")"
-
-    if docker image inspect "$IMAGE" >/dev/null 2>&1; then
-        echo "[build-missing] Image already exists: $IMAGE (skipping)"
-        continue
-    fi
-
-    echo
-    echo "------------------------------------------------------------"
-    echo "[build-missing] Building missing image: $IMAGE"
-    echo "BASE_IMAGE = $BASE_IMAGE"
-    echo "------------------------------------------------------------"
-
-    docker build \
-        --build-arg BASE_IMAGE="$BASE_IMAGE" \
-        -t "$IMAGE" \
-        .
-done
-
-echo
-echo "============================================================"
-echo ">>> build-missing: Done"
-echo "============================================================"

scripts/build/build-image-no-cache.sh

@@ -1,17 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-source "${SCRIPT_DIR}/resolve-base-image.sh"
-
-for distro in $DISTROS; do
-  base_image="$(resolve_base_image "$distro")"
-
-  echo ">>> Building test image for distro '$distro' with NO CACHE (BASE_IMAGE=$base_image)..."
-
-  docker build \
-    --no-cache \
-    --build-arg BASE_IMAGE="$base_image" \
-    -t "package-manager-test-$distro" \
-    .
-done

scripts/build/build-image.sh

@@ -1,16 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-source "${SCRIPT_DIR}/resolve-base-image.sh"
-
-for distro in $DISTROS; do
-  base_image="$(resolve_base_image "$distro")"
-
-  echo ">>> Building test image for distro '$distro' (BASE_IMAGE=$base_image)..."
-
-  docker build \
-    --build-arg BASE_IMAGE="$base_image" \
-    -t "package-manager-test-$distro" \
-    .
-done

scripts/build/image.sh

@@ -0,0 +1,227 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# shellcheck source=./scripts/build/base.sh
+source "${SCRIPT_DIR}/base.sh"
+
+: "${PKGMGR_DISTRO:?Environment variable 'PKGMGR_DISTRO' must be set (arch|debian|ubuntu|fedora|centos)}"
+
+NO_CACHE=0
+MISSING_ONLY=0
+TARGET=""
+IMAGE_TAG=""         # local image name or base tag (without registry)
+PUSH=0               # if 1 -> use buildx and push (requires docker buildx)
+PUBLISH=0            # if 1 -> push with semantic tags (latest/version/stable + arch aliases)
+REGISTRY=""          # e.g. ghcr.io
+OWNER=""             # e.g. github org/user
+REPO_PREFIX="pkgmgr" # image base name (pkgmgr)
+VERSION=""           # X.Y.Z (required for --publish)
+IS_STABLE="false"    # "true" -> publish stable tags
+DEFAULT_DISTRO="arch"
+
+usage() {
+  local default_tag="pkgmgr-${PKGMGR_DISTRO}"
+  if [[ -n "${TARGET:-}" ]]; then
+    default_tag="${default_tag}-${TARGET}"
+  fi
+
+  cat <<EOF
+Usage: PKGMGR_DISTRO=<distro> $0 [options]
+
+Build options:
+  --missing             Build only if the image does not already exist (local build only)
+  --no-cache            Build with --no-cache
+  --target <name>       Build a specific Dockerfile target (e.g. virgin)
+  --tag <image>         Override the output image tag (default: ${default_tag})
+
+Publish options:
+  --push                Push the built image (uses docker buildx build --push)
+  --publish             Publish semantic tags (latest, <version>, optional stable) + arch aliases
+  --registry <reg>      Registry (e.g. ghcr.io)
+  --owner <owner>       Registry namespace (e.g. \${GITHUB_REPOSITORY_OWNER})
+  --repo-prefix <name>  Image base name (default: pkgmgr)
+  --version <X.Y.Z>     Version for --publish
+  --stable <true|false> Whether to publish :stable tags (default: false)
+
+Notes:
+- --publish implies --push and requires --registry, --owner, and --version.
+- Local build (no --push) uses "docker build" and creates local images like "pkgmgr-arch" / "pkgmgr-arch-virgin".
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --no-cache) NO_CACHE=1; shift ;;
+    --missing)  MISSING_ONLY=1; shift ;;
+    --target)
+      TARGET="${2:-}"
+      [[ -n "${TARGET}" ]] || { echo "ERROR: --target requires a value (e.g. virgin)"; exit 2; }
+      shift 2
+      ;;
+    --tag)
+      IMAGE_TAG="${2:-}"
+      [[ -n "${IMAGE_TAG}" ]] || { echo "ERROR: --tag requires a value"; exit 2; }
+      shift 2
+      ;;
+    --push) PUSH=1; shift ;;
+    --publish) PUBLISH=1; PUSH=1; shift ;;
+    --registry)
+      REGISTRY="${2:-}"
+      [[ -n "${REGISTRY}" ]] || { echo "ERROR: --registry requires a value"; exit 2; }
+      shift 2
+      ;;
+    --owner)
+      OWNER="${2:-}"
+      [[ -n "${OWNER}" ]] || { echo "ERROR: --owner requires a value"; exit 2; }
+      shift 2
+      ;;
+    --repo-prefix)
+      REPO_PREFIX="${2:-}"
+      [[ -n "${REPO_PREFIX}" ]] || { echo "ERROR: --repo-prefix requires a value"; exit 2; }
+      shift 2
+      ;;
+    --version)
+      VERSION="${2:-}"
+      [[ -n "${VERSION}" ]] || { echo "ERROR: --version requires a value"; exit 2; }
+      shift 2
+      ;;
+    --stable)
+      IS_STABLE="${2:-}"
+      [[ -n "${IS_STABLE}" ]] || { echo "ERROR: --stable requires a value (true|false)"; exit 2; }
+      shift 2
+      ;;
+    -h|--help) usage; exit 0 ;;
+    *)
+      echo "ERROR: Unknown argument: $1" >&2
+      usage
+      exit 2
+      ;;
+  esac
+done
+
+# Derive default local tag if not provided
+if [[ -z "${IMAGE_TAG}" ]]; then
+  IMAGE_TAG="${REPO_PREFIX}-${PKGMGR_DISTRO}"
+  if [[ -n "${TARGET}" ]]; then
+    IMAGE_TAG="${IMAGE_TAG}-${TARGET}"
+  fi
+fi
+
+BASE_IMAGE="$(resolve_base_image "$PKGMGR_DISTRO")"
+
+# Local-only "missing" shortcut
+if [[ "${MISSING_ONLY}" == "1" ]]; then
+  if [[ "${PUSH}" == "1" ]]; then
+    echo "ERROR: --missing is only supported for local builds (without --push/--publish)" >&2
+    exit 2
+  fi
+  if docker image inspect "${IMAGE_TAG}" >/dev/null 2>&1; then
+    echo "[build] Image already exists: ${IMAGE_TAG} (skipping due to --missing)"
+    exit 0
+  fi
+fi
+
+# Validate publish parameters
+if [[ "${PUBLISH}" == "1" ]]; then
+  [[ -n "${REGISTRY}" ]] || { echo "ERROR: --publish requires --registry"; exit 2; }
+  [[ -n "${OWNER}" ]]    || { echo "ERROR: --publish requires --owner"; exit 2; }
+  [[ -n "${VERSION}" ]]  || { echo "ERROR: --publish requires --version"; exit 2; }
+fi
+
+# Guard: --push without --publish requires fully-qualified --tag
+if [[ "${PUSH}" == "1" && "${PUBLISH}" != "1" ]]; then
+  if [[ "${IMAGE_TAG}" != */* ]]; then
+    echo "ERROR: --push requires --tag with a fully-qualified name (e.g. ghcr.io/<owner>/<image>:tag), or use --publish" >&2
+    exit 2
+  fi
+fi
+
+echo
+echo "------------------------------------------------------------"
+echo "[build] Building image"
+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
+if [[ "${PUSH}" == "1" ]]; then echo "push      = enabled"; fi
+if [[ "${PUBLISH}" == "1" ]]; then
+  echo "publish   = enabled"
+  echo "registry  = ${REGISTRY}"
+  echo "owner     = ${OWNER}"
+  echo "version   = ${VERSION}"
+  echo "stable    = ${IS_STABLE}"
+fi
+echo "------------------------------------------------------------"
+
+# Common build args
+build_args=(--build-arg "BASE_IMAGE=${BASE_IMAGE}")
+
+if [[ "${NO_CACHE}" == "1" ]]; then
+  build_args+=(--no-cache)
+fi
+
+if [[ -n "${TARGET}" ]]; then
+  build_args+=(--target "${TARGET}")
+fi
+
+compute_publish_tags() {
+  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 [[ "${PKGMGR_DISTRO}" == "${DEFAULT_DISTRO}" ]]; then
+    alias_tag_base="${REGISTRY}/${OWNER}/${REPO_PREFIX}"
+    if [[ -n "${TARGET}" ]]; then
+      alias_tag_base="${alias_tag_base}-${TARGET}"
+    fi
+  fi
+
+  local tags=()
+  tags+=("${distro_tag_base}:latest")
+  tags+=("${distro_tag_base}:${VERSION}")
+
+  if [[ "${IS_STABLE}" == "true" ]]; then
+    tags+=("${distro_tag_base}:stable")
+  fi
+
+  if [[ -n "${alias_tag_base}" ]]; then
+    tags+=("${alias_tag_base}:latest")
+    tags+=("${alias_tag_base}:${VERSION}")
+    if [[ "${IS_STABLE}" == "true" ]]; then
+      tags+=("${alias_tag_base}:stable")
+    fi
+  fi
+
+  printf '%s\n' "${tags[@]}"
+}
+
+if [[ "${PUSH}" == "1" ]]; then
+  bx_args=(docker buildx build --push)
+
+  if [[ "${PUBLISH}" == "1" ]]; then
+    while IFS= read -r t; do
+      bx_args+=(-t "$t")
+    done < <(compute_publish_tags)
+  else
+    bx_args+=(-t "${IMAGE_TAG}")
+  fi
+
+  bx_args+=("${build_args[@]}")
+  bx_args+=(.)
+
+  echo "[build] Running: ${bx_args[*]}"
+  "${bx_args[@]}"
+else
+  local_args=(docker build)
+  local_args+=("${build_args[@]}")
+  local_args+=(-t "${IMAGE_TAG}")
+  local_args+=(.)
+
+  echo "[build] Running: ${local_args[*]}"
+  "${local_args[@]}"
+fi

scripts/build/publish.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Publish all distro images (full + virgin) to a registry via image.sh --publish
+#
+# Required env:
+#   OWNER      (e.g. GITHUB_REPOSITORY_OWNER)
+#   VERSION    (e.g. 1.2.3)
+#
+# Optional env:
+#   REGISTRY   (default: ghcr.io)
+#   IS_STABLE  (default: false)
+#   DISTROS    (default: "arch debian ubuntu fedora centos")
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+REGISTRY="${REGISTRY:-ghcr.io}"
+IS_STABLE="${IS_STABLE:-false}"
+DISTROS="${DISTROS:-arch debian ubuntu fedora centos}"
+
+: "${OWNER:?Environment variable OWNER must be set (e.g. github.repository_owner)}"
+: "${VERSION:?Environment variable VERSION must be set (e.g. 1.2.3)}"
+
+echo "[publish] REGISTRY=${REGISTRY}"
+echo "[publish] OWNER=${OWNER}"
+echo "[publish] VERSION=${VERSION}"
+echo "[publish] IS_STABLE=${IS_STABLE}"
+echo "[publish] DISTROS=${DISTROS}"
+
+for d in ${DISTROS}; do
+  echo
+  echo "============================================================"
+  echo "[publish] PKGMGR_DISTRO=${d}"
+  echo "============================================================"
+
+  # virgin
+  PKGMGR_DISTRO="${d}" bash "${SCRIPT_DIR}/image.sh" \
+    --publish \
+    --registry "${REGISTRY}" \
+    --owner "${OWNER}" \
+    --version "${VERSION}" \
+    --stable "${IS_STABLE}" \
+    --target virgin
+
+  # full (default target)
+  PKGMGR_DISTRO="${d}" bash "${SCRIPT_DIR}/image.sh" \
+    --publish \
+    --registry "${REGISTRY}" \
+    --owner "${OWNER}" \
+    --version "${VERSION}" \
+    --stable "${IS_STABLE}"
+done
+
+echo
+echo "[publish] Done."

scripts/build/resolve-base-image.sh

@@ -1,18 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-resolve_base_image() {
-  local distro="$1"
-
-  case "$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
-      ;;
-  esac
-}

scripts/docker/entry.sh

@@ -1,55 +1,6 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-# ---------------------------------------------------------------------------
-# Detect and export a valid CA bundle so Nix, Git, curl and Python tooling
-# can successfully perform HTTPS requests on all distros (Debian, Ubuntu,
-# Fedora, RHEL, CentOS, etc.)
-# ---------------------------------------------------------------------------
-detect_ca_bundle() {
-  # Common CA bundle locations across major Linux distributions
-  local candidates=(
-    /etc/ssl/certs/ca-certificates.crt                       # Debian/Ubuntu
-    /etc/ssl/cert.pem                                       # Some distros
-    /etc/pki/tls/certs/ca-bundle.crt                        # Fedora/RHEL/CentOS
-    /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem       # CentOS/RHEL extracted bundle
-    /etc/ssl/ca-bundle.pem                                  # Generic fallback
-  )
-
-  for path in "${candidates[@]}"; do
-    if [[ -f "$path" ]]; then
-      echo "$path"
-      return 0
-    fi
-  done
-
-  return 1
-}
-
-# Use existing NIX_SSL_CERT_FILE if provided, otherwise auto-detect
-CA_BUNDLE="${NIX_SSL_CERT_FILE:-}"
-
-if [[ -z "${CA_BUNDLE}" ]]; then
-  CA_BUNDLE="$(detect_ca_bundle || true)"
-fi
-
-if [[ -n "${CA_BUNDLE}" ]]; then
-  # Export for Nix (critical)
-  export NIX_SSL_CERT_FILE="${CA_BUNDLE}"
-
-  # Export for Git, Python requests, curl, etc.
-  export SSL_CERT_FILE="${CA_BUNDLE}"
-  export REQUESTS_CA_BUNDLE="${CA_BUNDLE}"
-  export GIT_SSL_CAINFO="${CA_BUNDLE}"
-
-  echo "[docker] Using CA bundle: ${CA_BUNDLE}"
-else
-  echo "[docker] WARNING: No CA certificate bundle found."
-  echo "[docker] HTTPS access for Nix flakes and other tools may fail."
-fi
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-
 echo "[docker] Starting package-manager container"
 
 # ---------------------------------------------------------------------------
@@ -68,16 +19,10 @@ cd /src
 # ---------------------------------------------------------------------------
 # DEV mode: rebuild package-manager from the mounted /src tree
 # ---------------------------------------------------------------------------
-if [[ "${PKGMGR_DEV:-0}" == "1" ]]; then
-  echo "[docker] DEV mode enabled (PKGMGR_DEV=1)"
-  echo "[docker] Rebuilding package-manager from /src via scripts/installation/run-package.sh..."
-
-  if [[ -x scripts/installation/run-package.sh ]]; then
-    bash scripts/installation/run-package.sh
-  else
-    echo "[docker] ERROR: scripts/installation/run-package.sh not found or not executable"
-    exit 1
-  fi
+if [[ "${REINSTALL_PKGMGR:-0}" == "1" ]]; then
+  echo "[docker] DEV mode enabled (REINSTALL_PKGMGR=1)"
+  echo "[docker] Rebuilding package-manager from /src via scripts/installation/package.sh..."
+  bash scripts/installation/package.sh || exit 1
 fi
 
 # ---------------------------------------------------------------------------

scripts/init-nix.sh

@@ -1,229 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-echo "[init-nix] Starting Nix initialization..."
-
-# ---------------------------------------------------------------------------
-# Helper: detect whether we are inside a container (Docker/Podman/etc.)
-# ---------------------------------------------------------------------------
-is_container() {
-  # Docker / Podman markers
-  if [[ -f /.dockerenv ]] || [[ -f /run/.containerenv ]]; then
-    return 0
-  fi
-
-  # cgroup hints
-  if grep -qiE 'docker|container|podman|lxc' /proc/1/cgroup 2>/dev/null; then
-    return 0
-  fi
-
-  # Environment variable used by some runtimes
-  if [[ -n "${container:-}" ]]; then
-    return 0
-  fi
-
-  return 1
-}
-
-# ---------------------------------------------------------------------------
-# Helper: ensure Nix binaries are on PATH (multi-user or single-user)
-# ---------------------------------------------------------------------------
-ensure_nix_on_path() {
-  # Multi-user profile (daemon install)
-  if [[ -x /nix/var/nix/profiles/default/bin/nix ]]; then
-    export PATH="/nix/var/nix/profiles/default/bin:${PATH}"
-  fi
-
-  # Single-user profile (current user)
-  if [[ -x "${HOME}/.nix-profile/bin/nix" ]]; then
-    export PATH="${HOME}/.nix-profile/bin:${PATH}"
-  fi
-
-  # Single-user profile for dedicated "nix" user (container case)
-  if [[ -x /home/nix/.nix-profile/bin/nix ]]; then
-    export PATH="/home/nix/.nix-profile/bin:${PATH}"
-  fi
-}
-
-# ---------------------------------------------------------------------------
-# Fast path: Nix already available
-# ---------------------------------------------------------------------------
-if command -v nix >/dev/null 2>&1; then
-  echo "[init-nix] Nix already available on PATH: $(command -v nix)"
-  exit 0
-fi
-
-ensure_nix_on_path
-
-if command -v nix >/dev/null 2>&1; then
-  echo "[init-nix] Nix found after adjusting PATH: $(command -v nix)"
-  exit 0
-fi
-
-echo "[init-nix] Nix not found, starting installation logic..."
-
-IN_CONTAINER=0
-if is_container; then
-  IN_CONTAINER=1
-  echo "[init-nix] Detected container environment."
-else
-  echo "[init-nix] No container detected."
-fi
-
-# ---------------------------------------------------------------------------
-# Container + root: install Nix as dedicated "nix" user (single-user)
-# ---------------------------------------------------------------------------
-if [[ "${IN_CONTAINER}" -eq 1 && "${EUID:-0}" -eq 0 ]]; then
-  echo "[init-nix] Running as root inside a container – using dedicated 'nix' user."
-
-  # Ensure nixbld group (required by Nix)
-  if ! getent group nixbld >/dev/null 2>&1; then
-    echo "[init-nix] Creating group 'nixbld'..."
-    groupadd -r nixbld
-  fi
-
-  # Ensure Nix build users (nixbld1..nixbld10) as members of nixbld
-  for i in $(seq 1 10); do
-    if ! id "nixbld$i" >/dev/null 2>&1; then
-      echo "[init-nix] Creating build user nixbld$i..."
-      # -r: system account, -g: primary group, -G: supplementary (ensures membership is listed)
-      useradd -r -g nixbld -G nixbld -s /usr/sbin/nologin "nixbld$i"
-    fi
-  done
-
-  # Ensure "nix" user (home at /home/nix)
-  if ! id nix >/dev/null 2>&1; then
-    echo "[init-nix] Creating user 'nix'..."
-    useradd -m -r -g nixbld -s /usr/bin/bash nix
-  fi
-
-  # Ensure /nix exists and is writable by the "nix" user.
-  #
-  # In some base images (or previous runs), /nix may already exist and be
-  # owned by root. In that case the Nix single-user installer will abort with:
-  #
-  #   "directory /nix exists, but is not writable by you"
-  #
-  # To keep container runs idempotent and robust, we always enforce
-  # ownership nix:nixbld here.
-  if [[ ! -d /nix ]]; then
-    echo "[init-nix] Creating /nix with owner nix:nixbld..."
-    mkdir -m 0755 /nix
-    chown nix:nixbld /nix
-  else
-    current_owner="$(stat -c '%U' /nix 2>/dev/null || echo '?')"
-    current_group="$(stat -c '%G' /nix 2>/dev/null || echo '?')"
-    if [[ "${current_owner}" != "nix" || "${current_group}" != "nixbld" ]]; then
-      echo "[init-nix] /nix already exists with owner ${current_owner}:${current_group} – fixing to nix:nixbld..."
-      chown -R nix:nixbld /nix
-    else
-      echo "[init-nix] /nix already exists with correct owner nix:nixbld."
-    fi
-
-    if [[ ! -w /nix ]]; then
-      echo "[init-nix] WARNING: /nix is still not writable after chown; Nix installer may fail."
-    fi
-  fi
-
-  # Run Nix single-user installer as "nix"
-  echo "[init-nix] Installing Nix as user 'nix' (single-user, --no-daemon)..."
-  if command -v sudo >/dev/null 2>&1; then
-    sudo -u nix bash -lc 'sh <(curl -L https://nixos.org/nix/install) --no-daemon'
-  else
-    su - nix -c 'sh <(curl -L https://nixos.org/nix/install) --no-daemon'
-  fi
-
-  # After installation, expose nix to root via PATH and symlink
-  ensure_nix_on_path
-
-  if [[ -x /home/nix/.nix-profile/bin/nix ]]; then
-    if [[ ! -e /usr/local/bin/nix ]]; then
-      echo "[init-nix] Creating /usr/local/bin/nix symlink -> /home/nix/.nix-profile/bin/nix"
-      ln -s /home/nix/.nix-profile/bin/nix /usr/local/bin/nix
-    fi
-  fi
-
-  ensure_nix_on_path
-
-  if command -v nix >/dev/null 2>&1; then
-    echo "[init-nix] Nix successfully installed (container mode) at: $(command -v nix)"
-  else
-    echo "[init-nix] WARNING: Nix installation finished in container, but 'nix' is still not on PATH."
-  fi
-
-  # Optionally add PATH hints to /etc/profile (best effort)
-  if [[ -w /etc/profile ]]; then
-    if ! grep -q 'Nix profiles' /etc/profile 2>/dev/null; then
-      cat <<'EOF' >> /etc/profile
-
-# Nix profiles (added by package-manager init-nix.sh)
-if [ -d /nix/var/nix/profiles/default/bin ]; then
-  PATH="/nix/var/nix/profiles/default/bin:$PATH"
-fi
-if [ -d "$HOME/.nix-profile/bin" ]; then
-  PATH="$HOME/.nix-profile/bin:$PATH"
-fi
-EOF
-      echo "[init-nix] Appended Nix PATH setup to /etc/profile (container mode)."
-    fi
-  fi
-
-  echo "[init-nix] Nix initialization complete (container root mode)."
-  exit 0
-fi
-
-# ---------------------------------------------------------------------------
-# Non-container or non-root container: normal installer paths
-# ---------------------------------------------------------------------------
-if [[ "${IN_CONTAINER}" -eq 0 ]]; then
-  # Real host
-  if command -v systemctl >/dev/null 2>&1; then
-    echo "[init-nix] Host with systemd – using multi-user install (--daemon)."
-    sh <(curl -L https://nixos.org/nix/install) --daemon
-  else
-    if [[ "${EUID:-0}" -eq 0 ]]; then
-      echo "[init-nix] WARNING: Running as root without systemd on host."
-      echo "[init-nix] Falling back to single-user install (--no-daemon), but this is not recommended."
-      sh <(curl -L https://nixos.org/nix/install) --no-daemon
-    else
-      echo "[init-nix] Non-root host without systemd – using single-user install (--no-daemon)."
-      sh <(curl -L https://nixos.org/nix/install) --no-daemon
-    fi
-  fi
-else
-  # Container, but not root (rare)
-  echo "[init-nix] Container as non-root user – using single-user install (--no-daemon)."
-  sh <(curl -L https://nixos.org/nix/install) --no-daemon
-fi
-
-# ---------------------------------------------------------------------------
-# After installation: fix PATH (runtime + shell profiles)
-# ---------------------------------------------------------------------------
-ensure_nix_on_path
-
-if ! command -v nix >/dev/null 2>&1; then
-  echo "[init-nix] WARNING: Nix installation finished, but 'nix' is still not on PATH."
-  echo "[init-nix] You may need to source your shell profile manually."
-  exit 0
-fi
-
-echo "[init-nix] Nix successfully installed at: $(command -v nix)"
-
-# Update global /etc/profile if writable (helps especially on minimal systems)
-if [[ -w /etc/profile ]]; then
-  if ! grep -q 'Nix profiles' /etc/profile 2>/dev/null; then
-    cat <<'EOF' >> /etc/profile
-
-# Nix profiles (added by package-manager init-nix.sh)
-if [ -d /nix/var/nix/profiles/default/bin ]; then
-  PATH="/nix/var/nix/profiles/default/bin:$PATH"
-fi
-if [ -d "$HOME/.nix-profile/bin" ]; then
-  PATH="$HOME/.nix-profile/bin:$PATH"
-fi
-EOF
-    echo "[init-nix] Appended Nix PATH setup to /etc/profile"
-  fi
-fi
-
-echo "[init-nix] Nix initialization complete."

scripts/installation/arch/aur-builder-setup.sh

@@ -45,8 +45,42 @@ else
 fi
 
 echo "[aur-builder-setup] Ensuring yay is installed for aur_builder..."
+
 if ! "${RUN_AS_AUR[@]}" 'command -v yay >/dev/null 2>&1'; then
-  "${RUN_AS_AUR[@]}" 'cd ~ && rm -rf yay && git clone https://aur.archlinux.org/yay.git && cd yay && makepkg -si --noconfirm'
+  echo "[aur-builder-setup] yay not found – starting retry sequence for download..."
+
+  MAX_TIME=300
+  SLEEP_INTERVAL=20
+  ELAPSED=0
+
+  while true; do
+    if "${RUN_AS_AUR[@]}" '
+        set -euo pipefail
+        cd ~
+        rm -rf yay || true
+        git clone https://aur.archlinux.org/yay.git yay
+    '; then
+        echo "[aur-builder-setup] yay repository cloned successfully."
+        break
+    fi
+
+    echo "[aur-builder-setup] git clone failed (likely 504). Retrying in ${SLEEP_INTERVAL}s..."
+    sleep "${SLEEP_INTERVAL}"
+    ELAPSED=$((ELAPSED + SLEEP_INTERVAL))
+
+    if (( ELAPSED >= MAX_TIME )); then
+      echo "[aur-builder-setup] ERROR: Aborted after 5 minutes of retry attempts."
+      exit 1
+    fi
+  done
+
+  # Now build yay after successful clone
+  "${RUN_AS_AUR[@]}" '
+      set -euo pipefail
+      cd ~/yay
+      makepkg -si --noconfirm
+  '
+
 else
   echo "[aur-builder-setup] yay already installed."
 fi

scripts/installation/arch/dependencies.sh

@@ -12,6 +12,7 @@ pacman -S --noconfirm --needed \
   rsync \
   curl \
   ca-certificates \
+  python \
   xz
 
 pacman -Scc --noconfirm

scripts/installation/arch/package.sh

@@ -1,19 +1,64 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-echo "[arch/package] Building Arch package (makepkg --nodeps)..."
+echo "[arch/package] Building Arch package (makepkg --nodeps) in an isolated build dir..."
 
-if id aur_builder >/dev/null 2>&1; then
-  echo "[arch/package] Using 'aur_builder' user for makepkg..."
-  chown -R aur_builder:aur_builder "$(pwd)"
-  su aur_builder -c "cd '$(pwd)' && rm -f package-manager-*.pkg.tar.* && makepkg --noconfirm --clean --nodeps"
-else
-  echo "[arch/package] WARNING: user 'aur_builder' not found, running makepkg as current user..."
-  rm -f package-manager-*.pkg.tar.*
-  makepkg --noconfirm --clean --nodeps
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "${SCRIPT_DIR}/../../.." && pwd)"
+
+# We must not build inside /src (mounted repo). Build in /tmp to avoid permission issues.
+BUILD_ROOT="/tmp/package-manager-arch-build"
+PKG_SRC_DIR="${PROJECT_ROOT}/packaging/arch"
+PKG_BUILD_DIR="${BUILD_ROOT}/packaging/arch"
+
+if [[ ! -f "${PKG_SRC_DIR}/PKGBUILD" ]]; then
+  echo "[arch/package] ERROR: PKGBUILD not found in ${PKG_SRC_DIR}"
+  exit 1
 fi
 
+echo "[arch/package] Preparing build directory: ${BUILD_ROOT}"
+rm -rf "${BUILD_ROOT}"
+mkdir -p "${BUILD_ROOT}"
+
+echo "[arch/package] Syncing project sources to ${BUILD_ROOT}..."
+# Keep it simple: copy everything; adjust excludes if needed later.
+rsync -a --delete \
+  --exclude '.git' \
+  --exclude '.venv' \
+  --exclude '.venvs' \
+  --exclude '__pycache__' \
+  --exclude '*.pyc' \
+  "${PROJECT_ROOT}/" "${BUILD_ROOT}/"
+
+if [[ ! -d "${PKG_BUILD_DIR}" ]]; then
+  echo "[arch/package] ERROR: Build PKG dir missing: ${PKG_BUILD_DIR}"
+  exit 1
+fi
+
+# ------------------------------------------------------------
+# Unprivileged user for Arch package build (makepkg)
+# ------------------------------------------------------------
+if ! id aur_builder >/dev/null 2>&1; then
+  echo "[arch/package] ERROR: user 'aur_builder' not found. Run scripts/installation/arch/aur-builder-setup.sh first."
+  exit 1
+fi
+
+echo "[arch/package] Using 'aur_builder' user for makepkg..."
+chown -R aur_builder:aur_builder "${BUILD_ROOT}"
+
+echo "[arch/package] Running makepkg in: ${PKG_BUILD_DIR}"
+su aur_builder -c "cd '${PKG_BUILD_DIR}' && rm -f package-manager-*.pkg.tar.* && makepkg --noconfirm --clean --nodeps"
+
 echo "[arch/package] Installing generated Arch package..."
-pacman -U --noconfirm package-manager-*.pkg.tar.*
+pkg_path="$(find "${PKG_BUILD_DIR}" -maxdepth 1 -type f -name 'package-manager-*.pkg.tar.*' | head -n1)"
+if [[ -z "${pkg_path}" ]]; then
+  echo "[arch/package] ERROR: Built package not found in ${PKG_BUILD_DIR}"
+  exit 1
+fi
+
+pacman -U --noconfirm "${pkg_path}"
+
+echo "[arch/package] Cleanup build directory..."
+rm -rf "${BUILD_ROOT}"
 
 echo "[arch/package] Done."

scripts/installation/centos/dependencies.sh

@@ -13,9 +13,64 @@ dnf -y install \
   bash \
   curl-minimal \
   ca-certificates \
+  python3 \
   sudo \
   xz
 
 dnf clean all
 
+# -----------------------------------------------------------------------------
+# Persist CA bundle configuration system-wide (virgin-compatible)
+# -----------------------------------------------------------------------------
+detect_ca_bundle() {
+  local candidates=(
+    /etc/pki/tls/certs/ca-bundle.crt
+    /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem
+    /etc/ssl/certs/ca-certificates.crt
+    /etc/ssl/cert.pem
+    /etc/ssl/ca-bundle.pem
+  )
+
+  for path in "${candidates[@]}"; do
+    if [[ -f "$path" ]]; then
+      echo "$path"
+      return 0
+    fi
+  done
+
+  return 1
+}
+
+CA_BUNDLE="$(detect_ca_bundle || true)"
+
+if [[ -n "${CA_BUNDLE}" ]]; then
+  echo "[centos/dependencies] Persisting CA bundle: ${CA_BUNDLE}"
+
+  # 1) Make it available for login shells
+  cat >/etc/profile.d/pkgmgr-ca.sh <<EOF
+# Generated by package-manager
+export NIX_SSL_CERT_FILE="${CA_BUNDLE}"
+export SSL_CERT_FILE="${CA_BUNDLE}"
+export REQUESTS_CA_BUNDLE="${CA_BUNDLE}"
+export GIT_SSL_CAINFO="${CA_BUNDLE}"
+EOF
+  chmod 0644 /etc/profile.d/pkgmgr-ca.sh
+
+  # 2) Ensure Nix uses it even without environment variables
+  mkdir -p /etc/nix
+  if [[ -f /etc/nix/nix.conf ]]; then
+    # Replace existing ssl-cert-file or append it
+    if grep -qE '^\s*ssl-cert-file\s*=' /etc/nix/nix.conf; then
+      sed -i "s|^\s*ssl-cert-file\s*=.*|ssl-cert-file = ${CA_BUNDLE}|" /etc/nix/nix.conf
+    else
+      echo "ssl-cert-file = ${CA_BUNDLE}" >>/etc/nix/nix.conf
+    fi
+  else
+    echo "ssl-cert-file = ${CA_BUNDLE}" >/etc/nix/nix.conf
+  fi
+
+else
+  echo "[centos/dependencies] WARNING: No CA bundle found after installing ca-certificates."
+fi
+
 echo "[centos/dependencies] Done."

scripts/installation/centos/package.sh

@@ -4,8 +4,17 @@ set -euo pipefail
 echo "[centos/package] Setting up rpmbuild directories..."
 mkdir -p /root/rpmbuild/{BUILD,RPMS,SOURCES,SPECS,SRPMS}
 
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "${SCRIPT_DIR}/../../.." && pwd)"
+SPEC_PATH="${PROJECT_ROOT}/packaging/fedora/package-manager.spec"
+
+if [[ ! -f "${SPEC_PATH}" ]]; then
+  echo "[centos/package] ERROR: SPEC file not found: ${SPEC_PATH}"
+  exit 1
+fi
+
 echo "[centos/package] Extracting version from package-manager.spec..."
-version="$(grep -E '^Version:' package-manager.spec | awk '{print $2}')"
+version="$(grep -E '^Version:' "${SPEC_PATH}" | awk '{print $2}')"
 if [[ -z "${version}" ]]; then
   echo "ERROR: Version missing!"
   exit 1
@@ -15,13 +24,13 @@ srcdir="package-manager-${version}"
 echo "[centos/package] Preparing source tree: ${srcdir}"
 rm -rf "/tmp/${srcdir}"
 mkdir -p "/tmp/${srcdir}"
-cp -a . "/tmp/${srcdir}/"
+cp -a "${PROJECT_ROOT}/." "/tmp/${srcdir}/"
 
 echo "[centos/package] Creating source tarball..."
 tar czf "/root/rpmbuild/SOURCES/${srcdir}.tar.gz" -C /tmp "${srcdir}"
 
 echo "[centos/package] Copying SPEC..."
-cp package-manager.spec /root/rpmbuild/SPECS/
+cp "${SPEC_PATH}" /root/rpmbuild/SPECS/
 
 echo "[centos/package] Running rpmbuild..."
 cd /root/rpmbuild/SPECS

scripts/installation/debian/dependencies.sh

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

scripts/installation/debian/package.sh

@@ -3,6 +3,25 @@ set -euo pipefail
 
 echo "[debian/package] Building Debian package..."
 
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "${SCRIPT_DIR}/../../.." && pwd)"
+
+BUILD_ROOT="/tmp/package-manager-debian-build"
+rm -rf "${BUILD_ROOT}"
+mkdir -p "${BUILD_ROOT}"
+
+echo "[debian/package] Syncing project sources to ${BUILD_ROOT}..."
+rsync -a \
+  --exclude 'packaging/debian' \
+  "${PROJECT_ROOT}/" "${BUILD_ROOT}/"
+
+echo "[debian/package] Overlaying debian/ metadata from packaging/debian..."
+mkdir -p "${BUILD_ROOT}/debian"
+cp -a "${PROJECT_ROOT}/packaging/debian/." "${BUILD_ROOT}/debian/"
+
+cd "${BUILD_ROOT}"
+
+echo "[debian/package] Running dpkg-buildpackage..."
 dpkg-buildpackage -us -uc -b
 
 echo "[debian/package] Installing generated DEB package..."

scripts/installation/dependencies.sh

@@ -3,22 +3,19 @@ set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
-# shellcheck source=/dev/null
-source "${SCRIPT_DIR}/lib.sh"
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/os_resolver.sh"
 
-OS_ID="$(detect_os_id)"
+OS_ID="$(osr_get_os_id)"
 
 echo "[run-dependencies] Detected OS: ${OS_ID}"
 
-case "${OS_ID}" in
-  arch|debian|ubuntu|fedora|centos)
-    DEP_SCRIPT="${SCRIPT_DIR}/${OS_ID}/dependencies.sh"
-    ;;
-  *)
-    echo "[run-dependencies] Unsupported OS: ${OS_ID}"
-    exit 1
-    ;;
-esac
+if ! osr_is_supported "${OS_ID}"; then
+  echo "[run-dependencies] Unsupported OS: ${OS_ID}"
+  exit 1
+fi
+
+DEP_SCRIPT="$(osr_script_path_for "${SCRIPT_DIR}" "${OS_ID}" "dependencies")"
 
 if [[ ! -f "${DEP_SCRIPT}" ]]; then
   echo "[run-dependencies] Dependency script not found: ${DEP_SCRIPT}"

scripts/installation/fedora/package.sh

@@ -4,8 +4,17 @@ set -euo pipefail
 echo "[fedora/package] Setting up rpmbuild directories..."
 mkdir -p /root/rpmbuild/{BUILD,RPMS,SOURCES,SPECS,SRPMS}
 
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "${SCRIPT_DIR}/../../.." && pwd)"
+SPEC_PATH="${PROJECT_ROOT}/packaging/fedora/package-manager.spec"
+
+if [[ ! -f "${SPEC_PATH}" ]]; then
+  echo "[fedora/package] ERROR: SPEC file not found: ${SPEC_PATH}"
+  exit 1
+fi
+
 echo "[fedora/package] Extracting version from package-manager.spec..."
-version="$(grep -E '^Version:' package-manager.spec | awk '{print $2}')"
+version="$(grep -E '^Version:' "${SPEC_PATH}" | awk '{print $2}')"
 if [[ -z "${version}" ]]; then
   echo "ERROR: Version missing!"
   exit 1
@@ -15,13 +24,13 @@ srcdir="package-manager-${version}"
 echo "[fedora/package] Preparing source tree: ${srcdir}"
 rm -rf "/tmp/${srcdir}"
 mkdir -p "/tmp/${srcdir}"
-cp -a . "/tmp/${srcdir}/"
+cp -a "${PROJECT_ROOT}/." "/tmp/${srcdir}/"
 
 echo "[fedora/package] Creating source tarball..."
 tar czf "/root/rpmbuild/SOURCES/${srcdir}.tar.gz" -C /tmp "${srcdir}"
 
 echo "[fedora/package] Copying SPEC..."
-cp package-manager.spec /root/rpmbuild/SPECS/
+cp "${SPEC_PATH}" /root/rpmbuild/SPECS/
 
 echo "[fedora/package] Running rpmbuild..."
 cd /root/rpmbuild/SPECS

scripts/installation/init.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ "${EUID:-$(id -u)}" -ne 0 ]]; then
+  echo "[installation/install] Warning: Installation is just possible via root."
+  exit 0
+fi
+
+echo "[installation] Running as root (EUID=0)."
+echo "[installation] Install Package Dependencies..."
+bash  scripts/installation/dependencies.sh
+echo "[installation] Install Distribution Package..."
+bash scripts/installation/package.sh
+echo "[installation] Root/system setup complete."
+exit 0

scripts/installation/lib.sh

@@ -1,12 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-detect_os_id() {
-  if [[ -f /etc/os-release ]]; then
-    # shellcheck disable=SC1091
-    . /etc/os-release
-    echo "${ID:-unknown}"
-  else
-    echo "unknown"
-  fi
-}

scripts/installation/main.sh

@@ -1,89 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-# ------------------------------------------------------------
-# main.sh
-#
-# Developer setup entrypoint.
-#
-# Responsibilities:
-#   - If inside a Nix shell (IN_NIX_SHELL=1):
-#       * Skip venv creation and dependency installation
-#       * Run `python3 main.py install`
-#   - Otherwise:
-#       * Create ~/.venvs/pkgmgr virtual environment if missing
-#       * Install Python dependencies into that venv
-#       * Append auto-activation to ~/.bashrc and ~/.zshrc
-#       * Run `main.py install` using the venv Python
-# ------------------------------------------------------------
-
-echo "[installation/main] Starting developer setup..."
-
-PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
-cd "${PROJECT_ROOT}"
-
-VENV_DIR="${HOME}/.venvs/pkgmgr"
-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'
-
-# ------------------------------------------------------------
-# Nix shell mode: do not touch venv, only run main.py install
-# ------------------------------------------------------------
-if [[ -n "${IN_NIX_SHELL:-}" ]]; then
-    echo "[installation/main] Nix shell detected (IN_NIX_SHELL=1)."
-    echo "[installation/main] Skipping virtualenv creation and dependency installation."
-    echo "[installation/main] Running main.py install via system python3..."
-    python3 main.py install
-    echo "[installation/main] Developer setup finished (Nix mode)."
-    exit 0
-fi
-
-# ------------------------------------------------------------
-# Normal host mode: create/update venv and run main.py install
-# ------------------------------------------------------------
-
-echo "[installation/main] Ensuring main.py is executable..."
-chmod +x main.py || true
-
-echo "[installation/main] Ensuring global virtualenv root: ${HOME}/.venvs"
-mkdir -p "${HOME}/.venvs"
-
-if [[ ! -d "${VENV_DIR}" ]]; then
-    echo "[installation/main] Creating virtual environment at: ${VENV_DIR}"
-    python3 -m venv "${VENV_DIR}"
-else
-    echo "[installation/main] Virtual environment already exists at: ${VENV_DIR}"
-fi
-
-echo "[installation/main] Installing Python tooling into venv..."
-"${VENV_DIR}/bin/python" -m ensurepip --upgrade
-"${VENV_DIR}/bin/pip" install --upgrade pip setuptools wheel
-
-if [[ -f "requirements.txt" ]]; then
-    echo "[installation/main] Installing dependencies from requirements.txt..."
-    "${VENV_DIR}/bin/pip" install -r requirements.txt
-elif [[ -f "_requirements.txt" ]]; then
-    echo "[installation/main] Installing dependencies from _requirements.txt..."
-    "${VENV_DIR}/bin/pip" install -r _requirements.txt
-else
-    echo "[installation/main] No requirements.txt or _requirements.txt found. Skipping dependency installation."
-fi
-
-echo "[installation/main] Ensuring ~/.bashrc and ~/.zshrc exist..."
-touch "${HOME}/.bashrc" "${HOME}/.zshrc"
-
-echo "[installation/main] Ensuring venv auto-activation is present in shell rc files..."
-for rc in "${HOME}/.bashrc" "${HOME}/.zshrc"; do
-    if ! grep -qxF "${RC_LINE}" "$rc"; then
-        echo "${RC_LINE}" >> "$rc"
-        echo "[installation/main] Appended auto-activation to $rc"
-    else
-        echo "[installation/main] Auto-activation already present in $rc"
-    fi
-done
-
-echo "[installation/main] Running main.py install via venv Python..."
-"${VENV_DIR}/bin/python" main.py install
-
-echo
-echo "[installation/main] Developer setup complete."
-echo "Restart your shell (or run 'exec bash' or 'exec zsh') to activate the environment."

scripts/installation/os_resolver.sh

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# -----------------------------------------------------------------------------
+# OsResolver (bash "class-style" module)
+# Centralizes OS detection + normalization + supported checks + script paths.
+# -----------------------------------------------------------------------------
+
+osr_detect_raw_id() {
+  if [[ -f /etc/os-release ]]; then
+    # shellcheck disable=SC1091
+    . /etc/os-release
+    echo "${ID:-unknown}"
+  else
+    echo "unknown"
+  fi
+}
+
+osr_detect_id_like() {
+  if [[ -f /etc/os-release ]]; then
+    # shellcheck disable=SC1091
+    . /etc/os-release
+    echo "${ID_LIKE:-}"
+  else
+    echo ""
+  fi
+}
+
+osr_normalize_id() {
+  local raw="${1:-unknown}"
+  local like="${2:-}"
+
+  # Explicit mapping first (your bugfix: manjaro -> arch everywhere)
+  case "${raw}" in
+    manjaro) echo "arch"; return 0 ;;
+  esac
+
+  # Keep direct IDs when they are already supported
+  case "${raw}" in
+    arch|debian|ubuntu|fedora|centos) echo "${raw}"; return 0 ;;
+  esac
+
+  # Fallback mapping via ID_LIKE for better portability
+  # Example: many Arch derivatives expose ID_LIKE="arch"
+  if [[ " ${like} " == *" arch "* ]]; then
+    echo "arch"; return 0
+  fi
+  if [[ " ${like} " == *" debian "* ]]; then
+    echo "debian"; return 0
+  fi
+  if [[ " ${like} " == *" fedora "* ]]; then
+    echo "fedora"; return 0
+  fi
+  if [[ " ${like} " == *" rhel "* || " ${like} " == *" centos "* ]]; then
+    echo "centos"; return 0
+  fi
+
+  echo "${raw}"
+}
+
+osr_get_os_id() {
+  local raw like
+  raw="$(osr_detect_raw_id)"
+  like="$(osr_detect_id_like)"
+  osr_normalize_id "${raw}" "${like}"
+}
+
+osr_is_supported() {
+  local id="${1:-unknown}"
+  case "${id}" in
+    arch|debian|ubuntu|fedora|centos) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+osr_script_path_for() {
+  local script_dir="${1:?script_dir required}"
+  local os_id="${2:?os_id required}"
+  local kind="${3:?kind required}" # "dependencies" or "package"
+
+  echo "${script_dir}/${os_id}/${kind}.sh"
+}

scripts/installation/package.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/os_resolver.sh"
+
+OS_ID="$(osr_get_os_id)"
+
+echo "[package] Detected OS: ${OS_ID}"
+
+if ! osr_is_supported "${OS_ID}"; then
+  echo "[package] Unsupported OS: ${OS_ID}"
+  exit 1
+fi
+
+PKG_SCRIPT="$(osr_script_path_for "${SCRIPT_DIR}" "${OS_ID}" "package")"
+
+if [[ ! -f "${PKG_SCRIPT}" ]]; then
+  echo "[package] Package script not found: ${PKG_SCRIPT}"
+  exit 1
+fi
+
+echo "[package] Executing: ${PKG_SCRIPT}"
+exec bash "${PKG_SCRIPT}"

scripts/installation/run-package.sh

@@ -1,29 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-
-# shellcheck source=/dev/null
-source "${SCRIPT_DIR}/lib.sh"
-
-OS_ID="$(detect_os_id)"
-
-echo "[run-package] Detected OS: ${OS_ID}"
-
-case "${OS_ID}" in
-  arch|debian|ubuntu|fedora|centos)
-    PKG_SCRIPT="${SCRIPT_DIR}/${OS_ID}/package.sh"
-    ;;
-  *)
-    echo "[run-package] Unsupported OS: ${OS_ID}"
-    exit 1
-    ;;
-esac
-
-if [[ ! -f "${PKG_SCRIPT}" ]]; then
-  echo "[run-package] Package script not found: ${PKG_SCRIPT}"
-  exit 1
-fi
-
-echo "[run-package] Executing: ${PKG_SCRIPT}"
-exec bash "${PKG_SCRIPT}"

scripts/installation/ubuntu/dependencies.sh

@@ -14,6 +14,9 @@ DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
   rsync \
   bash \
   curl \
+  make \
+  python3 \
+  python3-venv \
   ca-certificates \
   xz-utils
 

scripts/installation/ubuntu/package.sh

@@ -3,6 +3,25 @@ set -euo pipefail
 
 echo "[ubuntu/package] Building Ubuntu (Debian-style) package..."
 
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "${SCRIPT_DIR}/../../.." && pwd)"
+
+BUILD_ROOT="/tmp/package-manager-ubuntu-build"
+rm -rf "${BUILD_ROOT}"
+mkdir -p "${BUILD_ROOT}"
+
+echo "[ubuntu/package] Syncing project sources to ${BUILD_ROOT}..."
+rsync -a \
+  --exclude 'packaging/debian' \
+  "${PROJECT_ROOT}/" "${BUILD_ROOT}/"
+
+echo "[ubuntu/package] Overlaying debian/ metadata from packaging/debian..."
+mkdir -p "${BUILD_ROOT}/debian"
+cp -a "${PROJECT_ROOT}/packaging/debian/." "${BUILD_ROOT}/debian/"
+
+cd "${BUILD_ROOT}"
+
+echo "[ubuntu/package] Running dpkg-buildpackage..."
 dpkg-buildpackage -us -uc -b
 
 echo "[ubuntu/package] Installing generated DEB package..."

scripts/nix/README.md

@@ -0,0 +1,53 @@
+# Nix Bootstrap (package-manager)
+
+This directory contains the **Nix initialization and bootstrap logic** used by *package-manager* to ensure the `nix` command is available on supported systems (host machines and CI containers).
+
+It is invoked during package installation (Arch/Debian/Fedora scriptlets) and can also be called manually.
+
+---
+
+## Entry Point
+
+- *scripts/nix/init.sh*  
+  Main bootstrap script. It:
+  - checks whether `nix` is already available
+  - adjusts `PATH` for common Nix locations
+  - installs Nix when missing (daemon install on systemd hosts, single-user in containers)
+  - ensures predictable `nix` availability via symlinks (without overwriting distro-managed paths)
+  - validates that `nix` is usable at the end (CI-safe)
+
+---
+
+## Library Layout
+
+The entry point sources small, focused modules from *scripts/nix/lib/*:
+
+- *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
+- *users.sh* — build group/users and container ownership/perms helpers
+- *install.sh* — installer download + retry logic and execution helpers
+
+Each library file includes a simple guard to prevent double-sourcing.
+
+---
+
+## When It Runs
+
+This bootstrap is typically executed automatically:
+
+- Arch: post-install / post-upgrade hook
+- Debian: `postinst`
+- Fedora/RPM: `%post`
+
+
+---
+
+## Notes / Design Goals
+
+- **Cross-distro compatibility:** supports common Linux layouts (including Arch placing `nix` in */usr/sbin*).
+- **Non-destructive behavior:** avoids overwriting distro-managed `nix` binaries.
+- **CI robustness:** retry logic for downloads and a final `nix` availability check.
+- **Container-safe defaults:** single-user install as a dedicated `nix` user when running as root in containers.
+

scripts/nix/init.sh

@@ -0,0 +1,142 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# shellcheck source=./scripts/nix/lib/bootstrap_config.sh
+source "${SCRIPT_DIR}/lib/bootstrap_config.sh"
+
+# shellcheck source=./scripts/nix/lib/detect.sh
+source "${SCRIPT_DIR}/lib/detect.sh"
+
+# shellcheck source=./scripts/nix/lib/path.sh
+source "${SCRIPT_DIR}/lib/path.sh"
+
+# shellcheck source=./scripts/nix/lib/symlinks.sh
+source "${SCRIPT_DIR}/lib/symlinks.sh"
+
+# shellcheck source=./scripts/nix/lib/users.sh
+source "${SCRIPT_DIR}/lib/users.sh"
+
+# shellcheck source=./scripts/nix/lib/install.sh
+source "${SCRIPT_DIR}/lib/install.sh"
+
+# shellcheck source=./scripts/nix/lib/nix_conf_file.sh
+source "${SCRIPT_DIR}/lib/nix_conf_file.sh"
+
+echo "[init-nix] Starting Nix initialization..."
+
+main() {
+  # Fast path: already available
+  if command -v nix >/dev/null 2>&1; then
+    echo "[init-nix] Nix already available on PATH: $(command -v nix)"
+    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)"
+    fi
+
+    return 0
+  fi
+
+  ensure_nix_on_path
+
+  if command -v nix >/dev/null 2>&1; then
+    echo "[init-nix] Nix found after PATH adjustment: $(command -v nix)"
+    if [[ "${EUID:-0}" -eq 0 ]]; then
+      ensure_global_nix_symlinks "$(resolve_nix_bin 2>/dev/null || true)"
+    else
+      ensure_user_nix_symlink "$(resolve_nix_bin 2>/dev/null || true)"
+    fi
+    return 0
+  fi
+
+  local IN_CONTAINER=0
+  if is_container; then
+    IN_CONTAINER=1
+    echo "[init-nix] Detected container environment."
+  else
+    echo "[init-nix] No container detected."
+  fi
+
+  # -------------------------------------------------------------------------
+  # Container + root: dedicated "nix" user, single-user install
+  # -------------------------------------------------------------------------
+  if [[ "$IN_CONTAINER" -eq 1 && "${EUID:-0}" -eq 0 ]]; then
+    echo "[init-nix] Container + root: installing as 'nix' user (single-user)."
+
+    ensure_nix_build_group
+
+    if ! id nix >/dev/null 2>&1; then
+      echo "[init-nix] Creating user 'nix'..."
+      local BASH_SHELL
+      BASH_SHELL="$(command -v bash || true)"
+      [[ -z "$BASH_SHELL" ]] && BASH_SHELL="/bin/sh"
+      useradd -m -r -g nixbld -s "$BASH_SHELL" nix
+    fi
+
+    ensure_nix_store_dir_for_container_user
+
+    install_nix_with_retry "no-daemon" "nix"
+
+    ensure_nix_on_path
+
+    # Ensure stable global symlink(s) (sudo secure_path friendly)
+    ensure_global_nix_symlinks "/home/nix/.nix-profile/bin/nix"
+
+    # Ensure non-root users can traverse and execute nix user profile
+    ensure_container_profile_perms
+
+  # -------------------------------------------------------------------------
+  # Host (no container)
+  # -------------------------------------------------------------------------
+  else
+    if command -v systemctl >/dev/null 2>&1; then
+      echo "[init-nix] Host with systemd: using multi-user install (--daemon)."
+      if [[ "${EUID:-0}" -eq 0 ]]; then
+        ensure_nix_build_group
+      fi
+      install_nix_with_retry "daemon"
+    else
+      echo "[init-nix] No systemd detected: using single-user install (--no-daemon)."
+      if [[ "${EUID:-0}" -eq 0 ]]; then
+        ensure_nix_build_group
+      fi
+      install_nix_with_retry "no-daemon"
+    fi
+  fi
+
+  # -------------------------------------------------------------------------
+  # After install: PATH + symlink(s)
+  # -------------------------------------------------------------------------
+  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)"
+
+  if [[ "${EUID:-0}" -eq 0 ]]; then
+    ensure_global_nix_symlinks "$nix_bin_post"
+  else
+    ensure_user_nix_symlink "$nix_bin_post"
+  fi
+
+  # Final verification (must succeed for CI)
+  if ! command -v nix >/dev/null 2>&1; then
+    echo "[init-nix] ERROR: nix not found after installation."
+    echo "[init-nix] DEBUG: resolved nix path = ${nix_bin_post:-<empty>}"
+    echo "[init-nix] DEBUG: PATH = $PATH"
+    exit 1
+  fi
+
+  echo "[init-nix] Nix successfully available at: $(command -v nix)"
+  echo "[init-nix] Nix initialization complete."
+}
+
+main "$@"

scripts/nix/lib/bootstrap_config.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+
+# Prevent double-sourcing
+if [[ -n "${PKGMGR_NIX_CONFIG_SH:-}" ]]; then
+  return 0
+fi
+PKGMGR_NIX_CONFIG_SH=1
+
+NIX_INSTALL_URL="${NIX_INSTALL_URL:-https://nixos.org/nix/install}"
+NIX_DOWNLOAD_MAX_TIME="${NIX_DOWNLOAD_MAX_TIME:-300}"
+NIX_DOWNLOAD_SLEEP_INTERVAL="${NIX_DOWNLOAD_SLEEP_INTERVAL:-20}"

scripts/nix/lib/detect.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+
+if [[ -n "${PKGMGR_NIX_DETECT_SH:-}" ]]; then
+  return 0
+fi
+PKGMGR_NIX_DETECT_SH=1
+
+# Detect whether we are inside a container (Docker/Podman/etc.)
+is_container() {
+  [[ -f /.dockerenv || -f /run/.containerenv ]] && return 0
+  grep -qiE 'docker|container|podman|lxc' /proc/1/cgroup 2>/dev/null && return 0
+  [[ -n "${container:-}" ]] && return 0
+  return 1
+}

scripts/nix/lib/install.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+
+if [[ -n "${PKGMGR_NIX_INSTALL_SH:-}" ]]; then
+  return 0
+fi
+PKGMGR_NIX_INSTALL_SH=1
+
+# Requires: NIX_INSTALL_URL, NIX_DOWNLOAD_MAX_TIME, NIX_DOWNLOAD_SLEEP_INTERVAL
+
+# Download and run Nix installer with retry
+#   Usage: install_nix_with_retry daemon|no-daemon [run_as_user]
+install_nix_with_retry() {
+  local mode="$1"
+  local run_as="${2:-}"
+  local installer elapsed=0 mode_flag
+
+  case "$mode" in
+    daemon)    mode_flag="--daemon" ;;
+    no-daemon) mode_flag="--no-daemon" ;;
+    *)
+      echo "[init-nix] ERROR: Invalid mode '$mode' (expected 'daemon' or 'no-daemon')."
+      exit 1
+      ;;
+  esac
+
+  installer="$(mktemp -t nix-installer.XXXXXX)"
+  chmod 0644 "$installer"
+
+  echo "[init-nix] Downloading Nix installer from $NIX_INSTALL_URL (max ${NIX_DOWNLOAD_MAX_TIME}s)..."
+
+  while true; do
+    if curl -fL "$NIX_INSTALL_URL" -o "$installer"; then
+      echo "[init-nix] Successfully downloaded installer to $installer"
+      break
+    fi
+
+    elapsed=$((elapsed + NIX_DOWNLOAD_SLEEP_INTERVAL))
+    echo "[init-nix] WARNING: Download failed. Retrying in ${NIX_DOWNLOAD_SLEEP_INTERVAL}s (elapsed ${elapsed}s)..."
+
+    if (( elapsed >= NIX_DOWNLOAD_MAX_TIME )); then
+      echo "[init-nix] ERROR: Giving up after ${elapsed}s trying to download Nix installer."
+      rm -f "$installer"
+      exit 1
+    fi
+
+    sleep "$NIX_DOWNLOAD_SLEEP_INTERVAL"
+  done
+
+  if [[ -n "$run_as" ]]; then
+    chown "$run_as:$run_as" "$installer" 2>/dev/null || true
+    echo "[init-nix] Running installer as user '$run_as' ($mode_flag)..."
+    if command -v sudo >/dev/null 2>&1; then
+      sudo -u "$run_as" bash -lc "sh '$installer' $mode_flag"
+    else
+      su - "$run_as" -c "sh '$installer' $mode_flag"
+    fi
+  else
+    echo "[init-nix] Running installer as current user ($mode_flag)..."
+    sh "$installer" "$mode_flag"
+  fi
+
+  rm -f "$installer"
+}

scripts/nix/lib/nix_conf_file.sh

@@ -0,0 +1,55 @@
+#!/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"
+}
+
+nixconf_ensure_experimental_features() {
+  local nix_conf want
+  nix_conf="$(nixconf_file_path)"
+  want="experimental-features = nix-command flakes"
+
+  mkdir -p /etc/nix
+
+  if [[ ! -f "${nix_conf}" ]]; then
+    echo "[nix-conf] Creating ${nix_conf} with: ${want}"
+    printf "%s\n" "${want}" >"${nix_conf}"
+    return 0
+  fi
+
+  if grep -qE '^\s*experimental-features\s*=' "${nix_conf}"; then
+    if grep -qE '^\s*experimental-features\s*=.*\bnix-command\b' "${nix_conf}" \
+      && grep -qE '^\s*experimental-features\s*=.*\bflakes\b' "${nix_conf}"; then
+      echo "[nix-conf] experimental-features already correct"
+      return 0
+    fi
+
+    echo "[nix-conf] Extending experimental-features in ${nix_conf}"
+
+    local current
+    current="$(grep -E '^\s*experimental-features\s*=' "${nix_conf}" | head -n1 | cut -d= -f2-)"
+    current="$(echo "${current}" | xargs)" # trim
+
+    # Build a merged feature string without duplicates (simple token set)
+    local merged="nix-command flakes"
+    local token
+    for token in ${current}; do
+      if [[ " ${merged} " != *" ${token} "* ]]; then
+        merged="${merged} ${token}"
+      fi
+    done
+
+    sed -i "s|^\s*experimental-features\s*=.*|experimental-features = ${merged}|" "${nix_conf}"
+    return 0
+  fi
+
+  echo "[nix-conf] Appending to ${nix_conf}: ${want}"
+  printf "\n%s\n" "${want}" >>"${nix_conf}"
+}

scripts/nix/lib/path.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+
+if [[ -n "${PKGMGR_NIX_PATH_SH:-}" ]]; then
+  return 0
+fi
+PKGMGR_NIX_PATH_SH=1
+
+# Ensure Nix binaries are on PATH (additive, never destructive)
+ensure_nix_on_path() {
+  if [[ -x /nix/var/nix/profiles/default/bin/nix ]]; then
+    PATH="/nix/var/nix/profiles/default/bin:$PATH"
+  fi
+  if [[ -x "$HOME/.nix-profile/bin/nix" ]]; then
+    PATH="$HOME/.nix-profile/bin:$PATH"
+  fi
+  if [[ -x /home/nix/.nix-profile/bin/nix ]]; then
+    PATH="/home/nix/.nix-profile/bin:$PATH"
+  fi
+  if [[ -d "$HOME/.local/bin" ]]; then
+    PATH="$HOME/.local/bin:$PATH"
+  fi
+  export PATH
+}
+
+# Resolve a path to a real executable (follows symlinks)
+real_exe() {
+  local p="${1:-}"
+  [[ -z "$p" ]] && return 1
+
+  local r
+  r="$(readlink -f "$p" 2>/dev/null || echo "$p")"
+
+  [[ -x "$r" ]] && { echo "$r"; return 0; }
+  return 1
+}
+
+# Resolve nix binary path robustly (works across distros + Arch /usr/sbin)
+resolve_nix_bin() {
+  local nix_cmd=""
+  nix_cmd="$(command -v nix 2>/dev/null || true)"
+  [[ -n "$nix_cmd" ]] && real_exe "$nix_cmd" && return 0
+
+  # IMPORTANT: prefer system locations before /usr/local to avoid self-symlink traps
+  [[ -x /usr/sbin/nix ]]      && { echo "/usr/sbin/nix"; return 0; } # Arch package can land here
+  [[ -x /usr/bin/nix ]]       && { echo "/usr/bin/nix"; return 0; }
+  [[ -x /bin/nix ]]           && { echo "/bin/nix"; return 0; }
+
+  # /usr/local last, and only if it resolves to a real executable
+  [[ -e /usr/local/bin/nix ]] && real_exe "/usr/local/bin/nix" && return 0
+
+  [[ -x /nix/var/nix/profiles/default/bin/nix ]] && {
+    echo "/nix/var/nix/profiles/default/bin/nix"; return 0;
+  }
+
+  [[ -x "$HOME/.nix-profile/bin/nix" ]] && {
+    echo "$HOME/.nix-profile/bin/nix"; return 0;
+  }
+
+  [[ -x "$HOME/.local/bin/nix" ]] && {
+    echo "$HOME/.local/bin/nix"; return 0;
+  }
+
+  [[ -x /home/nix/.nix-profile/bin/nix ]] && {
+    echo "/home/nix/.nix-profile/bin/nix"; return 0;
+  }
+
+  return 1
+}

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/nix/lib/symlinks.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+
+if [[ -n "${PKGMGR_NIX_SYMLINKS_SH:-}" ]]; then
+  return 0
+fi
+PKGMGR_NIX_SYMLINKS_SH=1
+
+# Requires: real_exe, resolve_nix_bin
+# shellcheck disable=SC2034
+
+# Ensure globally reachable nix symlink(s) (CI / non-login shells) - root only
+ensure_global_nix_symlinks() {
+  local nix_bin="${1:-}"
+
+  [[ -z "$nix_bin" ]] && nix_bin="$(resolve_nix_bin 2>/dev/null || true)"
+
+  if [[ -z "$nix_bin" || ! -x "$nix_bin" ]]; then
+    echo "[init-nix] WARNING: nix binary not found, cannot create global symlink(s)."
+    return 0
+  fi
+
+  # Always link to the real executable to avoid /usr/local/bin/nix -> /usr/local/bin/nix
+  nix_bin="$(real_exe "$nix_bin" 2>/dev/null || echo "$nix_bin")"
+
+  local targets=()
+
+  # Always provide /usr/local/bin/nix for CI shells
+  mkdir -p /usr/local/bin 2>/dev/null || true
+  targets+=("/usr/local/bin/nix")
+
+  # Provide sudo-friendly locations only if they are NOT present (do not override distro paths)
+  if [[ ! -e /usr/bin/nix ]]; then
+    targets+=("/usr/bin/nix")
+  fi
+  if [[ ! -e /usr/sbin/nix ]]; then
+    targets+=("/usr/sbin/nix")
+  fi
+
+  local target current_real
+  for target in "${targets[@]}"; do
+    current_real=""
+    if [[ -e "$target" ]]; then
+      current_real="$(real_exe "$target" 2>/dev/null || true)"
+    fi
+
+    if [[ -n "$current_real" && "$current_real" == "$nix_bin" ]]; then
+      echo "[init-nix] $target already points to: $nix_bin"
+      continue
+    fi
+
+    # If something exists but is not the same (and we promised not to override), skip.
+    if [[ -e "$target" && "$target" != "/usr/local/bin/nix" ]]; then
+      echo "[init-nix] WARNING: $target exists; not overwriting."
+      continue
+    fi
+
+    if ln -sf "$nix_bin" "$target" 2>/dev/null; then
+      echo "[init-nix] Ensured $target -> $nix_bin"
+    else
+      echo "[init-nix] WARNING: Failed to ensure $target symlink."
+    fi
+  done
+}
+
+# Ensure user-level nix symlink (works without root; CI-safe)
+ensure_user_nix_symlink() {
+  local nix_bin="${1:-}"
+
+  [[ -z "$nix_bin" ]] && nix_bin="$(resolve_nix_bin 2>/dev/null || true)"
+
+  if [[ -z "$nix_bin" || ! -x "$nix_bin" ]]; then
+    echo "[init-nix] WARNING: nix binary not found, cannot create user symlink."
+    return 0
+  fi
+
+  nix_bin="$(real_exe "$nix_bin" 2>/dev/null || echo "$nix_bin")"
+
+  mkdir -p "$HOME/.local/bin" 2>/dev/null || true
+  ln -sf "$nix_bin" "$HOME/.local/bin/nix"
+
+  echo "[init-nix] Ensured $HOME/.local/bin/nix -> $nix_bin"
+
+  PATH="$HOME/.local/bin:$PATH"
+  export PATH
+
+  if [[ -w "$HOME/.profile" ]] && ! grep -q 'nix/init.sh' "$HOME/.profile" 2>/dev/null; then
+    cat >>"$HOME/.profile" <<'EOF'
+
+# PATH for nix (added by package-manager nix/init.sh)
+if [ -d "$HOME/.local/bin" ]; then
+  PATH="$HOME/.local/bin:$PATH"
+fi
+EOF
+  fi
+}

scripts/nix/lib/users.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+
+if [[ -n "${PKGMGR_NIX_USERS_SH:-}" ]]; then
+  return 0
+fi
+PKGMGR_NIX_USERS_SH=1
+
+# Ensure Nix build group and users exist (build-users-group = nixbld) - root only
+ensure_nix_build_group() {
+  if ! getent group nixbld >/dev/null 2>&1; then
+    echo "[init-nix] Creating group 'nixbld'..."
+    groupadd -r nixbld
+  fi
+
+  for i in $(seq 1 10); do
+    if ! id "nixbld$i" >/dev/null 2>&1; then
+      echo "[init-nix] Creating build user nixbld$i..."
+      useradd -r -g nixbld -G nixbld -s /usr/sbin/nologin "nixbld$i"
+    fi
+  done
+}
+
+# Container-only helper: /nix ownership + perms for single-user install as 'nix'
+ensure_nix_store_dir_for_container_user() {
+  if [[ ! -d /nix ]]; then
+    echo "[init-nix] Creating /nix with owner nix:nixbld..."
+    mkdir -m 0755 /nix
+    chown nix:nixbld /nix
+    return 0
+  fi
+
+  local current_owner current_group
+  current_owner="$(stat -c '%U' /nix 2>/dev/null || echo '?')"
+  current_group="$(stat -c '%G' /nix 2>/dev/null || echo '?')"
+  if [[ "$current_owner" != "nix" || "$current_group" != "nixbld" ]]; then
+    echo "[init-nix] Fixing /nix ownership from $current_owner:$current_group to nix:nixbld..."
+    chown -R nix:nixbld /nix
+  fi
+}
+
+# Container-only helper: make nix profile executable/traversable for non-root
+ensure_container_profile_perms() {
+  if [[ -d /home/nix ]]; then
+    chmod o+rx /home/nix 2>/dev/null || true
+  fi
+  if [[ -d /home/nix/.nix-profile ]]; then
+    chmod -R o+rx /home/nix/.nix-profile 2>/dev/null || true
+  fi
+}

scripts/pkgmgr-wrapper.sh

@@ -8,19 +8,18 @@ fi
 
 FLAKE_DIR="/usr/lib/package-manager"
 
-# ------------------------------------------------------------
-# Try to ensure that "nix" is on PATH
-# ------------------------------------------------------------
+# ---------------------------------------------------------------------------
+# Try to ensure that "nix" is on PATH (common locations + container user)
+# ---------------------------------------------------------------------------
 if ! command -v nix >/dev/null 2>&1; then
-  # Common locations for Nix installations
   CANDIDATES=(
     "/nix/var/nix/profiles/default/bin/nix"
     "${HOME:-/root}/.nix-profile/bin/nix"
+    "/home/nix/.nix-profile/bin/nix"
   )
 
   for candidate in "${CANDIDATES[@]}"; do
     if [[ -x "$candidate" ]]; then
-      # Prepend the directory of the candidate to PATH
       PATH="$(dirname "$candidate"):${PATH}"
       export PATH
       break
@@ -28,13 +27,22 @@ if ! command -v nix >/dev/null 2>&1; then
   done
 fi
 
-# ------------------------------------------------------------
-# Primary (and only) path: use Nix flake if available
-# ------------------------------------------------------------
+# ---------------------------------------------------------------------------
+# If nix is still missing, try to run nix/init.sh once
+# ---------------------------------------------------------------------------
+if ! command -v nix >/dev/null 2>&1; then
+  if [[ -x "${FLAKE_DIR}/nix/init.sh" ]]; then
+    "${FLAKE_DIR}/nix/init.sh" || true
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# Primary path: use Nix flake if available
+# ---------------------------------------------------------------------------
 if command -v nix >/dev/null 2>&1; then
   exec nix run "${FLAKE_DIR}#pkgmgr" -- "$@"
 fi
 
-echo "[pkgmgr-wrapper] ERROR: 'nix' binary not found on PATH."
+echo "[pkgmgr-wrapper] ERROR: 'nix' binary not found on PATH after init."
 echo "[pkgmgr-wrapper] Nix is required to run pkgmgr (no Python fallback)."
 exit 1

scripts/setup/nix.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+
+# ------------------------------------------------------------
+# 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 install via system python3..."
+python3 -m pkgmgr install
+echo "[setup] Setup finished (Nix mode)."

scripts/setup/venv.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "[setup] Starting setup..."
+
+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'
+
+# ------------------------------------------------------------
+# Normal user mode: dev setup with venv
+# ------------------------------------------------------------
+
+echo "[setup] Running in normal user mode (developer setup)."
+
+echo "[setup] Ensuring global virtualenv root: ${HOME}/.venvs"
+mkdir -p "${HOME}/.venvs"
+
+echo "[setup] Creating/updating virtualenv via helper..."
+PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+cd "${PROJECT_ROOT}"
+
+PIP_EDITABLE="${PKGMGR_PIP_EDITABLE:-1}"
+PIP_EXTRAS="${PKGMGR_PIP_EXTRAS:-}"
+PREFER_NIX="${PKGMGR_PREFER_NIX:-0}"
+
+echo "[venv] Using VENV_DIR=${VENV_DIR}"
+
+if [[ "${PREFER_NIX}" == "1" ]]; then
+  echo "[venv] PKGMGR_PREFER_NIX=1 set."
+  echo "[venv] Hint: Use Nix instead of a venv for reproducible installs:"
+  echo "[venv]   nix develop"
+  echo "[venv]   nix run .#pkgmgr -- --help"
+  exit 2
+fi
+
+echo "[venv] Ensuring virtualenv parent directory exists..."
+mkdir -p "$(dirname "${VENV_DIR}")"
+
+if [[ ! -d "${VENV_DIR}" ]]; then
+  echo "[venv] Creating virtual environment at: ${VENV_DIR}"
+  python3 -m venv "${VENV_DIR}"
+else
+  echo "[venv] Virtual environment already exists at: ${VENV_DIR}"
+fi
+
+echo "[venv] Installing Python tooling into venv..."
+"${VENV_DIR}/bin/python" -m ensurepip --upgrade
+"${VENV_DIR}/bin/pip" install --upgrade pip setuptools wheel
+
+# ---------------------------------------------------------------------------
+# Install dependencies
+# ---------------------------------------------------------------------------
+if [[ -f "pyproject.toml" ]]; then
+  echo "[venv] Detected pyproject.toml. Installing project via pip..."
+
+  target="."
+  if [[ -n "${PIP_EXTRAS}" ]]; then
+    target=".[${PIP_EXTRAS}]"
+  fi
+
+  if [[ "${PIP_EDITABLE}" == "1" ]]; then
+    echo "[venv] pip install -e ${target}"
+    "${VENV_DIR}/bin/pip" install -e "${target}"
+  else
+    echo "[venv] pip install ${target}"
+    "${VENV_DIR}/bin/pip" install "${target}"
+  fi
+else
+  echo "[venv] No pyproject.toml found. Skipping dependency installation."
+fi
+
+echo "[venv] Done."
+
+echo "[setup] Ensuring ~/.bashrc and ~/.zshrc exist..."
+touch "${HOME}/.bashrc" "${HOME}/.zshrc"
+
+echo "[setup] Ensuring venv auto-activation is present in shell rc files..."
+for rc in "${HOME}/.bashrc" "${HOME}/.zshrc"; do
+    if ! grep -qxF "${RC_LINE}" "$rc"; then
+        echo "${RC_LINE}" >> "$rc"
+        echo "[setup] Appended auto-activation to $rc"
+    else
+        echo "[setup] Auto-activation already present in $rc"
+    fi
+done
+
+echo "[setup] Running install via venv Python..."
+"${VENV_DIR}/bin/python" -m pkgmgr install
+
+echo
+echo "[setup] Developer setup complete."
+echo "Restart your shell (or run 'exec bash' or 'exec zsh') to activate the environment."

scripts/test/test-container.sh

@@ -1,41 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-echo "============================================================"
-echo ">>> Running sanity test: verifying test containers start"
-echo "============================================================"
-
-for distro in $DISTROS; do
-    IMAGE="package-manager-test-$distro"
-
-    echo
-    echo "------------------------------------------------------------"
-    echo ">>> Testing container: $IMAGE"
-    echo "------------------------------------------------------------"
-
-    echo "[test-container] Running: docker run --rm --entrypoint pkgmgr $IMAGE --help"
-    echo
-
-    # Run the command and capture the output
-    if OUTPUT=$(docker run --rm \
-            -e PKGMGR_DEV=1 \
-            -v pkgmgr_nix_store:/nix \
-            -v "$(pwd):/src" \
-            -v "pkgmgr_nix_cache:/root/.cache/nix" \
-            "$IMAGE" 2>&1); then
-        echo "$OUTPUT"
-        echo
-        echo "[test-container] SUCCESS: $IMAGE responded to 'pkgmgr --help'"
-
-    else
-        echo "$OUTPUT"
-        echo
-        echo "[test-container] ERROR: $IMAGE failed to run 'pkgmgr --help'"
-        exit 1
-    fi
-done
-
-echo
-echo "============================================================"
-echo ">>> All containers passed the sanity check"
-echo "============================================================"

scripts/test/test-e2e.sh

@@ -1,52 +1,60 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-echo ">>> Running E2E tests in all distros: $DISTROS"
+echo "============================================================"
+echo ">>> Running E2E tests: $PKGMGR_DISTRO"
+echo "============================================================"
 
-for distro in $DISTROS; do
-  echo "============================================================"
-  echo ">>> Running E2E tests: $distro"
-  echo "============================================================"
+docker run --rm \
+  -v "$(pwd):/src" \
+  -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-${PKGMGR_DISTRO}" \
+  bash -lc '
+    set -euo pipefail
 
-  docker run --rm \
-    -v "$(pwd):/src" \
-    -v pkgmgr_nix_store:/nix \
-    -v "pkgmgr_nix_cache:/root/.cache/nix" \
-    -e PKGMGR_DEV=1 \
-    -e TEST_PATTERN="${TEST_PATTERN}" \
-    --workdir /src \
-    --entrypoint bash \
-    "package-manager-test-$distro" \
-    -c '
-      set -e;
+    # Load distro info
+    if [ -f /etc/os-release ]; then
+      . /etc/os-release
+    fi
 
-      if [ -f /etc/os-release ]; then
-        . /etc/os-release;
-      fi;
+    echo "Running tests inside distro: ${ID:-unknown}"
 
-      echo "Running tests inside distro: $ID";
+    # Load Nix environment if available
+    if [ -f "/nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh" ]; then
+      . "/nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh"
+    fi
 
-      # Try to load nix environment
-      if [ -f "/nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh" ]; then
-        . "/nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh";
-      fi
+    if [ -f "$HOME/.nix-profile/etc/profile.d/nix.sh" ]; then
+      . "$HOME/.nix-profile/etc/profile.d/nix.sh"
+    fi
 
-      if [ -f "$HOME/.nix-profile/etc/profile.d/nix.sh" ]; then
-        . "$HOME/.nix-profile/etc/profile.d/nix.sh";
-      fi
+    PATH="/nix/var/nix/profiles/default/bin:$HOME/.nix-profile/bin:$PATH"
 
-      PATH="/nix/var/nix/profiles/default/bin:$HOME/.nix-profile/bin:$PATH";
+    command -v nix >/dev/null || {
+      echo "ERROR: nix not found."
+      exit 1
+    }
 
-      command -v nix >/dev/null || {
-        echo "ERROR: nix not found.";
-        exit 1;
-      }
+    # Mark the mounted repository as safe to avoid Git ownership errors.
+    # Newer Git (e.g. on Ubuntu) complains about the gitdir (/src/.git),
+    # older versions about the worktree (/src). Nix turns "." into the
+    # flake input "git+file:///src", which then uses Git under the hood.
+    if command -v git >/dev/null 2>&1; then
+      # Worktree path
+      git config --global --add safe.directory /src || true
+      # 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
+    fi
 
-      git config --global --add safe.directory /src || true;
-
-      nix develop .#default --no-write-lock-file -c \
-        python3 -m unittest discover \
-          -s /src/tests/e2e \
-          -p "$TEST_PATTERN";
-    '
-done
+    # Run the E2E tests inside the Nix development shell
+    nix develop .#default --no-write-lock-file -c \
+      python3 -m unittest discover \
+        -s /src/tests/e2e \
+        -p "$TEST_PATTERN"
+  '

scripts/test/test-env-nix.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+IMAGE="pkgmgr-${PKGMGR_DISTRO}"
+
+echo "============================================================"
+echo ">>> Running Nix flake-only test in ${PKGMGR_DISTRO} container"
+echo ">>> Image: ${IMAGE}"
+echo "============================================================"
+
+docker run --rm \
+  -v "$(pwd):/src" \
+  -v "pkgmgr_nix_store_${PKGMGR_DISTRO}:/nix" \
+  -v "pkgmgr_nix_cache_${PKGMGR_DISTRO}:/root/.cache/nix" \
+  --workdir /src \
+  -e REINSTALL_PKGMGR=1 \
+  "${IMAGE}" \
+  bash -lc '
+    set -euo pipefail
+
+    if command -v git >/dev/null 2>&1; then
+      git config --global --add safe.directory /src || true
+      git config --global --add safe.directory /src/.git || true
+      git config --global --add safe.directory "*" || true
+    fi
+
+    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}"' (PKGMGR_DISTRO='"${PKGMGR_DISTRO}"')"
+      echo "HINT: Ensure Nix is installed during image build for this distro."
+      exit 1
+    fi
+
+    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"
+    run_with_github_403_retry nix flake show . --no-write-lock-file >/dev/null
+
+    echo ">>> nix build .#default"
+    run_with_github_403_retry nix build .#default --no-link --no-write-lock-file
+
+    echo ">>> nix run .#pkgmgr -- --help"
+    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

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+IMAGE="pkgmgr-$PKGMGR_DISTRO"
+
+echo
+echo "------------------------------------------------------------"
+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"
+echo
+
+# Run the command and capture the output
+if OUTPUT=$(docker run --rm \
+        -e REINSTALL_PKGMGR=1 \
+        -v "pkgmgr_nix_store_${PKGMGR_DISTRO}:/nix" \
+        -v "$(pwd):/src" \
+        -v "pkgmgr_nix_cache_${PKGMGR_DISTRO}:/root/.cache/nix" \
+        "$IMAGE" 2>&1); then
+    echo "$OUTPUT"
+    echo
+    echo "[test-env-virtual] SUCCESS: $IMAGE responded to 'pkgmgr --help'"
+
+else
+    echo "$OUTPUT"
+    echo
+    echo "[test-env-virtual] ERROR: $IMAGE failed to run 'pkgmgr --help'"
+    exit 1
+fi

scripts/test/test-integration.sh

@@ -2,23 +2,22 @@
 set -euo pipefail
 
 echo "============================================================"
-echo ">>> Running INTEGRATION tests in Arch container"
+echo ">>> Running INTEGRATION tests in ${PKGMGR_DISTRO} container"
 echo "============================================================"
 
 docker run --rm \
   -v "$(pwd):/src" \
-  -v pkgmgr_nix_store:/nix \
-  -v "pkgmgr_nix_cache:/root/.cache/nix" \
+  -v "pkgmgr_nix_store_${PKGMGR_DISTRO}:/nix" \
+  -v "pkgmgr_nix_cache_${PKGMGR_DISTRO}:/root/.cache/nix" \
   --workdir /src \
-  -e PKGMGR_DEV=1 \
+  -e REINSTALL_PKGMGR=1 \
   -e TEST_PATTERN="${TEST_PATTERN}" \
-  --entrypoint bash \
-  "package-manager-test-arch" \
-  -c '
+  "pkgmgr-${PKGMGR_DISTRO}" \
+  bash -lc '
     set -e;
     git config --global --add safe.directory /src || true;
     nix develop .#default --no-write-lock-file -c \
-      python -m unittest discover \
+      python3 -m unittest discover \
         -s tests/integration \
         -t /src \
         -p "$TEST_PATTERN";

scripts/test/test-unit.sh

@@ -2,23 +2,22 @@
 set -euo pipefail
 
 echo "============================================================"
-echo ">>> Running UNIT tests in Arch container"
+echo ">>> Running UNIT tests in ${PKGMGR_DISTRO} container"
 echo "============================================================"
 
 docker run --rm \
   -v "$(pwd):/src" \
-  -v "pkgmgr_nix_cache:/root/.cache/nix" \
-  -v pkgmgr_nix_store:/nix \
+  -v "pkgmgr_nix_cache_${PKGMGR_DISTRO}:/root/.cache/nix" \
+  -v "pkgmgr_nix_store_${PKGMGR_DISTRO}:/nix" \
   --workdir /src \
-  -e PKGMGR_DEV=1 \
+  -e REINSTALL_PKGMGR=1 \
   -e TEST_PATTERN="${TEST_PATTERN}" \
-  --entrypoint bash \
-  "package-manager-test-arch" \
-  -c '
+  "pkgmgr-${PKGMGR_DISTRO}" \
+  bash -lc '
     set -e;
     git config --global --add safe.directory /src || true;
     nix develop .#default --no-write-lock-file -c \
-      python -m unittest discover \
+      python3 -m unittest discover \
         -s tests/unit \
         -t /src \
         -p "$TEST_PATTERN";

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

@@ -0,0 +1,36 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+Top-level pkgmgr package.
+
+We deliberately avoid importing heavy submodules (like the CLI)
+on import to keep unit tests fast and to not require optional
+dependencies (like PyYAML) unless they are actually used.
+
+Accessing ``pkgmgr.cli`` will load the CLI module lazily via
+``__getattr__``. This keeps patterns like
+
+    from pkgmgr import cli
+
+working as expected in tests and entry points.
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any
+
+__all__ = ["cli"]
+
+
+def __getattr__(name: str) -> Any:
+  """
+  Lazily expose ``pkgmgr.cli`` as attribute on the top-level package.
+
+  This keeps ``import pkgmgr`` lightweight while still allowing
+  ``from pkgmgr import cli`` in tests and entry points.
+  """
+  if name == "cli":
+      return import_module("pkgmgr.cli")
+  raise AttributeError(f"module 'pkgmgr' has no attribute {name!r}")