Release version 1.4.1

**Replace main.py with module-based entry point and unify CLI execution**
* Remove legacy *main.py* and introduce *pkgmgr* module entry via *python -m pkgmgr* * Add ***main**.py* as the canonical entry point delegating to the CLI * Export *PYTHONPATH=src* in Makefile to ensure reliable imports in dev and CI * Update setup scripts (venv & nix) to use module execution * Refactor all E2E tests to execute the real module entry instead of file paths This aligns pkgmgr with standard Python packaging practices and simplifies testing, setup, and execution across environments. https://chatgpt.com/share/693c9056-716c-800f-b583-fc9245eab2b4
2025-12-12 23:06:15 +01:00 · 2025-12-12 22:59:46 +01:00 · 2025-12-12 22:50:33 +01:00 · 2025-12-12 22:20:07 +01:00 · 2025-12-12 22:17:32 +01:00 · 2025-12-12 22:04:39 +01:00
49 changed files with 1003 additions and 587 deletions
--- a/.github/workflows/publish-containers.yml
+++ b/.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
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,22 @@
+## [1.4.1] - 2025-12-12
+
+* Fixed (#1) 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

 * **Minor release – Stability & CI hardening**
--- a/5
+++ b/5
@@ -30,13 +30,14 @@ export BASE_IMAGE_CENTOS
 # PYthon Unittest Pattern
 TEST_PATTERN	:= test_*.py
 export TEST_PATTERN
+export PYTHONPATH := src

 # ------------------------------------------------------------
 # System install
 # ------------------------------------------------------------
 install:
 	@echo "Building and installing distro-native package-manager for this system..."
-	@bash scripts/installation/main.sh
+	@bash scripts/installation/init.sh

 # ------------------------------------------------------------
 # PKGMGR setup
@@ -45,7 +46,7 @@ install:
 # Default: keep current auto-detection behavior
 setup: setup-nix setup-venv

-# Explicit: developer setup (Python venv + shell RC + main.py install)
+# Explicit: developer setup (Python venv + shell RC + install)
 setup-venv: setup-nix
 	@bash scripts/setup/venv.sh

--- a/README.md
+++ b/README.md
@@ -8,8 +8,9 @@
 [![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)

-**Kevin's Package Manager (PKGMGR)** is a *multi-distro* package manager and workflow orchestrator.
+[**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, …).

@@ -103,50 +104,88 @@ The following diagram gives a full overview of:

 ---

+Perfekt, dann hier die **noch kompaktere und korrekt differenzierte Version**, die **nur** zwischen
+**`make setup`** und **`make setup-venv`** unterscheidet und exakt deinem Verhalten entspricht.
+
+README-ready, ohne Over-Engineering.
+
+---
+
 ## Installation ⚙️

-### 1. Get the latest stable version
+PKGMGR can be installed using `make`.
+The setup mode defines **which runtime layers are prepared**.

-For a stable setup, use the **latest tagged release** (the tag pointed to by
-`latest`):
+---
+
+### Dependency installation (optional)
+
+System dependencies required **before running any *make* commands** are installed via:
+
+```
+scripts/installation/dependencies.sh
+```
+
+The script detects and normalizes the OS and installs the required **system-level dependencies** accordingly.
+
+
+---
+
+### Setup modes
+
+| Command             | Prepares                | Use case              |
+| ------------------- | ----------------------- | --------------------- |
+| **make setup**      | Python venv **and** Nix | Full development & CI |
+| **make setup-venv** | Python venv only        | Local user setup      |
+
+---
+
+### Install & setup

 ```bash
 git clone https://github.com/kevinveenbirkenbach/package-manager.git
 cd package-manager
-
-# Optional but recommended: checkout the latest stable tag
-git fetch --tags
-git checkout "$(git describe --tags --abbrev=0)"
-```
-
-### 2. Install via Make
-
-The project ships with a Makefile that encapsulates the typical installation
-flow. On most systems you only need:
-
-```bash
-# Ensure make, Python and pip are installed via your distro package manager
-# (e.g. pacman -S make python python-pip, apt install make python3-pip, ...)
-
 make install
 ```

-This will:
-
-* create or reuse a Python virtual environment,
-* install PKGMGR (and its Python dependencies) into that environment,
-* expose the `pkgmgr` executable on your PATH (usually via `~/.local/bin`),
-* prepare Nix-based integration where available so PKGMGR can build and manage
-  packages distribution-independently.
-
-For development use, you can also run:
+#### Full setup (venv + Nix)

 ```bash
 make setup
 ```

-which prepares the environment and leaves you with a fully wired development
-workspace (including Nix, tests and scripts).
+Use this for CI, servers, containers and full development workflows.
+
+#### Venv-only setup
+
+```bash
+make setup-venv
+source ~/.venvs/pkgmgr/bin/activate
+```
+
+Use this if you want PKGMGR isolated without Nix integration.
+
+---
+
+## Run without installation (Nix)
+
+Run PKGMGR directly via Nix Flakes.
+
+```bash
+nix run github:kevinveenbirkenbach/package-manager#pkgmgr -- --help
+```
+
+Example:
+
+```bash
+nix run github:kevinveenbirkenbach/package-manager#pkgmgr -- version pkgmgr
+```
+
+Notes:
+
+* full flake URL required
+* `--` separates Nix and PKGMGR arguments
+* can be used alongside any setup mode

 ---

@@ -158,21 +197,9 @@ After installation, the main entry point is:
 pkgmgr --help
 ```

-This prints a list of all available subcommands, for example:
-
-* `pkgmgr list --all` – show all repositories in the config
-* `pkgmgr update --all --clone-mode https` – update every repository
-* `pkgmgr release patch --preview` – simulate a patch release
-* `pkgmgr version --all` – show version information for all repositories
-* `pkgmgr mirror setup --preview --all` – prepare Git mirrors (no changes in preview)
-* `pkgmgr make install --preview pkgmgr` – preview make install for the pkgmgr repo
-
+This prints a list of all available subcommands.
 The help for each command is available via:

-```bash
-pkgmgr <command> --help
-```
-
 ---

 ## License 📄
--- a/flake.nix
+++ b/flake.nix
@@ -36,7 +36,7 @@
        rec {
          pkgmgr = pyPkgs.buildPythonApplication {
            pname   = "package-manager";
-            version = "1.3.0";
+            version = "1.4.1";

            # Use the git repo as source
            src = ./.;
--- a/main.py
+++ b/main.py
@@ -1,14 +0,0 @@
-#!/usr/bin/env python3
-import sys
-from pathlib import Path
-
-# Ensure local src/ overrides installed package
-ROOT = Path(__file__).resolve().parent
-SRC = ROOT / "src"
-if SRC.is_dir():
-    sys.path.insert(0, str(SRC))
-
-from pkgmgr.cli import main
-
-if __name__ == "__main__":
-    main()
--- a/packaging/arch/PKGBUILD
+++ b/packaging/arch/PKGBUILD
@@ -50,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"
--- a/packaging/arch/package-manager.install
+++ b/packaging/arch/package-manager.install
@@ -1,9 +1,9 @@
 post_install() {
-  /usr/lib/package-manager/init-nix.sh || echo ">>> ERROR: /usr/lib/package-manager/init-nix.sh not found or not executable."
+  /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/init-nix.sh || echo ">>> ERROR: /usr/lib/package-manager/init-nix.sh not found or not executable."
+  /usr/lib/package-manager/nix/init.sh || echo ">>> ERROR: /usr/lib/package-manager/nix/init.sh not found or not executable."
 }

 post_remove() {
--- a/packaging/debian/postinst
+++ b/packaging/debian/postinst
@@ -3,7 +3,7 @@ set -e

 case "$1" in
    configure)
-        /usr/lib/package-manager/init-nix.sh || echo ">>> ERROR: /usr/lib/package-manager/init-nix.sh not found or not executable."
+        /usr/lib/package-manager/nix/init.sh || echo ">>> ERROR: /usr/lib/package-manager/nix/init.sh not found or not executable."
        ;;
 esac

--- a/packaging/debian/rules
+++ b/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.
--- a/packaging/fedora/package-manager.spec
+++ b/packaging/fedora/package-manager.spec
@@ -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,7 +62,7 @@ rm -rf \
  %{buildroot}/usr/lib/package-manager/.gitkeep || true

 %post
-/usr/lib/package-manager/init-nix.sh || echo ">>> ERROR: /usr/lib/package-manager/init-nix.sh not found or not executable."
+/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."
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -7,7 +7,7 @@ build-backend = "setuptools.build_meta"

 [project]
 name = "package-manager"
-version = "1.3.0"
+version = "1.4.1"
 description = "Kevin's package-manager tool (pkgmgr)"
 readme = "README.md"
 requires-python = ">=3.9"
--- a/scripts/build/base.sh
+++ b/scripts/build/base.sh
@@ -1,18 +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 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
-      ;;
+    *) echo "ERROR: Unknown distro '$distro'" >&2; exit 1 ;;
  esac
 }
--- a/scripts/build/image.sh
+++ b/scripts/build/image.sh
@@ -1,28 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail

-# Unified docker image builder for all distros.
-#
-# Supports:
-#   --missing     Build only if image does not exist
-#   --no-cache    Disable docker layer cache
-#   --target      Dockerfile target (e.g. virgin|full)
-#   --tag         Override image tag (default: pkgmgr-$distro[-$target])
-#
-# Requires:
-#   - env var: distro (arch|debian|ubuntu|fedora|centos)
-#   - base.sh in same dir
-#
-# Examples:
-#   distro=arch   bash scripts/build/image.sh
-#   distro=arch   bash scripts/build/image.sh --no-cache
-#   distro=arch   bash scripts/build/image.sh --missing
-#   distro=arch   bash scripts/build/image.sh --target virgin
-#   distro=arch   bash scripts/build/image.sh --target virgin --missing
-#   distro=arch   bash scripts/build/image.sh --tag myimg:arch
-
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-# shellcheck source=/dev/null
 source "${SCRIPT_DIR}/base.sh"

 : "${distro:?Environment variable 'distro' must be set (arch|debian|ubuntu|fedora|centos)}"
@@ -30,7 +9,15 @@ source "${SCRIPT_DIR}/base.sh"
 NO_CACHE=0
 MISSING_ONLY=0
 TARGET=""
-IMAGE_TAG="" # derive later unless --tag is provided
+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-${distro}"
@@ -39,14 +26,26 @@ usage() {
  fi

  cat <<EOF
-Usage: distro=<distro> $0 [--missing] [--no-cache] [--target <name>] [--tag <image>]
+Usage: distro=<distro> $0 [options]

-Options:
-  --missing         Build only if the image does not already exist
-  --no-cache        Build with --no-cache
-  --target <name>   Build a specific Dockerfile target (e.g. virgin|full)
-  --tag <image>     Override the output image tag (default: ${default_tag})
-  -h, --help        Show help
+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
 }

@@ -56,18 +55,39 @@ while [[ $# -gt 0 ]]; do
    --missing)  MISSING_ONLY=1; shift ;;
    --target)
      TARGET="${2:-}"
-      if [[ -z "${TARGET}" ]]; then
-        echo "ERROR: --target requires a value (e.g. virgin|full)" >&2
-        exit 2
-      fi
+      [[ -n "${TARGET}" ]] || { echo "ERROR: --target requires a value (e.g. virgin)"; exit 2; }
      shift 2
      ;;
    --tag)
      IMAGE_TAG="${2:-}"
-      if [[ -z "${IMAGE_TAG}" ]]; then
-        echo "ERROR: --tag requires a value" >&2
-        exit 2
-      fi
+      [[ -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 ;;
@@ -79,9 +99,9 @@ while [[ $# -gt 0 ]]; do
  esac
 done

-# Auto-tag: if --tag not provided, derive from distro (+ target suffix)
+# Derive default local tag if not provided
 if [[ -z "${IMAGE_TAG}" ]]; then
-  IMAGE_TAG="pkgmgr-${distro}"
+  IMAGE_TAG="${REPO_PREFIX}-${distro}"
  if [[ -n "${TARGET}" ]]; then
    IMAGE_TAG="${IMAGE_TAG}-${TARGET}"
  fi
@@ -89,22 +109,51 @@ fi

 BASE_IMAGE="$(resolve_base_image "$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: ${IMAGE_TAG}"
+echo "[build] Building image"
 echo "distro     = ${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
@@ -115,6 +164,62 @@ if [[ -n "${TARGET}" ]]; then
  build_args+=(--target "${TARGET}")
 fi

-build_args+=(-t "${IMAGE_TAG}" .)
+compute_publish_tags() {
+  local distro_tag_base="${REGISTRY}/${OWNER}/${REPO_PREFIX}-${distro}"
+  local alias_tag_base=""

-docker build "${build_args[@]}"
+  if [[ -n "${TARGET}" ]]; then
+    distro_tag_base="${distro_tag_base}-${TARGET}"
+  fi
+
+  if [[ "${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
--- a/scripts/build/publish.sh
+++ b/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] distro=${d}"
+  echo "============================================================"
+
+  # virgin
+  distro="${d}" bash "${SCRIPT_DIR}/image.sh" \
+    --publish \
+    --registry "${REGISTRY}" \
+    --owner "${OWNER}" \
+    --version "${VERSION}" \
+    --stable "${IS_STABLE}" \
+    --target virgin
+
+  # full (default target)
+  distro="${d}" bash "${SCRIPT_DIR}/image.sh" \
+    --publish \
+    --registry "${REGISTRY}" \
+    --owner "${OWNER}" \
+    --version "${VERSION}" \
+    --stable "${IS_STABLE}"
+done
+
+echo
+echo "[publish] Done."
--- a/scripts/init-nix.sh
+++ b/scripts/init-nix.sh
@@ -1,385 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-echo "[init-nix] Starting Nix initialization..."
-
-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}"
-
-# ---------------------------------------------------------------------------
-# 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
-}
-
-# ---------------------------------------------------------------------------
-# 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
-}
-
-# ---------------------------------------------------------------------------
-# Ensure globally reachable nix symlink(s) (CI / non-login shells) - root only
-#
-# Key rule:
-# - Never overwrite distro-managed nix locations (Arch may ship nix in /usr/sbin).
-# - But for sudo secure_path (CentOS), /usr/local/bin is often NOT included.
-#   Therefore: also create /usr/bin/nix (and /usr/sbin/nix) ONLY if they do not exist.
-# ---------------------------------------------------------------------------
-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 'init-nix.sh' "$HOME/.profile" 2>/dev/null; then
-    cat >>"$HOME/.profile" <<'EOF'
-
-# PATH for nix (added by package-manager init-nix.sh)
-if [ -d "$HOME/.local/bin" ]; then
-  PATH="$HOME/.local/bin:$PATH"
-fi
-EOF
-  fi
-}
-
-# ---------------------------------------------------------------------------
-# 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
-}
-
-# ---------------------------------------------------------------------------
-# 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"
-}
-
-# ---------------------------------------------------------------------------
-# Main
-# ---------------------------------------------------------------------------
-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
-      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
-
-    if [[ ! -d /nix ]]; then
-      echo "[init-nix] Creating /nix with owner nix:nixbld..."
-      mkdir -m 0755 /nix
-      chown nix:nixbld /nix
-    else
-      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
-    fi
-
-    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
-    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
-
-  # -------------------------------------------------------------------------
-  # 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
-
-  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 "$@"
--- a/scripts/installation/dependencies.sh
+++ b/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}"
--- a/scripts/installation/init.sh
+++ b/scripts/installation/init.sh
--- a/scripts/installation/lib.sh
+++ b/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
-}
--- a/scripts/installation/os_resolver.sh
+++ b/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"
+}
--- a/scripts/installation/package.sh
+++ b/scripts/installation/package.sh
@@ -3,28 +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)"
-
-# Map Manjaro to Arch
-if [[ "${OS_ID}" == "manjaro" ]]; then
-  echo "[package] Mapping OS 'manjaro' → 'arch'"
-  OS_ID="arch"
-fi
+OS_ID="$(osr_get_os_id)"

 echo "[package] Detected OS: ${OS_ID}"

-case "${OS_ID}" in
-  arch|debian|ubuntu|fedora|centos)
-    PKG_SCRIPT="${SCRIPT_DIR}/${OS_ID}/package.sh"
-    ;;
-  *)
-    echo "[package] Unsupported OS: ${OS_ID}"
-    exit 1
-    ;;
-esac
+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}"
--- a/scripts/nix/README.md
+++ b/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/*:
+
+- *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.
+
--- a/scripts/nix/init.sh
+++ b/scripts/nix/init.sh
@@ -0,0 +1,130 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# shellcheck source=lib/config.sh
+# shellcheck source=lib/detect.sh
+# shellcheck source=lib/path.sh
+# shellcheck source=lib/symlinks.sh
+# shellcheck source=lib/users.sh
+# shellcheck source=lib/install.sh
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+source "${SCRIPT_DIR}/lib/config.sh"
+source "${SCRIPT_DIR}/lib/detect.sh"
+source "${SCRIPT_DIR}/lib/path.sh"
+source "${SCRIPT_DIR}/lib/symlinks.sh"
+source "${SCRIPT_DIR}/lib/users.sh"
+source "${SCRIPT_DIR}/lib/install.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
+      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
+
+  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 "$@"
--- a/scripts/nix/lib/config.sh
+++ b/scripts/nix/lib/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}"
--- a/scripts/nix/lib/detect.sh
+++ b/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
+}
--- a/scripts/nix/lib/install.sh
+++ b/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"
+}
--- a/scripts/nix/lib/path.sh
+++ b/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
+}
--- a/scripts/nix/lib/symlinks.sh
+++ b/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
+}
--- a/scripts/nix/lib/users.sh
+++ b/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
+}
--- a/scripts/pkgmgr-wrapper.sh
+++ b/scripts/pkgmgr-wrapper.sh
@@ -28,11 +28,11 @@ if ! command -v nix >/dev/null 2>&1; then
 fi

 # ---------------------------------------------------------------------------
-# If nix is still missing, try to run init-nix.sh once
+# 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}/init-nix.sh" ]]; then
-    "${FLAKE_DIR}/init-nix.sh" || true
+  if [[ -x "${FLAKE_DIR}/nix/init.sh" ]]; then
+    "${FLAKE_DIR}/nix/init.sh" || true
  fi
 fi

--- a/scripts/setup/nix.sh
+++ b/scripts/setup/nix.sh
@@ -1,9 +1,9 @@
 # ------------------------------------------------------------
-# Nix shell mode: do not touch venv, only run main.py install
+# Nix shell mode: do not touch venv, only run install
 # ------------------------------------------------------------

 echo "[setup] Nix mode enabled (NIX_ENABLED=1)."
 echo "[setup] Skipping virtualenv creation and dependency installation."
-echo "[setup] Running main.py install via system python3..."
-python3 main.py install
+echo "[setup] Running install via system python3..."
+python3 -m pkgmgr install
 echo "[setup] Setup finished (Nix mode)."
--- a/scripts/setup/venv.sh
+++ b/scripts/setup/venv.sh
@@ -15,9 +15,6 @@ RC_LINE='if [ -d "${HOME}/.venvs/pkgmgr" ]; then . "${HOME}/.venvs/pkgmgr/bin/ac

 echo "[setup] Running in normal user mode (developer setup)."

-echo "[setup] Ensuring main.py is executable..."
-chmod +x main.py || true
-
 echo "[setup] Ensuring global virtualenv root: ${HOME}/.venvs"
 mkdir -p "${HOME}/.venvs"

@@ -90,8 +87,8 @@ for rc in "${HOME}/.bashrc" "${HOME}/.zshrc"; do
    fi
 done

-echo "[setup] Running main.py install via venv Python..."
-"${VENV_DIR}/bin/python" main.py install
+echo "[setup] Running install via venv Python..."
+"${VENV_DIR}/bin/python" -m pkgmgr install

 echo
 echo "[setup] Developer setup complete."
--- a/src/pkgmgr/main.py
+++ b/src/pkgmgr/main.py
@@ -0,0 +1,5 @@
+#!/usr/bin/env python3
+from pkgmgr.cli import main
+
+if __name__ == "__main__":
+    main()
--- a/src/pkgmgr/cli/init.py
+++ b/src/pkgmgr/cli/init.py
@@ -19,7 +19,7 @@ USER_CONFIG_PATH = os.path.expanduser("~/.config/pkgmgr/config.yaml")
 DESCRIPTION_TEXT = """\
 \033[1;32mPackage Manager 🤖📦\033[0m
 \033[3mKevin's multi-distro package and workflow manager.\033[0m
-  \033[1;34mKevin Veen-Birkenbach\033[0m – \033[4mhttps://www.veen.world/\033[0m
+\033[1;34mKevin Veen-Birkenbach\033[0m – \033[4mhttps://s.veen.world/pkgmgr\033[0m

 Built in \033[1;33mPython\033[0m on top of \033[1;33mNix flakes\033[0m to manage many
 repositories and packaging formats (pyproject.toml, flake.nix,
--- a/tests/e2e/test_branch_commands.py
+++ b/tests/e2e/test_branch_commands.py
@@ -27,7 +27,7 @@ class TestIntegrationBranchCommands(unittest.TestCase):
        try:
            # argv[0] is the program name; the rest are CLI arguments.
            sys.argv = ["pkgmgr"] + list(extra_args)
-            runpy.run_module("main", run_name="__main__")
+            runpy.run_module("pkgmgr", run_name="__main__")
        finally:
            sys.argv = original_argv

--- a/tests/e2e/test_branch_help.py
+++ b/tests/e2e/test_branch_help.py
@@ -24,7 +24,7 @@ def _run_pkgmgr_help(argv_tail: list[str]) -> str:

        try:
            with redirect_stdout(buffer), redirect_stderr(buffer):
-                runpy.run_module("main", run_name="__main__")
+                runpy.run_module("pkgmgr", run_name="__main__")
        except SystemExit as exc:
            code = exc.code if isinstance(exc.code, int) else None
            if code not in (0, None):
--- a/tests/e2e/test_changelog_commands.py
+++ b/tests/e2e/test_changelog_commands.py
@@ -53,7 +53,7 @@ class TestIntegrationChangelogCommands(unittest.TestCase):
            sys.argv = ["pkgmgr", "changelog"] + list(extra_args)

            try:
-                runpy.run_module("main", run_name="__main__")
+                runpy.run_module("pkgmgr", run_name="__main__")
            except SystemExit as exc:
                code = exc.code if isinstance(exc.code, int) else str(exc.code)
                if code != 0:
--- a/tests/e2e/test_clone_all.py
+++ b/tests/e2e/test_clone_all.py
@@ -47,7 +47,7 @@ class TestIntegrationCloneAllHttps(unittest.TestCase):
            try:
                # Execute main.py as if it was called from CLI.
                # This will run the full clone pipeline inside the container.
-                runpy.run_module("main", run_name="__main__")
+                runpy.run_module("pkgmgr", run_name="__main__")
            except SystemExit as exc:
                # Determine the exit code (int or string)
                exit_code = exc.code
--- a/tests/e2e/test_config_commands.py
+++ b/tests/e2e/test_config_commands.py
@@ -34,7 +34,7 @@ def _run_pkgmgr_config(extra_args: list[str]) -> None:
        sys.argv = ["pkgmgr"] + extra_args

        try:
-            runpy.run_module("main", run_name="__main__")
+            runpy.run_module("pkgmgr", run_name="__main__")
        except SystemExit as exc:
            code = exc.code if isinstance(exc.code, int) else str(exc.code)
            if code != 0:
--- a/tests/e2e/test_install_pkgmgr_shallow.py
+++ b/tests/e2e/test_install_pkgmgr_shallow.py
@@ -139,7 +139,7 @@ class TestIntegrationInstalPKGMGRShallow(unittest.TestCase):
            ]

            # Execute installation via main.py
-            runpy.run_module("main", run_name="__main__")
+            runpy.run_module("pkgmgr", run_name="__main__")

            # Debug: interactive shell test
            pkgmgr_help_debug()
--- a/tests/e2e/test_list_commands.py
+++ b/tests/e2e/test_list_commands.py
@@ -27,7 +27,7 @@ class TestIntegrationListCommands(unittest.TestCase):
            sys.argv = ["pkgmgr"] + args

            try:
-                runpy.run_module("main", run_name="__main__")
+                runpy.run_module("pkgmgr", run_name="__main__")
            except SystemExit as exc:
                code = exc.code if isinstance(exc.code, int) else str(exc.code)
                if code != 0:
--- a/tests/e2e/test_make_commands.py
+++ b/tests/e2e/test_make_commands.py
@@ -44,7 +44,7 @@ class TestIntegrationMakeCommands(unittest.TestCase):
            sys.argv = ["pkgmgr"] + extra_args

            try:
-                runpy.run_module("main", run_name="__main__")
+                runpy.run_module("pkgmgr", run_name="__main__")
            except SystemExit as exc:
                code = exc.code if isinstance(exc.code, int) else str(exc.code)
                if code != 0:
--- a/tests/e2e/test_mirror_commands.py
+++ b/tests/e2e/test_mirror_commands.py
@@ -50,7 +50,7 @@ class TestIntegrationMirrorCommands(unittest.TestCase):

            try:
                with redirect_stdout(buffer), redirect_stderr(buffer):
-                    runpy.run_module("main", run_name="__main__")
+                    runpy.run_module("pkgmgr", run_name="__main__")
            except SystemExit as exc:
                code = exc.code if isinstance(exc.code, int) else None
                if code not in (0, None):
--- a/tests/e2e/test_path_commands.py
+++ b/tests/e2e/test_path_commands.py
@@ -50,7 +50,7 @@ class TestPathCommandsE2E(unittest.TestCase):
            try:
                # Capture stdout while running the CLI entry point.
                with redirect_stdout(buffer):
-                    runpy.run_module("main", run_name="__main__")
+                    runpy.run_module("pkgmgr", run_name="__main__")
            except SystemExit as exc:
                # Determine the exit code (int or string)
                exit_code = exc.code
--- a/tests/e2e/test_proxy_commands.py
+++ b/tests/e2e/test_proxy_commands.py
@@ -27,7 +27,7 @@ class TestIntegrationProxyCommands(unittest.TestCase):
            sys.argv = ["pkgmgr"] + args

            try:
-                runpy.run_module("main", run_name="__main__")
+                runpy.run_module("pkgmgr", run_name="__main__")
            except SystemExit as exc:
                code = exc.code if isinstance(exc.code, int) else str(exc.code)
                if code != 0:
--- a/tests/e2e/test_release_commands.py
+++ b/tests/e2e/test_release_commands.py
@@ -44,7 +44,7 @@ class TestIntegrationReleaseCommand(unittest.TestCase):
        try:
            # argv[0] is the program name; the rest are CLI arguments.
            sys.argv = ["pkgmgr"] + list(extra_args)
-            runpy.run_module("main", run_name="__main__")
+            runpy.run_module("pkgmgr", run_name="__main__")
        finally:
            sys.argv = original_argv

@@ -152,7 +152,7 @@ class TestIntegrationReleaseCommand(unittest.TestCase):
            # argparse will call sys.exit(), so we expect a SystemExit here.
            with contextlib.redirect_stdout(buf), contextlib.redirect_stderr(buf):
                with self.assertRaises(SystemExit) as cm:
-                    runpy.run_module("main", run_name="__main__")
+                    runpy.run_module("pkgmgr", run_name="__main__")
        finally:
            sys.argv = original_argv

--- a/tests/e2e/test_tools_commands.py
+++ b/tests/e2e/test_tools_commands.py
@@ -55,7 +55,7 @@ class TestIntegrationToolsCommands(unittest.TestCase):
            sys.argv = ["pkgmgr"] + extra_args

            try:
-                runpy.run_module("main", run_name="__main__")
+                runpy.run_module("pkgmgr", run_name="__main__")
            except SystemExit as exc:
                code = exc.code if isinstance(exc.code, int) else str(exc.code)
                if code != 0:
--- a/tests/e2e/test_tools_help.py
+++ b/tests/e2e/test_tools_help.py
@@ -18,14 +18,6 @@ import sys
 import unittest
 from typing import List

-
-# Resolve project root (the repo where main.py lives, e.g. /src)
-PROJECT_ROOT = os.path.abspath(
-    os.path.join(os.path.dirname(__file__), "..", "..")
-)
-MAIN_PATH = os.path.join(PROJECT_ROOT, "main.py")
-
-
 def _run_main(argv: List[str]) -> None:
    """
    Helper to run main.py with the given argv.
@@ -40,7 +32,7 @@ def _run_main(argv: List[str]) -> None:
    try:
        sys.argv = ["pkgmgr"] + argv
        try:
-            runpy.run_path(MAIN_PATH, run_name="__main__")
+            runpy.run_module("pkgmgr", run_name="__main__")
        except SystemExit as exc:  # argparse uses this for --help
            # SystemExit.code can be int, str or None; for our purposes:
            code = exc.code
--- a/tests/e2e/test_version_commands.py
+++ b/tests/e2e/test_version_commands.py
@@ -130,7 +130,7 @@ class TestIntegrationVersionCommands(unittest.TestCase):
            sys.argv = ["pkgmgr", "version"] + extra_args

            try:
-                runpy.run_module("main", run_name="__main__")
+                runpy.run_module("pkgmgr", run_name="__main__")
            except SystemExit as exc:
                code = exc.code if isinstance(exc.code, int) else str(exc.code)
                if code != 0:
Author	SHA1	Message	Date
Kevin Veen-Birkenbach	103f49c8f6	Release version 1.4.1 Some checks failed Mark stable commit / test-unit (push) Has been cancelled Details Mark stable commit / test-integration (push) Has been cancelled Details Mark stable commit / test-env-virtual (push) Has been cancelled Details Mark stable commit / test-env-nix (push) Has been cancelled Details Mark stable commit / test-e2e (push) Has been cancelled Details Mark stable commit / test-virgin-user (push) Has been cancelled Details Mark stable commit / test-virgin-root (push) Has been cancelled Details Mark stable commit / mark-stable (push) Has been cancelled Details	2025-12-12 23:06:15 +01:00
Kevin Veen-Birkenbach	f5d428950e	Replace main.py with module-based entry point and unify CLI execution Some checks failed Mark stable commit / test-unit (push) Has been cancelled Details Mark stable commit / test-integration (push) Has been cancelled Details Mark stable commit / test-env-virtual (push) Has been cancelled Details Mark stable commit / test-env-nix (push) Has been cancelled Details Mark stable commit / test-e2e (push) Has been cancelled Details Mark stable commit / test-virgin-user (push) Has been cancelled Details Mark stable commit / test-virgin-root (push) Has been cancelled Details Mark stable commit / mark-stable (push) Has been cancelled Details * Remove legacy main.py and introduce pkgmgr module entry via python -m pkgmgr * Add *main.py* as the canonical entry point delegating to the CLI * Export PYTHONPATH=src in Makefile to ensure reliable imports in dev and CI * Update setup scripts (venv & nix) to use module execution * Refactor all E2E tests to execute the real module entry instead of file paths This aligns pkgmgr with standard Python packaging practices and simplifies testing, setup, and execution across environments. https://chatgpt.com/share/693c9056-716c-800f-b583-fc9245eab2b4	2025-12-12 22:59:46 +01:00
Kevin Veen-Birkenbach	b40787ffc5	ci: publish GHCR images after successful mark-stable workflow Some checks failed Mark stable commit / test-unit (push) Has been cancelled Details Mark stable commit / test-integration (push) Has been cancelled Details Mark stable commit / test-env-virtual (push) Has been cancelled Details Mark stable commit / test-env-nix (push) Has been cancelled Details Mark stable commit / test-e2e (push) Has been cancelled Details Mark stable commit / test-virgin-user (push) Has been cancelled Details Mark stable commit / test-virgin-root (push) Has been cancelled Details Mark stable commit / mark-stable (push) Has been cancelled Details Trigger container publishing via workflow_run on "Mark stable commit", gate on success, checkout the workflow_run head SHA, force-refresh tags, and derive version from the v* tag pointing at the tested commit to correctly detect and publish stable images. https://chatgpt.com/share/693c836b-0b00-800f-9536-9e273abd0fb5	2025-12-12 22:50:33 +01:00
Kevin Veen-Birkenbach	0482a7f88d	Release version 1.4.0 Some checks failed Mark stable commit / test-unit (push) Has been cancelled Details Mark stable commit / test-integration (push) Has been cancelled Details Mark stable commit / test-env-virtual (push) Has been cancelled Details Mark stable commit / test-env-nix (push) Has been cancelled Details Mark stable commit / test-e2e (push) Has been cancelled Details Mark stable commit / test-virgin-user (push) Has been cancelled Details Mark stable commit / test-virgin-root (push) Has been cancelled Details Mark stable commit / mark-stable (push) Has been cancelled Details Publish container images (GHCR) / publish (push) Has been cancelled Details	2025-12-12 22:20:07 +01:00
Kevin Veen-Birkenbach	8c127cc45a	ci: fix container publish workflow to run on version tag pushes Switch publish-containers workflow from workflow_run to direct v* tag triggers, remove obsolete workflow_run logic, simplify version detection via GITHUB_REF_NAME, and keep stable-tag detection aligned with the stable ref. https://chatgpt.com/share/693c836b-0b00-800f-9536-9e273abd0fb5	2025-12-12 22:17:32 +01:00
Kevin Veen-Birkenbach	2761e829cb	ci: add GHCR container publish pipeline with semantic tags Some checks failed Mark stable commit / test-unit (push) Has been cancelled Details Mark stable commit / test-integration (push) Has been cancelled Details Mark stable commit / test-env-virtual (push) Has been cancelled Details Mark stable commit / test-env-nix (push) Has been cancelled Details Mark stable commit / test-e2e (push) Has been cancelled Details Mark stable commit / test-virgin-user (push) Has been cancelled Details Mark stable commit / test-virgin-root (push) Has been cancelled Details Mark stable commit / mark-stable (push) Has been cancelled Details Introduce a dedicated publish-containers workflow triggered after stable releases. Unify container build and publish logic via scripts, add buildx-based multi-tag publishing, default base image resolution, and Arch alias tags for latest/version/stable. https://chatgpt.com/share/693c836b-0b00-800f-9536-9e273abd0fb5	2025-12-12 22:04:39 +01:00
Kevin Veen-Birkenbach	d0c01b6955	Updated dependencies instructions Some checks failed Mark stable commit / test-unit (push) Has been cancelled Details Mark stable commit / test-integration (push) Has been cancelled Details Mark stable commit / test-env-virtual (push) Has been cancelled Details Mark stable commit / test-env-nix (push) Has been cancelled Details Mark stable commit / test-e2e (push) Has been cancelled Details Mark stable commit / test-virgin-user (push) Has been cancelled Details Mark stable commit / test-virgin-root (push) Has been cancelled Details Mark stable commit / mark-stable (push) Has been cancelled Details	2025-12-12 21:37:50 +01:00
Kevin Veen-Birkenbach	b2421c9b84	Refactor OS detection and normalize Manjaro to Arch Some checks failed Mark stable commit / test-unit (push) Has been cancelled Details Mark stable commit / test-integration (push) Has been cancelled Details Mark stable commit / test-env-virtual (push) Has been cancelled Details Mark stable commit / test-env-nix (push) Has been cancelled Details Mark stable commit / test-e2e (push) Has been cancelled Details Mark stable commit / test-virgin-user (push) Has been cancelled Details Mark stable commit / test-virgin-root (push) Has been cancelled Details Mark stable commit / mark-stable (push) Has been cancelled Details * Centralize OS detection and normalization in a dedicated resolver module * Treat Manjaro consistently as Arch across dependencies and package install * Remove duplicated OS logic and legacy lib.sh * Rename installation entrypoint to init.sh and update Makefile accordingly https://chatgpt.com/share/693c7b50-3be0-800f-8aeb-daf3ee929ea3	2025-12-12 21:30:03 +01:00
Kevin Veen-Birkenbach	f950bb493c	Release version 1.3.1 Some checks failed Mark stable commit / test-unit (push) Has been cancelled Details Mark stable commit / test-integration (push) Has been cancelled Details Mark stable commit / test-env-virtual (push) Has been cancelled Details Mark stable commit / test-env-nix (push) Has been cancelled Details Mark stable commit / test-e2e (push) Has been cancelled Details Mark stable commit / test-virgin-user (push) Has been cancelled Details Mark stable commit / test-virgin-root (push) Has been cancelled Details Mark stable commit / mark-stable (push) Has been cancelled Details	2025-12-12 21:16:27 +01:00
Kevin Veen-Birkenbach	fb0b81954d	Fix Nix bootstrap installation by shipping init script and libraries together Some checks failed Mark stable commit / test-unit (push) Has been cancelled Details Mark stable commit / test-integration (push) Has been cancelled Details Mark stable commit / test-env-virtual (push) Has been cancelled Details Mark stable commit / test-env-nix (push) Has been cancelled Details Mark stable commit / test-e2e (push) Has been cancelled Details Mark stable commit / test-virgin-user (push) Has been cancelled Details Mark stable commit / test-virgin-root (push) Has been cancelled Details Mark stable commit / mark-stable (push) Has been cancelled Details * Install the complete Nix bootstrap (init.sh and lib/) into /usr/lib/package-manager/nix/ for Arch, Debian, and Fedora * Align packaging paths with the expectations of the modularized nix/init.sh * Prevent runtime failures caused by missing sourced library scripts https://chatgpt.com/share/693c7159-b340-800f-929e-2515eeb0dd03	2025-12-12 21:02:26 +01:00
Kevin Veen-Birkenbach	b9b4c3fa59	Refactor Nix init into modular scripts and update packaging paths Some checks failed Mark stable commit / test-unit (push) Has been cancelled Details Mark stable commit / test-integration (push) Has been cancelled Details Mark stable commit / test-env-virtual (push) Has been cancelled Details Mark stable commit / test-env-nix (push) Has been cancelled Details Mark stable commit / test-e2e (push) Has been cancelled Details Mark stable commit / test-virgin-user (push) Has been cancelled Details Mark stable commit / test-virgin-root (push) Has been cancelled Details Mark stable commit / mark-stable (push) Has been cancelled Details * Move the Nix bootstrap from scripts/init-nix.sh to scripts/nix/init.sh with split-out helpers in scripts/nix/lib/ * Update Arch/Debian/Fedora packaging hooks to call /usr/lib/package-manager/nix/init.sh * Keep bootstrap behavior the same while improving maintainability and reuse https://chatgpt.com/share/693c7159-b340-800f-929e-2515eeb0dd03	2025-12-12 20:47:31 +01:00