Release version 1.6.1

- Add TYPE_CHECKING imports for RepoContext and CommandRunner to avoid runtime deps
- Fix Ruff F821 undefined-name errors in nix installer modules
- Refactor legacy NixFlakeInstaller unit tests to mock subprocess.run directly
- Remove obsolete run_cmd_mock usage and assert install calls via subprocess calls
- Ensure tests run without realtime waits or external nix dependencies

https://chatgpt.com/share/693e925d-a79c-800f-b0b6-92b8ba260b11

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

@@ -46,8 +46,6 @@ jobs:
 
               . "$HOME/.venvs/pkgmgr/bin/activate"
 
-              export NIX_CONFIG="experimental-features = nix-command flakes"
-
               pkgmgr update pkgmgr --clone-mode shallow --no-verification
               pkgmgr version pkgmgr
 

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

@@ -59,7 +59,6 @@ jobs:
                 pkgmgr version pkgmgr
 
                 export NIX_REMOTE=local
-                export NIX_CONFIG=\"experimental-features = nix-command flakes\"
                 nix run /src#pkgmgr -- version pkgmgr
               "
             '

CHANGELOG.md

@@ -1,3 +1,28 @@
+## [1.6.1] - 2025-12-14
+
+* * Added automatic retry handling for GitHub 403 / rate-limit errors during Nix flake installs (Fibonacci backoff with jitter).
+
+
+## [1.6.0] - 2025-12-14
+
+* *** Changed ***
+- Unified update handling via a single top-level `pkgmgr update` command, removing ambiguous update paths.
+- Improved update reliability by routing all update logic through a central UpdateManager.
+- Renamed system update flag from `--system-update` to `--system` for clarity and consistency.
+- Made mirror handling explicit and safer by separating setup, check, and provision responsibilities.
+- Improved credential resolution for remote providers (environment → keyring → interactive).
+
+*** Added ***
+- Optional system updates via `pkgmgr update --system` (Arch, Debian/Ubuntu, Fedora/RHEL).
+- `pkgmgr install --update` to force re-running installers and refresh existing installations.
+- Remote repository provisioning for mirrors on supported providers.
+- Extended end-to-end test coverage for update and mirror workflows.
+
+*** Fixed ***
+- Resolved “Unknown repos command: update” errors after CLI refactoring.
+- Improved Nix update stability and reduced CI failures caused by transient rate limits.
+
+
 ## [1.5.0] - 2025-12-13
 
 * - Commands now show live output while running, making long operations easier to follow

Dockerfile

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

flake.nix

@@ -32,7 +32,7 @@
         rec {
           pkgmgr = pyPkgs.buildPythonApplication {
             pname   = "package-manager";
-            version = "1.5.0";
+            version = "1.6.1";
 
             # Use the git repo as source
             src = ./.;

packaging/arch/PKGBUILD

@@ -47,7 +47,7 @@ package() {
   cd "$srcdir/$_srcdir_name"
 
   # Install the wrapper into /usr/bin
-  install -Dm0755 "scripts/pkgmgr-wrapper.sh" \
+  install -Dm0755 "scripts/launcher.sh" \
     "$pkgdir/usr/bin/pkgmgr"
 
   # Install Nix bootstrap (init + lib)

packaging/debian/rules

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

packaging/fedora/package-manager.spec

@@ -42,7 +42,7 @@ install -d %{buildroot}/usr/lib/package-manager
 cp -a . %{buildroot}/usr/lib/package-manager/
 
 # Wrapper
-install -m0755 scripts/pkgmgr-wrapper.sh %{buildroot}%{_bindir}/pkgmgr
+install -m0755 scripts/launcher.sh %{buildroot}%{_bindir}/pkgmgr
 
 # Nix bootstrap (init + lib)
 install -d %{buildroot}/usr/lib/package-manager/nix

pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "package-manager"
-version = "1.5.0"
+version = "1.6.1"
 description = "Kevin's package-manager tool (pkgmgr)"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -23,12 +23,12 @@ dependencies = [
 ]
 
 [project.urls]
-Homepage = "https://github.com/kevinveenbirkenbach/package-manager"
+Homepage = "https://s.veen.world/pkgmgr"
 Source   = "https://github.com/kevinveenbirkenbach/package-manager"
 
 [project.optional-dependencies]
+keyring = ["keyring>=24.0.0"]
 dev = [
-  "pytest",
   "mypy"
 ]
 

scripts/launcher.sh

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

scripts/nix/lib/nix_conf_file.sh

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

src/pkgmgr/actions/install/__init__.py

@@ -28,7 +28,7 @@ from pkgmgr.actions.install.installers.os_packages import (
     DebianControlInstaller,
     RpmSpecInstaller,
 )
-from pkgmgr.actions.install.installers.nix_flake import (
+from pkgmgr.actions.install.installers.nix import (
     NixFlakeInstaller,
 )
 from pkgmgr.actions.install.installers.python import PythonInstaller

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

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

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

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

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

@@ -0,0 +1,168 @@
+# src/pkgmgr/actions/install/installers/nix/installer.py
+from __future__ import annotations
+
+import os
+import shutil
+from typing import List, Tuple, TYPE_CHECKING
+
+from pkgmgr.actions.install.installers.base import BaseInstaller
+
+from .profile import NixProfileInspector
+from .retry import GitHubRateLimitRetry, RetryPolicy
+from .runner import CommandRunner
+
+if TYPE_CHECKING:
+    from pkgmgr.actions.install.context import RepoContext
+
+class NixFlakeInstaller(BaseInstaller):
+    layer = "nix"
+    FLAKE_FILE = "flake.nix"
+
+    def __init__(self, policy: RetryPolicy | None = None) -> None:
+        self._runner = CommandRunner()
+        self._retry = GitHubRateLimitRetry(policy=policy)
+        self._profile = NixProfileInspector()
+
+    # ------------------------------------------------------------------ #
+    # Compatibility: supports()
+    # ------------------------------------------------------------------ #
+
+    def supports(self, ctx: "RepoContext") -> bool:
+        if os.environ.get("PKGMGR_DISABLE_NIX_FLAKE_INSTALLER") == "1":
+            if not ctx.quiet:
+                print("[INFO] PKGMGR_DISABLE_NIX_FLAKE_INSTALLER=1 – skipping NixFlakeInstaller.")
+            return False
+
+        if shutil.which("nix") is None:
+            return False
+
+        return os.path.exists(os.path.join(ctx.repo_dir, self.FLAKE_FILE))
+
+    # ------------------------------------------------------------------ #
+    # Compatibility: output selection
+    # ------------------------------------------------------------------ #
+
+    def _profile_outputs(self, ctx: "RepoContext") -> List[Tuple[str, bool]]:
+        # (output_name, allow_failure)
+        if ctx.identifier in {"pkgmgr", "package-manager"}:
+            return [("pkgmgr", False), ("default", True)]
+        return [("default", False)]
+
+    # ------------------------------------------------------------------ #
+    # Compatibility: run()
+    # ------------------------------------------------------------------ #
+
+    def run(self, ctx: "RepoContext") -> None:
+        if not self.supports(ctx):
+            return
+
+        outputs = self._profile_outputs(ctx)
+
+        if not ctx.quiet:
+            print(
+                "[nix] flake detected in "
+                f"{ctx.identifier}, ensuring outputs: "
+                + ", ".join(name for name, _ in outputs)
+            )
+
+        for output, allow_failure in outputs:
+            if ctx.force_update:
+                self._force_upgrade_output(ctx, output, allow_failure)
+            else:
+                self._install_only(ctx, output, allow_failure)
+
+    # ------------------------------------------------------------------ #
+    # Core logic (unchanged semantics)
+    # ------------------------------------------------------------------ #
+
+    def _installable(self, ctx: "RepoContext", output: str) -> str:
+        return f"{ctx.repo_dir}#{output}"
+
+    def _install_only(self, ctx: "RepoContext", output: str, allow_failure: bool) -> None:
+        install_cmd = f"nix profile install {self._installable(ctx, output)}"
+
+        if not ctx.quiet:
+            print(f"[nix] install: {install_cmd}")
+
+        res = self._retry.run_with_retry(ctx, self._runner, install_cmd)
+
+        if res.returncode == 0:
+            if not ctx.quiet:
+                print(f"[nix] output '{output}' successfully installed.")
+            return
+
+        if not ctx.quiet:
+            print(
+                f"[nix] install failed for '{output}' (exit {res.returncode}), "
+                "trying index-based upgrade/remove+install..."
+            )
+
+        indices = self._profile.find_installed_indices_for_output(ctx, self._runner, output)
+
+        upgraded = False
+        for idx in indices:
+            if self._upgrade_index(ctx, idx):
+                upgraded = True
+                if not ctx.quiet:
+                    print(f"[nix] output '{output}' successfully upgraded (index {idx}).")
+
+        if upgraded:
+            return
+
+        if indices and not ctx.quiet:
+            print(f"[nix] upgrade failed; removing indices {indices} and reinstalling '{output}'.")
+
+        for idx in indices:
+            self._remove_index(ctx, idx)
+
+        final = self._runner.run(ctx, install_cmd, allow_failure=True)
+        if final.returncode == 0:
+            if not ctx.quiet:
+                print(f"[nix] output '{output}' successfully re-installed.")
+            return
+
+        print(f"[ERROR] Failed to install Nix flake output '{output}' (exit {final.returncode})")
+
+        if not allow_failure:
+            raise SystemExit(final.returncode)
+
+        print(f"[WARNING] Continuing despite failure of optional output '{output}'.")
+
+    # ------------------------------------------------------------------ #
+    # force_update path (unchanged semantics)
+    # ------------------------------------------------------------------ #
+
+    def _force_upgrade_output(self, ctx: "RepoContext", output: str, allow_failure: bool) -> None:
+        indices = self._profile.find_installed_indices_for_output(ctx, self._runner, output)
+
+        upgraded_any = False
+        for idx in indices:
+            if self._upgrade_index(ctx, idx):
+                upgraded_any = True
+                if not ctx.quiet:
+                    print(f"[nix] output '{output}' successfully upgraded (index {idx}).")
+
+        if upgraded_any:
+            print(f"[nix] output '{output}' successfully upgraded.")
+            return
+
+        if indices and not ctx.quiet:
+            print(f"[nix] upgrade failed; removing indices {indices} and reinstalling '{output}'.")
+
+        for idx in indices:
+            self._remove_index(ctx, idx)
+
+        self._install_only(ctx, output, allow_failure)
+
+        print(f"[nix] output '{output}' successfully upgraded.")
+
+    # ------------------------------------------------------------------ #
+    # Helpers
+    # ------------------------------------------------------------------ #
+
+    def _upgrade_index(self, ctx: "RepoContext", idx: int) -> bool:
+        res = self._runner.run(ctx, f"nix profile upgrade --refresh {idx}", allow_failure=True)
+        return res.returncode == 0
+
+    def _remove_index(self, ctx: "RepoContext", idx: int) -> None:
+        self._runner.run(ctx, f"nix profile remove {idx}", allow_failure=True)

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

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import json
+from typing import Any, List, TYPE_CHECKING
+
+
+if TYPE_CHECKING:
+    from pkgmgr.actions.install.context import RepoContext
+    from .runner import CommandRunner
+ 
+class NixProfileInspector:
+    """
+    Reads and interprets `nix profile list --json` and provides helpers for
+    finding indices matching a given output name.
+    """
+
+    def find_installed_indices_for_output(self, ctx: "RepoContext", runner: "CommandRunner", output: str) -> List[int]:
+        res = runner.run(ctx, "nix profile list --json", allow_failure=True)
+        if res.returncode != 0:
+            return []
+
+        try:
+            data = json.loads(res.stdout or "{}")
+        except json.JSONDecodeError:
+            return []
+
+        indices: List[int] = []
+
+        elements = data.get("elements")
+        if isinstance(elements, dict):
+            for idx_str, elem in elements.items():
+                try:
+                    idx = int(idx_str)
+                except (TypeError, ValueError):
+                    continue
+                if self._element_matches_output(elem, output):
+                    indices.append(idx)
+            return sorted(indices)
+
+        if isinstance(elements, list):
+            for elem in elements:
+                idx = elem.get("index") if isinstance(elem, dict) else None
+                if isinstance(idx, int) and self._element_matches_output(elem, output):
+                    indices.append(idx)
+            return sorted(indices)
+
+        return []
+
+    @staticmethod
+    def element_matches_output(elem: Any, output: str) -> bool:
+        return NixProfileInspector._element_matches_output(elem, output)
+
+    @staticmethod
+    def _element_matches_output(elem: Any, output: str) -> bool:
+        out = (output or "").strip()
+        if not out or not isinstance(elem, dict):
+            return False
+
+        candidates: List[str] = []
+        for k in ("attrPath", "originalUrl", "url", "storePath", "name"):
+            v = elem.get(k)
+            if isinstance(v, str) and v:
+                candidates.append(v)
+
+        for c in candidates:
+            if c == out:
+                return True
+            if f"#{out}" in c:
+                return True
+
+        return False

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

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

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

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

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

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

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

@@ -1,238 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-
-from __future__ import annotations
-
-import json
-import os
-import shutil
-import subprocess
-from typing import TYPE_CHECKING, List, Tuple
-
-from pkgmgr.actions.install.installers.base import BaseInstaller
-from pkgmgr.core.command.run import run_command
-
-if TYPE_CHECKING:
-    from pkgmgr.actions.install.context import RepoContext
-
-
-class NixFlakeInstaller(BaseInstaller):
-    layer = "nix"
-    FLAKE_FILE = "flake.nix"
-
-    def supports(self, ctx: "RepoContext") -> bool:
-        if os.environ.get("PKGMGR_DISABLE_NIX_FLAKE_INSTALLER") == "1":
-            if not ctx.quiet:
-                print("[INFO] PKGMGR_DISABLE_NIX_FLAKE_INSTALLER=1 – skipping NixFlakeInstaller.")
-            return False
-
-        if shutil.which("nix") is None:
-            return False
-
-        return os.path.exists(os.path.join(ctx.repo_dir, self.FLAKE_FILE))
-
-    def _profile_outputs(self, ctx: "RepoContext") -> List[Tuple[str, bool]]:
-        # (output_name, allow_failure)
-        if ctx.identifier in {"pkgmgr", "package-manager"}:
-            return [("pkgmgr", False), ("default", True)]
-        return [("default", False)]
-
-    def _installable(self, ctx: "RepoContext", output: str) -> str:
-        return f"{ctx.repo_dir}#{output}"
-
-    def _run(self, ctx: "RepoContext", cmd: str, allow_failure: bool = True):
-        return run_command(
-            cmd,
-            cwd=ctx.repo_dir,
-            preview=ctx.preview,
-            allow_failure=allow_failure,
-        )
-
-    def _profile_list_json(self, ctx: "RepoContext") -> dict:
-        """
-        Read current Nix profile entries as JSON (best-effort).
-
-        NOTE: Nix versions differ:
-          - Newer: {"elements": [ { "index": 0, "attrPath": "...", ... }, ... ]}
-          - Older: {"elements": [ "nixpkgs#hello", ... ]}   (strings)
-
-        We return {} on failure or in preview mode.
-        """
-        if ctx.preview:
-            return {}
-
-        proc = subprocess.run(
-            ["nix", "profile", "list", "--json"],
-            check=False,
-            stdout=subprocess.PIPE,
-            stderr=subprocess.STDOUT,
-            text=True,
-            env=os.environ.copy(),
-        )
-        if proc.returncode != 0:
-            return {}
-
-        try:
-            return json.loads(proc.stdout or "{}")
-        except json.JSONDecodeError:
-            return {}
-
-    def _find_installed_indices_for_output(self, ctx: "RepoContext", output: str) -> List[int]:
-        """
-        Find installed profile indices for a given output.
-
-        Works across Nix JSON variants:
-          - If elements are dicts: we can extract indices.
-          - If elements are strings: we cannot extract indices -> return [].
-        """
-        data = self._profile_list_json(ctx)
-        elements = data.get("elements", []) or []
-
-        matches: List[int] = []
-
-        for el in elements:
-            # Legacy JSON format: plain strings -> no index information
-            if not isinstance(el, dict):
-                continue
-
-            idx = el.get("index")
-            if idx is None:
-                continue
-
-            attr_path = el.get("attrPath") or el.get("attr_path") or ""
-            pname = el.get("pname") or ""
-            name = el.get("name") or ""
-
-            if attr_path == output:
-                matches.append(int(idx))
-                continue
-
-            if pname == output or name == output:
-                matches.append(int(idx))
-                continue
-
-            if isinstance(attr_path, str) and attr_path.endswith(f".{output}"):
-                matches.append(int(idx))
-                continue
-
-        return matches
-
-    def _upgrade_index(self, ctx: "RepoContext", index: int) -> bool:
-        cmd = f"nix profile upgrade --refresh {index}"
-        if not ctx.quiet:
-            print(f"[nix] upgrade: {cmd}")
-        res = self._run(ctx, cmd, allow_failure=True)
-        return res.returncode == 0
-
-    def _remove_index(self, ctx: "RepoContext", index: int) -> None:
-        cmd = f"nix profile remove {index}"
-        if not ctx.quiet:
-            print(f"[nix] remove: {cmd}")
-        self._run(ctx, cmd, allow_failure=True)
-
-    def _install_only(self, ctx: "RepoContext", output: str, allow_failure: bool) -> None:
-        """
-        Install output; on failure, try index-based upgrade/remove+install if possible.
-        """
-        installable = self._installable(ctx, output)
-        install_cmd = f"nix profile install {installable}"
-
-        if not ctx.quiet:
-            print(f"[nix] install: {install_cmd}")
-
-        res = self._run(ctx, install_cmd, allow_failure=True)
-        if res.returncode == 0:
-            if not ctx.quiet:
-                print(f"[nix] output '{output}' successfully installed.")
-            return
-
-        if not ctx.quiet:
-            print(
-                f"[nix] install failed for '{output}' (exit {res.returncode}), "
-                "trying index-based upgrade/remove+install..."
-            )
-
-        indices = self._find_installed_indices_for_output(ctx, output)
-
-        # 1) Try upgrading existing indices (only possible on newer JSON format)
-        upgraded = False
-        for idx in indices:
-            if self._upgrade_index(ctx, idx):
-                upgraded = True
-                if not ctx.quiet:
-                    print(f"[nix] output '{output}' successfully upgraded (index {idx}).")
-
-        if upgraded:
-            return
-
-        # 2) Remove matching indices and retry install
-        if indices and not ctx.quiet:
-            print(f"[nix] upgrade failed; removing indices {indices} and reinstalling '{output}'.")
-
-        for idx in indices:
-            self._remove_index(ctx, idx)
-
-        final = self._run(ctx, install_cmd, allow_failure=True)
-        if final.returncode == 0:
-            if not ctx.quiet:
-                print(f"[nix] output '{output}' successfully re-installed.")
-            return
-
-        msg = f"[ERROR] Failed to install Nix flake output '{output}' (exit {final.returncode})"
-        print(msg)
-
-        if not allow_failure:
-            raise SystemExit(final.returncode)
-
-        print(f"[WARNING] Continuing despite failure of optional output '{output}'.")
-
-    def _force_upgrade_output(self, ctx: "RepoContext", output: str, allow_failure: bool) -> None:
-        """
-        force_update path:
-          - Prefer upgrading existing entries via indices (if we can discover them).
-          - If no indices (legacy JSON) or upgrade fails, fall back to install-only logic.
-        """
-        indices = self._find_installed_indices_for_output(ctx, output)
-
-        upgraded_any = False
-        for idx in indices:
-            if self._upgrade_index(ctx, idx):
-                upgraded_any = True
-                if not ctx.quiet:
-                    print(f"[nix] output '{output}' successfully upgraded (index {idx}).")
-
-        if upgraded_any:
-            # Make upgrades visible to tests
-            print(f"[nix] output '{output}' successfully upgraded.")
-            return
-
-        if indices and not ctx.quiet:
-            print(f"[nix] upgrade failed; removing indices {indices} and reinstalling '{output}'.")
-
-        for idx in indices:
-            self._remove_index(ctx, idx)
-
-        # Ensure installed (includes its own fallback logic)
-        self._install_only(ctx, output, allow_failure)
-
-        # Make upgrades visible to tests (semantic: update requested)
-        print(f"[nix] output '{output}' successfully upgraded.")
-
-    def run(self, ctx: "RepoContext") -> None:
-        if not self.supports(ctx):
-            return
-
-        outputs = self._profile_outputs(ctx)
-
-        if not ctx.quiet:
-            print(
-                "[nix] flake detected in "
-                f"{ctx.identifier}, ensuring outputs: "
-                + ", ".join(name for name, _ in outputs)
-            )
-
-        for output, allow_failure in outputs:
-            if ctx.force_update:
-                self._force_upgrade_output(ctx, output, allow_failure)
-            else:
-                self._install_only(ctx, output, allow_failure)

src/pkgmgr/actions/mirror/setup_cmd.py

@@ -1,14 +1,121 @@
+# src/pkgmgr/actions/mirror/setup_cmd.py
 from __future__ import annotations
 
 from typing import List, Tuple
+from urllib.parse import urlparse
 
-from pkgmgr.core.git import run_git, GitError
+from pkgmgr.core.git import GitError, run_git
+from pkgmgr.core.remote_provisioning import ProviderHint, RepoSpec, ensure_remote_repo
+from pkgmgr.core.remote_provisioning.ensure import EnsureOptions
 
 from .context import build_context
 from .git_remote import determine_primary_remote_url, ensure_origin_remote
 from .types import Repository
 
 
+def _probe_mirror(url: str, repo_dir: str) -> Tuple[bool, str]:
+    """
+    Probe a remote mirror URL using `git ls-remote`.
+
+    Returns:
+      (True, "") on success,
+      (False, error_message) on failure.
+    """
+    try:
+        run_git(["ls-remote", url], cwd=repo_dir)
+        return True, ""
+    except GitError as exc:
+        return False, str(exc)
+
+
+def _host_from_git_url(url: str) -> str:
+    url = (url or "").strip()
+    if not url:
+        return ""
+
+    if "://" in url:
+        parsed = urlparse(url)
+        netloc = (parsed.netloc or "").strip()
+        if "@" in netloc:
+            netloc = netloc.split("@", 1)[1]
+        # keep optional :port
+        return netloc
+
+    # scp-like: git@host:owner/repo.git
+    if "@" in url and ":" in url:
+        after_at = url.split("@", 1)[1]
+        host = after_at.split(":", 1)[0]
+        return host.strip()
+
+    return url.split("/", 1)[0].strip()
+
+def _ensure_remote_repository(
+    repo: Repository,
+    repositories_base_dir: str,
+    all_repos: List[Repository],
+    preview: bool,
+) -> None:
+    """
+    Ensure that the remote repository exists using provider APIs.
+
+    This is ONLY called when ensure_remote=True.
+    """
+    ctx = build_context(repo, repositories_base_dir, all_repos)
+    resolved_mirrors = ctx.resolved_mirrors
+
+    primary_url = determine_primary_remote_url(repo, resolved_mirrors)
+    if not primary_url:
+        print("[INFO] No remote URL could be derived; skipping remote provisioning.")
+        return
+
+    # IMPORTANT:
+    # - repo["provider"] is typically a provider *kind* (e.g. "github" / "gitea"),
+    #   NOT a hostname. We derive the actual host from the remote URL.
+    host = _host_from_git_url(primary_url)
+    owner = repo.get("account")
+    name = repo.get("repository")
+
+    if not host or not owner or not name:
+        print("[WARN] Missing host/account/repository; cannot ensure remote repo.")
+        print(f"       host={host!r}, account={owner!r}, repository={name!r}")
+        return
+
+    print("------------------------------------------------------------")
+    print(f"[REMOTE ENSURE] {ctx.identifier}")
+    print(f"[REMOTE ENSURE] host: {host}")
+    print("------------------------------------------------------------")
+
+    spec = RepoSpec(
+        host=str(host),
+        owner=str(owner),
+        name=str(name),
+        private=bool(repo.get("private", True)),
+        description=str(repo.get("description", "")),
+    )
+
+    provider_kind = str(repo.get("provider", "")).strip().lower() or None
+
+    try:
+        result = ensure_remote_repo(
+            spec,
+            provider_hint=ProviderHint(kind=provider_kind),
+            options=EnsureOptions(
+                preview=preview,
+                interactive=True,
+                allow_prompt=True,
+                save_prompt_token_to_keyring=True,
+            ),
+        )
+        print(f"[REMOTE ENSURE] {result.status.upper()}: {result.message}")
+        if result.url:
+            print(f"[REMOTE ENSURE] URL: {result.url}")
+    except Exception as exc:  # noqa: BLE001
+        # Keep action layer resilient
+        print(f"[ERROR] Remote provisioning failed: {exc}")
+
+    print()
+
+
 def _setup_local_mirrors_for_repo(
     repo: Repository,
     repositories_base_dir: str,
@@ -16,7 +123,8 @@ def _setup_local_mirrors_for_repo(
     preview: bool,
 ) -> None:
     """
-    Ensure local Git state is sane (currently: 'origin' remote).
+    Local setup:
+      - Ensure 'origin' remote exists and is sane
     """
     ctx = build_context(repo, repositories_base_dir, all_repos)
 
@@ -29,103 +137,68 @@ def _setup_local_mirrors_for_repo(
     print()
 
 
-def _probe_mirror(url: str, repo_dir: str) -> Tuple[bool, str]:
-    """
-    Probe a remote mirror by running `git ls-remote <url>`.
-
-    Returns:
-      (True, "") on success,
-      (False, error_message) on failure.
-
-    Wichtig:
-      - Wir werten ausschließlich den Exit-Code aus.
-      - STDERR kann Hinweise/Warnings enthalten und ist NICHT automatisch ein Fehler.
-    """
-    try:
-        # Wir ignorieren stdout komplett; wichtig ist nur, dass der Befehl ohne
-        # GitError (also Exit-Code 0) durchläuft.
-        run_git(["ls-remote", url], cwd=repo_dir)
-        return True, ""
-    except GitError as exc:
-        return False, str(exc)
-
-
 def _setup_remote_mirrors_for_repo(
     repo: Repository,
     repositories_base_dir: str,
     all_repos: List[Repository],
     preview: bool,
+    ensure_remote: bool,
 ) -> None:
     """
     Remote-side setup / validation.
 
-    Aktuell werden nur **nicht-destruktive Checks** gemacht:
+    Default behavior:
+      - Non-destructive checks using `git ls-remote`.
 
-      - Für jeden Mirror (aus config + MIRRORS-Datei, file gewinnt):
+    Optional behavior:
-          * `git ls-remote <url>` wird ausgeführt.
+      - If ensure_remote=True:
-          * Bei Exit-Code 0 → [OK]
+          * Attempt to create missing repositories via provider API
-          * Bei Fehler → [WARN] + Details aus der GitError-Exception
+          * Uses TokenResolver (ENV -> keyring -> prompt)
-
-    Es werden **keine** Provider-APIs aufgerufen und keine Repos angelegt.
     """
     ctx = build_context(repo, repositories_base_dir, all_repos)
-    resolved_m = ctx.resolved_mirrors
+    resolved_mirrors = ctx.resolved_mirrors
 
     print("------------------------------------------------------------")
     print(f"[MIRROR SETUP:REMOTE] {ctx.identifier}")
     print(f"[MIRROR SETUP:REMOTE] dir: {ctx.repo_dir}")
     print("------------------------------------------------------------")
 
-    if not resolved_m:
+    if ensure_remote:
-        # Optional: Fallback auf eine heuristisch bestimmte URL, falls wir
+        _ensure_remote_repository(
-        # irgendwann "automatisch anlegen" implementieren wollen.
+            repo,
-        primary_url = determine_primary_remote_url(repo, resolved_m)
+            repositories_base_dir=repositories_base_dir,
-        if not primary_url:
+            all_repos=all_repos,
-            print(
+            preview=preview,
-                "[INFO] No mirrors configured (config or MIRRORS file), and no "
-                "primary URL could be derived from provider/account/repository."
         )
+
+    if not resolved_mirrors:
+        primary_url = determine_primary_remote_url(repo, resolved_mirrors)
+        if not primary_url:
+            print("[INFO] No mirrors configured and no primary URL available.")
             print()
             return
 
         ok, error_message = _probe_mirror(primary_url, ctx.repo_dir)
         if ok:
-            print(f"[OK]   Remote mirror (primary) is reachable: {primary_url}")
+            print(f"[OK] primary: {primary_url}")
         else:
-            print("[WARN] Primary remote URL is NOT reachable:")
+            print(f"[WARN] primary: {primary_url}")
-            print(f"       {primary_url}")
-            if error_message:
-                print("       Details:")
             for line in error_message.splitlines():
                 print(f"         {line}")
 
-        print()
-        print(
-            "[INFO] Remote checks are non-destructive and only use `git ls-remote` "
-            "to probe mirror URLs."
-        )
         print()
         return
 
-    # Normaler Fall: wir haben benannte Mirrors aus config/MIRRORS
+    for name, url in sorted(resolved_mirrors.items()):
-    for name, url in sorted(resolved_m.items()):
         ok, error_message = _probe_mirror(url, ctx.repo_dir)
         if ok:
-            print(f"[OK]   Remote mirror '{name}' is reachable: {url}")
+            print(f"[OK] {name}: {url}")
         else:
-            print(f"[WARN] Remote mirror '{name}' is NOT reachable:")
+            print(f"[WARN] {name}: {url}")
-            print(f"       {url}")
-            if error_message:
-                print("       Details:")
             for line in error_message.splitlines():
                 print(f"         {line}")
 
     print()
-    print(
-        "[INFO] Remote checks are non-destructive and only use `git ls-remote` "
-        "to probe mirror URLs."
-    )
-    print()
 
 
 def setup_mirrors(
@@ -135,22 +208,25 @@ def setup_mirrors(
     preview: bool = False,
     local: bool = True,
     remote: bool = True,
+    ensure_remote: bool = False,
 ) -> None:
     """
     Setup mirrors for the selected repositories.
 
     local:
-      - Configure local Git remotes (currently: ensure 'origin' is present and
+      - Configure local Git remotes (ensure 'origin' exists).
-        points to a reasonable URL).
 
     remote:
-      - Non-destructive remote checks using `git ls-remote` for each mirror URL.
+      - Non-destructive remote checks using `git ls-remote`.
-        Es werden keine Repositories auf dem Provider angelegt.
+
+    ensure_remote:
+      - If True, attempt to create missing remote repositories via provider APIs.
+      - This is explicit and NEVER enabled implicitly.
     """
     for repo in selected_repos:
         if local:
             _setup_local_mirrors_for_repo(
-                repo,
+                repo=repo,
                 repositories_base_dir=repositories_base_dir,
                 all_repos=all_repos,
                 preview=preview,
@@ -158,8 +234,9 @@ def setup_mirrors(
 
         if remote:
             _setup_remote_mirrors_for_repo(
-                repo,
+                repo=repo,
                 repositories_base_dir=repositories_base_dir,
                 all_repos=all_repos,
                 preview=preview,
+                ensure_remote=ensure_remote,
             )

src/pkgmgr/actions/repository/update.py

@@ -1,58 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-
-import shutil
-
-from pkgmgr.actions.install import install_repos
-from pkgmgr.actions.repository.pull import pull_with_verification
-
-
-def update_repos(
-    selected_repos,
-    repositories_base_dir,
-    bin_dir,
-    all_repos,
-    no_verification,
-    system_update,
-    preview: bool,
-    quiet: bool,
-    update_dependencies: bool,
-    clone_mode: str,
-    force_update: bool = True,
-) -> None:
-    """
-    Update repositories by pulling latest changes and installing them.
-    """
-    pull_with_verification(
-        selected_repos,
-        repositories_base_dir,
-        all_repos,
-        [],
-        no_verification,
-        preview,
-    )
-
-    install_repos(
-        selected_repos,
-        repositories_base_dir,
-        bin_dir,
-        all_repos,
-        no_verification,
-        preview,
-        quiet,
-        clone_mode,
-        update_dependencies,
-        force_update=force_update,
-    )
-
-    if system_update:
-        from pkgmgr.core.command.run import run_command
-
-        if shutil.which("nix") is not None:
-            try:
-                run_command("nix profile upgrade '.*'", preview=preview)
-            except SystemExit as e:
-                print(f"[Warning] 'nix profile upgrade' failed: {e}")
-
-        run_command("sudo -u aur_builder yay -Syu --noconfirm", preview=preview)
-        run_command("sudo pacman -Syyu --noconfirm", preview=preview)

src/pkgmgr/actions/update/__init__.py

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

src/pkgmgr/actions/update/manager.py

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

src/pkgmgr/actions/update/os_release.py

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

src/pkgmgr/actions/update/system_updater.py

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

src/pkgmgr/cli/commands/mirror.py

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

src/pkgmgr/cli/commands/repos.py

@@ -8,7 +8,6 @@ from typing import Any, Dict, List
 
 from pkgmgr.cli.context import CLIContext
 from pkgmgr.actions.install import install_repos
-from pkgmgr.actions.repository.update import update_repos
 from pkgmgr.actions.repository.deinstall import deinstall_repos
 from pkgmgr.actions.repository.delete import delete_repos
 from pkgmgr.actions.repository.status import status_repos
@@ -72,25 +71,6 @@ def handle_repos_command(
         )
         return
 
-    # ------------------------------------------------------------
-    # update
-    # ------------------------------------------------------------
-    if args.command == "update":
-        update_repos(
-            selected,
-            ctx.repositories_base_dir,
-            ctx.binaries_dir,
-            ctx.all_repositories,
-            args.no_verification,
-            args.system_update,
-            args.preview,
-            args.quiet,
-            args.dependencies,
-            args.clone_mode,
-            force_update=True,
-        )
-        return
-
     # ------------------------------------------------------------
     # deinstall
     # ------------------------------------------------------------

src/pkgmgr/cli/dispatch.py

@@ -129,7 +129,6 @@ def dispatch_command(args, ctx: CLIContext) -> None:
     # ------------------------------------------------------------------ #
     if args.command in (
         "install",
-        "update",
         "deinstall",
         "delete",
         "status",
@@ -141,6 +140,27 @@ def dispatch_command(args, ctx: CLIContext) -> None:
         handle_repos_command(args, ctx, selected)
         return
 
+    # ------------------------------------------------------------
+    # update
+    # ------------------------------------------------------------
+    if args.command == "update":
+        from pkgmgr.actions.update import UpdateManager
+        UpdateManager().run(
+            selected_repos=selected,
+            repositories_base_dir=ctx.repositories_base_dir,
+            bin_dir=ctx.binaries_dir,
+            all_repos=ctx.all_repositories,
+            no_verification=args.no_verification,
+            system_update=args.system,
+            preview=args.preview,
+            quiet=args.quiet,
+            update_dependencies=args.dependencies,
+            clone_mode=args.clone_mode,
+            force_update=True,
+        )
+        return
+
+
     # ------------------------------------------------------------------ #
     # Tools (explore / terminal / code)
     # ------------------------------------------------------------------ #
@@ -176,7 +196,7 @@ def dispatch_command(args, ctx: CLIContext) -> None:
         return
 
     if args.command == "mirror":
-        handle_mirror_command(args, ctx, selected)
+        handle_mirror_command(ctx, args, selected)
         return
 
     print(f"Unknown command: {args.command}")

src/pkgmgr/cli/parser/common.py

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

src/pkgmgr/cli/parser/install_update.py

@@ -33,11 +33,12 @@ def add_install_update_subparsers(
     )
     add_install_update_arguments(update_parser)
     update_parser.add_argument(
-    "--system-update",
+        "--system",
-        dest="system_update",
+        dest="system",
         action="store_true",
         help="Include system update commands",
     )
+    # No --update here: update implies force_update=True
 
     deinstall_parser = subparsers.add_parser(
         "deinstall",

src/pkgmgr/cli/parser/mirror_cmd.py

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

src/pkgmgr/core/credentials/__init__.py

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

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

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

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

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

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

@@ -0,0 +1,39 @@
+# src/pkgmgr/core/credentials/providers/keyring.py
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from ..store_keys import build_keyring_key
+from ..types import KeyringUnavailableError, TokenRequest, TokenResult
+
+
+def _import_keyring():
+    try:
+        import keyring  # type: ignore
+
+        return keyring
+    except Exception as exc:  # noqa: BLE001
+        raise KeyringUnavailableError(
+            "python-keyring is not available or no backend is configured."
+        ) from exc
+
+
+@dataclass(frozen=True)
+class KeyringTokenProvider:
+    """Resolve/store tokens from/to OS keyring via python-keyring."""
+
+    source_name: str = "keyring"
+
+    def get(self, request: TokenRequest) -> Optional[TokenResult]:
+        keyring = _import_keyring()
+        key = build_keyring_key(request.provider_kind, request.host, request.owner)
+        token = keyring.get_password(key.service, key.username)
+        if token:
+            return TokenResult(token=token.strip(), source=self.source_name)
+        return None
+
+    def set(self, request: TokenRequest, token: str) -> None:
+        keyring = _import_keyring()
+        key = build_keyring_key(request.provider_kind, request.host, request.owner)
+        keyring.set_password(key.service, key.username, token)

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

@@ -0,0 +1,32 @@
+# src/pkgmgr/core/credentials/providers/prompt.py
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass
+from getpass import getpass
+from typing import Optional
+
+from ..types import TokenRequest, TokenResult
+
+
+@dataclass(frozen=True)
+class PromptTokenProvider:
+    """Interactively prompt for a token.
+
+    Only used when:
+    - interactive mode is enabled
+    - stdin is a TTY
+    """
+
+    source_name: str = "prompt"
+
+    def get(self, request: TokenRequest) -> Optional[TokenResult]:
+        if not sys.stdin.isatty():
+            return None
+
+        owner_info = f" (owner: {request.owner})" if request.owner else ""
+        prompt = f"Enter API token for {request.provider_kind} on {request.host}{owner_info}: "
+        token = (getpass(prompt) or "").strip()
+        if not token:
+            return None
+        return TokenResult(token=token, source=self.source_name)

src/pkgmgr/core/credentials/resolver.py

@@ -0,0 +1,71 @@
+# src/pkgmgr/core/credentials/resolver.py
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from .providers.env import EnvTokenProvider
+from .providers.keyring import KeyringTokenProvider
+from .providers.prompt import PromptTokenProvider
+from .types import NoCredentialsError, TokenRequest, TokenResult
+
+
+@dataclass(frozen=True)
+class ResolutionOptions:
+    """Controls token resolution behavior."""
+
+    interactive: bool = True
+    allow_prompt: bool = True
+    save_prompt_token_to_keyring: bool = True
+
+
+class TokenResolver:
+    """Resolve tokens from multiple sources (ENV -> Keyring -> Prompt)."""
+
+    def __init__(self) -> None:
+        self._env = EnvTokenProvider()
+        self._keyring = KeyringTokenProvider()
+        self._prompt = PromptTokenProvider()
+
+    def get_token(
+        self,
+        provider_kind: str,
+        host: str,
+        owner: Optional[str] = None,
+        options: Optional[ResolutionOptions] = None,
+    ) -> TokenResult:
+        opts = options or ResolutionOptions()
+        request = TokenRequest(provider_kind=provider_kind, host=host, owner=owner)
+
+        # 1) ENV
+        env_res = self._env.get(request)
+        if env_res:
+            return env_res
+
+        # 2) Keyring
+        try:
+            kr_res = self._keyring.get(request)
+            if kr_res:
+                return kr_res
+        except Exception:
+            # Keyring missing/unavailable: ignore to allow prompt (workstations)
+            # or to fail cleanly below (headless CI without prompt).
+            pass
+
+        # 3) Prompt (optional)
+        if opts.interactive and opts.allow_prompt:
+            prompt_res = self._prompt.get(request)
+            if prompt_res:
+                if opts.save_prompt_token_to_keyring:
+                    try:
+                        self._keyring.set(request, prompt_res.token)
+                    except Exception:
+                        # If keyring cannot store, still use token for this run.
+                        pass
+                return prompt_res
+
+        raise NoCredentialsError(
+            f"No token available for {provider_kind}@{host}"
+            + (f" (owner: {owner})" if owner else "")
+            + ". Provide it via environment variable or keyring."
+        )

src/pkgmgr/core/credentials/store_keys.py

@@ -0,0 +1,54 @@
+# src/pkgmgr/core/credentials/store_keys.py
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class KeyringKey:
+    """Keyring address for a token."""
+
+    service: str
+    username: str
+
+
+def build_keyring_key(provider_kind: str, host: str, owner: Optional[str]) -> KeyringKey:
+    """Build a stable keyring key.
+
+    - service: "pkgmgr:<provider>"
+    - username: "<host>|<owner>" or "<host>|-"
+    """
+    provider_kind = str(provider_kind).strip().lower()
+    host = str(host).strip()
+    owner_part = (str(owner).strip() if owner else "-")
+    return KeyringKey(service=f"pkgmgr:{provider_kind}", username=f"{host}|{owner_part}")
+
+
+def env_var_candidates(provider_kind: str, host: str, owner: Optional[str]) -> list[str]:
+    """Return a list of environment variable names to try.
+
+    Order is from most specific to most generic.
+    """
+    kind = re_sub_non_alnum(str(provider_kind).strip().upper())
+    host_norm = re_sub_non_alnum(str(host).strip().upper())
+    candidates: list[str] = []
+
+    if owner:
+        owner_norm = re_sub_non_alnum(str(owner).strip().upper())
+        candidates.append(f"PKGMGR_{kind}_TOKEN_{host_norm}_{owner_norm}")
+        candidates.append(f"PKGMGR_TOKEN_{kind}_{host_norm}_{owner_norm}")
+
+    candidates.append(f"PKGMGR_{kind}_TOKEN_{host_norm}")
+    candidates.append(f"PKGMGR_TOKEN_{kind}_{host_norm}")
+    candidates.append(f"PKGMGR_{kind}_TOKEN")
+    candidates.append(f"PKGMGR_TOKEN_{kind}")
+    candidates.append("PKGMGR_TOKEN")
+    return candidates
+
+
+def re_sub_non_alnum(value: str) -> str:
+    """Normalize to an uppercase env-var friendly token (A-Z0-9_)."""
+    import re
+
+    return re.sub(r"[^A-Z0-9]+", "_", value).strip("_")

src/pkgmgr/core/credentials/types.py

@@ -0,0 +1,34 @@
+# src/pkgmgr/core/credentials/types.py
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+class CredentialError(RuntimeError):
+    """Base class for credential resolution errors."""
+
+
+class NoCredentialsError(CredentialError):
+    """Raised when no usable credential could be resolved."""
+
+
+class KeyringUnavailableError(CredentialError):
+    """Raised when keyring is requested but no backend is available."""
+
+
+@dataclass(frozen=True)
+class TokenRequest:
+    """Parameters describing which token we need."""
+
+    provider_kind: str  # e.g. "gitea", "github"
+    host: str  # e.g. "git.example.org" or "github.com"
+    owner: Optional[str] = None  # optional org/user
+
+
+@dataclass(frozen=True)
+class TokenResult:
+    """A resolved token plus metadata about its source."""
+
+    token: str
+    source: str  # "env" | "keyring" | "prompt"

src/pkgmgr/core/remote_provisioning/__init__.py

@@ -0,0 +1,14 @@
+# src/pkgmgr/core/remote_provisioning/__init__.py
+"""Remote repository provisioning (ensure remote repo exists)."""
+
+from .ensure import ensure_remote_repo
+from .registry import ProviderRegistry
+from .types import EnsureResult, ProviderHint, RepoSpec
+
+__all__ = [
+    "ensure_remote_repo",
+    "RepoSpec",
+    "EnsureResult",
+    "ProviderHint",
+    "ProviderRegistry",
+]

src/pkgmgr/core/remote_provisioning/ensure.py

@@ -0,0 +1,97 @@
+# src/pkgmgr/core/remote_provisioning/ensure.py
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from pkgmgr.core.credentials.resolver import ResolutionOptions, TokenResolver
+
+from .http.errors import HttpError
+from .registry import ProviderRegistry
+from .types import (
+    AuthError,
+    EnsureResult,
+    NetworkError,
+    PermissionError,
+    ProviderHint,
+    RepoSpec,
+    UnsupportedProviderError,
+)
+
+
+@dataclass(frozen=True)
+class EnsureOptions:
+    """Options controlling remote provisioning."""
+
+    preview: bool = False
+    interactive: bool = True
+    allow_prompt: bool = True
+    save_prompt_token_to_keyring: bool = True
+
+
+def _raise_mapped_http_error(exc: HttpError, host: str) -> None:
+    """Map HttpError into domain-specific error types."""
+    if exc.status == 0:
+        raise NetworkError(f"Network error while talking to {host}: {exc}") from exc
+    if exc.status == 401:
+        raise AuthError(f"Authentication failed for {host} (401).") from exc
+    if exc.status == 403:
+        raise PermissionError(f"Permission denied for {host} (403).") from exc
+
+    raise NetworkError(
+        f"HTTP error from {host}: status={exc.status}, message={exc}, body={exc.body}"
+    ) from exc
+
+
+def ensure_remote_repo(
+    spec: RepoSpec,
+    provider_hint: Optional[ProviderHint] = None,
+    options: Optional[EnsureOptions] = None,
+    registry: Optional[ProviderRegistry] = None,
+    token_resolver: Optional[TokenResolver] = None,
+) -> EnsureResult:
+    """Ensure that the remote repository exists (create if missing).
+
+    - Uses TokenResolver (ENV -> keyring -> prompt)
+    - Selects provider via ProviderRegistry (or provider_hint override)
+    - Respects preview mode (no remote changes)
+    - Maps HTTP errors to domain-specific errors
+    """
+    opts = options or EnsureOptions()
+    reg = registry or ProviderRegistry.default()
+    resolver = token_resolver or TokenResolver()
+
+    provider = reg.resolve(spec.host)
+    if provider_hint and provider_hint.kind:
+        forced = provider_hint.kind.strip().lower()
+        provider = next(
+            (p for p in reg.providers if getattr(p, "kind", "").lower() == forced),
+            None,
+        )
+
+    if provider is None:
+        raise UnsupportedProviderError(f"No provider matched host: {spec.host}")
+
+    token_opts = ResolutionOptions(
+        interactive=opts.interactive,
+        allow_prompt=opts.allow_prompt,
+        save_prompt_token_to_keyring=opts.save_prompt_token_to_keyring,
+    )
+    token = resolver.get_token(
+        provider_kind=getattr(provider, "kind", "unknown"),
+        host=spec.host,
+        owner=spec.owner,
+        options=token_opts,
+    )
+
+    if opts.preview:
+        return EnsureResult(
+            status="skipped",
+            message="Preview mode: no remote changes performed.",
+        )
+
+    try:
+        return provider.ensure_repo(token.token, spec)
+    except HttpError as exc:
+        _raise_mapped_http_error(exc, host=spec.host)
+        return EnsureResult(status="failed", message="Unreachable error mapping.")

src/pkgmgr/core/remote_provisioning/http/__init__.py

@@ -0,0 +1,5 @@
+# src/pkgmgr/core/remote_provisioning/http/__init__.py
+from .client import HttpClient, HttpResponse
+from .errors import HttpError
+
+__all__ = ["HttpClient", "HttpResponse", "HttpError"]

src/pkgmgr/core/remote_provisioning/http/client.py

@@ -0,0 +1,69 @@
+# src/pkgmgr/core/remote_provisioning/http/client.py
+from __future__ import annotations
+
+import json
+import ssl
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+from .errors import HttpError
+
+
+@dataclass(frozen=True)
+class HttpResponse:
+    status: int
+    text: str
+    json: Optional[Dict[str, Any]] = None
+
+
+class HttpClient:
+    """Tiny HTTP client (stdlib) with JSON support."""
+
+    def __init__(self, timeout_s: int = 15) -> None:
+        self._timeout_s = int(timeout_s)
+
+    def request_json(
+        self,
+        method: str,
+        url: str,
+        headers: Optional[Dict[str, str]] = None,
+        payload: Optional[Dict[str, Any]] = None,
+    ) -> HttpResponse:
+        data: Optional[bytes] = None
+        final_headers: Dict[str, str] = dict(headers or {})
+
+        if payload is not None:
+            data = json.dumps(payload).encode("utf-8")
+            final_headers.setdefault("Content-Type", "application/json")
+
+        req = urllib.request.Request(url=url, data=data, method=method.upper())
+        for k, v in final_headers.items():
+            req.add_header(k, v)
+
+        try:
+            with urllib.request.urlopen(
+                req,
+                timeout=self._timeout_s,
+                context=ssl.create_default_context(),
+            ) as resp:
+                raw = resp.read().decode("utf-8", errors="replace")
+
+                parsed: Optional[Dict[str, Any]] = None
+                if raw:
+                    try:
+                        loaded = json.loads(raw)
+                        parsed = loaded if isinstance(loaded, dict) else None
+                    except Exception:
+                        parsed = None
+
+                return HttpResponse(status=int(resp.status), text=raw, json=parsed)
+        except urllib.error.HTTPError as exc:
+            try:
+                body = exc.read().decode("utf-8", errors="replace")
+            except Exception:
+                body = ""
+            raise HttpError(status=int(exc.code), message=str(exc), body=body) from exc
+        except urllib.error.URLError as exc:
+            raise HttpError(status=0, message=str(exc), body="") from exc

src/pkgmgr/core/remote_provisioning/http/errors.py

@@ -0,0 +1,9 @@
+# src/pkgmgr/core/remote_provisioning/http/errors.py
+from __future__ import annotations
+
+
+class HttpError(RuntimeError):
+    def __init__(self, status: int, message: str, body: str = "") -> None:
+        super().__init__(message)
+        self.status = status
+        self.body = body

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

@@ -0,0 +1,6 @@
+# src/pkgmgr/core/remote_provisioning/providers/__init__.py
+from .base import RemoteProvider
+from .gitea import GiteaProvider
+from .github import GitHubProvider
+
+__all__ = ["RemoteProvider", "GiteaProvider", "GitHubProvider"]

src/pkgmgr/core/remote_provisioning/providers/base.py

@@ -0,0 +1,36 @@
+# src/pkgmgr/core/remote_provisioning/providers/base.py
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from ..types import EnsureResult, RepoSpec
+
+
+class RemoteProvider(ABC):
+    """Provider interface for remote repo provisioning."""
+
+    kind: str
+
+    @abstractmethod
+    def can_handle(self, host: str) -> bool:
+        """Return True if this provider implementation matches the host."""
+
+    @abstractmethod
+    def repo_exists(self, token: str, spec: RepoSpec) -> bool:
+        """Return True if repo exists and is accessible."""
+
+    @abstractmethod
+    def create_repo(self, token: str, spec: RepoSpec) -> EnsureResult:
+        """Create a repository (owner may be user or org)."""
+
+    def ensure_repo(self, token: str, spec: RepoSpec) -> EnsureResult:
+        if self.repo_exists(token, spec):
+            return EnsureResult(status="exists", message="Repository exists.")
+        return self.create_repo(token, spec)
+
+    @staticmethod
+    def _api_base(host: str) -> str:
+        # Default to https. If you need http for local dev, store host as "http://..."
+        if host.startswith("http://") or host.startswith("https://"):
+            return host.rstrip("/")
+        return f"https://{host}".rstrip("/")

src/pkgmgr/core/remote_provisioning/providers/gitea.py

@@ -0,0 +1,106 @@
+# src/pkgmgr/core/remote_provisioning/providers/gitea.py
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from ..http.client import HttpClient
+from ..http.errors import HttpError
+from ..types import EnsureResult, RepoSpec
+from .base import RemoteProvider
+
+
+class GiteaProvider(RemoteProvider):
+    """Gitea provider using Gitea REST API v1."""
+
+    kind = "gitea"
+
+    def __init__(self, timeout_s: int = 15) -> None:
+        self._http = HttpClient(timeout_s=timeout_s)
+
+    def can_handle(self, host: str) -> bool:
+        """
+        Heuristic host match:
+        - Acts as a fallback provider for self-hosted setups.
+        - Must NOT claim GitHub hosts.
+        - If you add more providers later, tighten this heuristic or use provider hints.
+        """
+        h = host.lower()
+        if h in ("github.com", "api.github.com") or h.endswith(".github.com"):
+            return False
+        return True
+
+    def _headers(self, token: str) -> Dict[str, str]:
+        """
+        Gitea commonly supports:
+          Authorization: token <TOKEN>
+        Newer versions may also accept Bearer tokens, but "token" is broadly compatible.
+        """
+        return {
+            "Authorization": f"token {token}",
+            "Accept": "application/json",
+            "User-Agent": "pkgmgr",
+        }
+
+    def repo_exists(self, token: str, spec: RepoSpec) -> bool:
+        base = self._api_base(spec.host)
+        url = f"{base}/api/v1/repos/{spec.owner}/{spec.name}"
+        try:
+            resp = self._http.request_json("GET", url, headers=self._headers(token))
+            return 200 <= resp.status < 300
+        except HttpError as exc:
+            if exc.status == 404:
+                return False
+            raise
+
+    def create_repo(self, token: str, spec: RepoSpec) -> EnsureResult:
+        base = self._api_base(spec.host)
+
+        payload: Dict[str, Any] = {
+            "name": spec.name,
+            "private": bool(spec.private),
+        }
+        if spec.description:
+            payload["description"] = spec.description
+        if spec.default_branch:
+            payload["default_branch"] = spec.default_branch
+
+        org_url = f"{base}/api/v1/orgs/{spec.owner}/repos"
+        user_url = f"{base}/api/v1/user/repos"
+
+        # Try org first, then fall back to user creation.
+        try:
+            resp = self._http.request_json(
+                "POST",
+                org_url,
+                headers=self._headers(token),
+                payload=payload,
+            )
+            if 200 <= resp.status < 300:
+                html_url = (resp.json or {}).get("html_url") if resp.json else None
+                return EnsureResult(
+                    status="created",
+                    message="Repository created (org).",
+                    url=str(html_url) if html_url else None,
+                )
+        except HttpError:
+            # Typical org failures: 404 (not an org), 403 (no rights), 401 (bad token).
+            pass
+
+        resp = self._http.request_json(
+            "POST",
+            user_url,
+            headers=self._headers(token),
+            payload=payload,
+        )
+        if 200 <= resp.status < 300:
+            html_url = (resp.json or {}).get("html_url") if resp.json else None
+            return EnsureResult(
+                status="created",
+                message="Repository created (user).",
+                url=str(html_url) if html_url else None,
+            )
+
+        return EnsureResult(
+            status="failed",
+            message=f"Failed to create repository (status {resp.status}).",
+        )

src/pkgmgr/core/remote_provisioning/providers/github.py

@@ -0,0 +1,101 @@
+# src/pkgmgr/core/remote_provisioning/providers/github.py
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from ..http.client import HttpClient
+from ..http.errors import HttpError
+from ..types import EnsureResult, RepoSpec
+from .base import RemoteProvider
+
+
+class GitHubProvider(RemoteProvider):
+    """GitHub provider using GitHub REST API."""
+
+    kind = "github"
+
+    def __init__(self, timeout_s: int = 15) -> None:
+        self._http = HttpClient(timeout_s=timeout_s)
+
+    def can_handle(self, host: str) -> bool:
+        h = host.lower()
+        return h in ("github.com", "api.github.com") or h.endswith(".github.com")
+
+    def _api_base(self, host: str) -> str:
+        """
+        GitHub API base:
+        - Public GitHub: https://api.github.com
+        - GitHub Enterprise Server: https://<host>/api/v3
+        """
+        h = host.lower()
+        if h in ("github.com", "api.github.com"):
+            return "https://api.github.com"
+
+        # Enterprise instance:
+        if host.startswith("http://") or host.startswith("https://"):
+            return host.rstrip("/") + "/api/v3"
+        return f"https://{host}/api/v3"
+
+    def _headers(self, token: str) -> Dict[str, str]:
+        return {
+            "Authorization": f"Bearer {token}",
+            "Accept": "application/vnd.github+json",
+            "User-Agent": "pkgmgr",
+        }
+
+    def repo_exists(self, token: str, spec: RepoSpec) -> bool:
+        api = self._api_base(spec.host)
+        url = f"{api}/repos/{spec.owner}/{spec.name}"
+        try:
+            resp = self._http.request_json("GET", url, headers=self._headers(token))
+            return 200 <= resp.status < 300
+        except HttpError as exc:
+            if exc.status == 404:
+                return False
+            raise
+
+    def create_repo(self, token: str, spec: RepoSpec) -> EnsureResult:
+        api = self._api_base(spec.host)
+
+        payload: Dict[str, Any] = {
+            "name": spec.name,
+            "private": bool(spec.private),
+        }
+        if spec.description:
+            payload["description"] = spec.description
+        if spec.default_branch:
+            payload["default_branch"] = spec.default_branch
+
+        org_url = f"{api}/orgs/{spec.owner}/repos"
+        user_url = f"{api}/user/repos"
+
+        # Try org first, then fall back to user creation.
+        try:
+            resp = self._http.request_json(
+                "POST", org_url, headers=self._headers(token), payload=payload
+            )
+            if 200 <= resp.status < 300:
+                html_url = (resp.json or {}).get("html_url") if resp.json else None
+                return EnsureResult(
+                    status="created",
+                    message="Repository created (org).",
+                    url=str(html_url) if html_url else None,
+                )
+        except HttpError:
+            pass
+
+        resp = self._http.request_json(
+            "POST", user_url, headers=self._headers(token), payload=payload
+        )
+        if 200 <= resp.status < 300:
+            html_url = (resp.json or {}).get("html_url") if resp.json else None
+            return EnsureResult(
+                status="created",
+                message="Repository created (user).",
+                url=str(html_url) if html_url else None,
+            )
+
+        return EnsureResult(
+            status="failed",
+            message=f"Failed to create repository (status {resp.status}).",
+        )

src/pkgmgr/core/remote_provisioning/registry.py

@@ -0,0 +1,30 @@
+# src/pkgmgr/core/remote_provisioning/registry.py
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Optional
+
+from .providers.base import RemoteProvider
+from .providers.gitea import GiteaProvider
+from .providers.github import GitHubProvider
+
+
+@dataclass
+class ProviderRegistry:
+    """Resolve the correct provider implementation for a host."""
+
+    providers: List[RemoteProvider]
+
+    @classmethod
+    def default(cls) -> "ProviderRegistry":
+        # Order matters: more specific providers first; fallback providers last.
+        return cls(providers=[GitHubProvider(), GiteaProvider()])
+
+    def resolve(self, host: str) -> Optional[RemoteProvider]:
+        for p in self.providers:
+            try:
+                if p.can_handle(host):
+                    return p
+            except Exception:
+                continue
+        return None

src/pkgmgr/core/remote_provisioning/types.py

@@ -0,0 +1,61 @@
+# src/pkgmgr/core/remote_provisioning/types.py
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal, Optional
+
+EnsureStatus = Literal["exists", "created", "skipped", "failed"]
+
+
+@dataclass(frozen=True)
+class ProviderHint:
+    """Optional hint to force a provider kind."""
+
+    kind: Optional[str] = None  # e.g. "gitea" or "github"
+
+
+@dataclass(frozen=True)
+class RepoSpec:
+    """Desired remote repository."""
+
+    host: str
+    owner: str
+    name: str
+    private: bool = True
+    description: str = ""
+    default_branch: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class EnsureResult:
+    status: EnsureStatus
+    message: str
+    url: Optional[str] = None
+
+
+class RemoteProvisioningError(RuntimeError):
+    """Base class for remote provisioning errors."""
+
+
+class AuthError(RemoteProvisioningError):
+    """Authentication failed (401)."""
+
+
+class PermissionError(RemoteProvisioningError):
+    """Permission denied (403)."""
+
+
+class NotFoundError(RemoteProvisioningError):
+    """Resource not found (404)."""
+
+
+class PolicyError(RemoteProvisioningError):
+    """Provider/org policy prevents the operation."""
+
+
+class NetworkError(RemoteProvisioningError):
+    """Network/transport errors."""
+
+
+class UnsupportedProviderError(RemoteProvisioningError):
+    """No provider matched for the given host."""

tests/e2e/test_mirror_commands.py

@@ -4,21 +4,21 @@
 """
 E2E integration tests for the `pkgmgr mirror` command family.
 
-This test class covers:
+Covered commands:
 
   - pkgmgr mirror --help
   - pkgmgr mirror list --preview --all
   - pkgmgr mirror diff --preview --all
   - pkgmgr mirror merge config file --preview --all
   - pkgmgr mirror setup --preview --all
+  - pkgmgr mirror check --preview --all
+  - pkgmgr mirror provision --preview --all
 
-All of these subcommands are fully wired at CLI level and do not
+All commands are executed via the real CLI entry point (main module).
-require mocks. With --preview, merge and setup do not perform
+With --preview enabled, all operations are non-destructive and safe
-destructive actions, making them safe for CI execution.
+to run inside CI containers.
 """
 
-from __future__ import annotations
-
 import io
 import runpy
 import sys
@@ -28,25 +28,25 @@ from contextlib import redirect_stdout, redirect_stderr
 
 class TestIntegrationMirrorCommands(unittest.TestCase):
     """
-    E2E tests for `pkgmgr mirror` commands.
+    End-to-end tests for `pkgmgr mirror` commands.
     """
 
     # ------------------------------------------------------------
     # Helper
     # ------------------------------------------------------------
-    def _run_pkgmgr(self, args: list[str]) -> str:
+    def _run_pkgmgr(self, args):
         """
-        Execute pkgmgr with the given arguments and return captured stdout+stderr.
+        Execute pkgmgr with the given arguments and return captured output.
 
         - Treat SystemExit(0) or SystemExit(None) as success.
-        - Convert non-zero exit codes into AssertionError.
+        - Any other exit code is considered a test failure.
         """
         original_argv = list(sys.argv)
         buffer = io.StringIO()
         cmd_repr = "pkgmgr " + " ".join(args)
 
         try:
-            sys.argv = ["pkgmgr"] + args
+            sys.argv = ["pkgmgr"] + list(args)
 
             try:
                 with redirect_stdout(buffer), redirect_stderr(buffer):
@@ -55,9 +55,9 @@ class TestIntegrationMirrorCommands(unittest.TestCase):
                 code = exc.code if isinstance(exc.code, int) else None
                 if code not in (0, None):
                     raise AssertionError(
-                        f"{cmd_repr!r} failed with exit code {exc.code}. "
+                        "%r failed with exit code %r.\n\nOutput:\n%s"
-                        "Scroll up to inspect the pkgmgr output."
+                        % (cmd_repr, exc.code, buffer.getvalue())
-                    ) from exc
+                    )
 
             return buffer.getvalue()
 
@@ -68,44 +68,41 @@ class TestIntegrationMirrorCommands(unittest.TestCase):
     # Tests
     # ------------------------------------------------------------
 
-    def test_mirror_help(self) -> None:
+    def test_mirror_help(self):
         """
-        Ensure `pkgmgr mirror --help` runs successfully
+        `pkgmgr mirror --help` should run without error and print usage info.
-        and prints a usage message for the mirror command.
         """
         output = self._run_pkgmgr(["mirror", "--help"])
         self.assertIn("usage:", output)
         self.assertIn("pkgmgr mirror", output)
 
-    def test_mirror_list_preview_all(self) -> None:
+    def test_mirror_list_preview_all(self):
         """
-        `pkgmgr mirror list --preview --all` should run without error
+        `pkgmgr mirror list --preview --all`
-        and produce some output for the selected repositories.
         """
-        output = self._run_pkgmgr(["mirror", "list", "--preview", "--all"])
+        output = self._run_pkgmgr(
-        # Do not assert specific wording; just ensure something was printed.
+            ["mirror", "list", "--preview", "--all"]
+        )
         self.assertTrue(
             output.strip(),
-            msg="Expected `pkgmgr mirror list --preview --all` to produce output.",
+            "Expected output from mirror list",
         )
 
-    def test_mirror_diff_preview_all(self) -> None:
+    def test_mirror_diff_preview_all(self):
         """
-        `pkgmgr mirror diff --preview --all` should run without error
+        `pkgmgr mirror diff --preview --all`
-        and produce some diagnostic output (diff header, etc.).
         """
-        output = self._run_pkgmgr(["mirror", "diff", "--preview", "--all"])
+        output = self._run_pkgmgr(
+            ["mirror", "diff", "--preview", "--all"]
+        )
         self.assertTrue(
             output.strip(),
-            msg="Expected `pkgmgr mirror diff --preview --all` to produce output.",
+            "Expected output from mirror diff",
         )
 
-    def test_mirror_merge_config_to_file_preview_all(self) -> None:
+    def test_mirror_merge_config_to_file_preview_all(self):
         """
-        `pkgmgr mirror merge config file --preview --all` should run without error.
+        `pkgmgr mirror merge config file --preview --all`
-
-        In preview mode this does not change either config or MIRRORS files;
-        it only prints what would be merged.
         """
         output = self._run_pkgmgr(
             [
@@ -119,23 +116,47 @@ class TestIntegrationMirrorCommands(unittest.TestCase):
         )
         self.assertTrue(
             output.strip(),
-            msg=(
+            "Expected output from mirror merge (config -> file)",
-                "Expected `pkgmgr mirror merge config file --preview --all` "
-                "to produce output."
-            ),
         )
 
-    def test_mirror_setup_preview_all(self) -> None:
+    def test_mirror_setup_preview_all(self):
         """
-        `pkgmgr mirror setup --preview --all` should run without error.
+        `pkgmgr mirror setup --preview --all`
-
-        In preview mode only the intended Git operations and remote
-        suggestions are printed; no real changes are made.
         """
-        output = self._run_pkgmgr(["mirror", "setup", "--preview", "--all"])
+        output = self._run_pkgmgr(
+            ["mirror", "setup", "--preview", "--all"]
+        )
         self.assertTrue(
             output.strip(),
-            msg="Expected `pkgmgr mirror setup --preview --all` to produce output.",
+            "Expected output from mirror setup",
+        )
+
+    def test_mirror_check_preview_all(self):
+        """
+        `pkgmgr mirror check --preview --all`
+
+        Performs non-destructive remote checks (git ls-remote).
+        """
+        output = self._run_pkgmgr(
+            ["mirror", "check", "--preview", "--all"]
+        )
+        self.assertTrue(
+            output.strip(),
+            "Expected output from mirror check",
+        )
+
+    def test_mirror_provision_preview_all(self):
+        """
+        `pkgmgr mirror provision --preview --all`
+
+        In preview mode this MUST NOT create remote repositories.
+        """
+        output = self._run_pkgmgr(
+            ["mirror", "provision", "--preview", "--all"]
+        )
+        self.assertTrue(
+            output.strip(),
+            "Expected output from mirror provision (preview)",
         )
 
 

tests/e2e/test_update_all_no_system.py

@@ -1,6 +1,6 @@
 """
 Integration test: update all configured repositories using
---clone-mode https and --no-verification.
+--clone-mode shallow and --no-verification, WITHOUT system updates.
 
 This test is intended to be run inside the Docker container where:
   - network access is available,
@@ -8,8 +8,8 @@ This test is intended to be run inside the Docker container where:
   - and it is safe to perform real git operations.
 
 It passes if BOTH commands complete successfully (in separate tests):
-  1) pkgmgr update --all --clone-mode https --no-verification --system-update
+  1) pkgmgr update --all --clone-mode shallow --no-verification
-  2) nix run .#pkgmgr -- update --all --clone-mode https --no-verification --system-update
+  2) nix run .#pkgmgr -- update --all --clone-mode shallow --no-verification
 """
 
 from __future__ import annotations
@@ -38,7 +38,7 @@ def _make_temp_gitconfig_with_safe_dirs(home: Path) -> Path:
     return gitconfig
 
 
-class TestIntegrationUpdateAllHttps(unittest.TestCase):
+class TestIntegrationUpdateAllshallowNoSystem(unittest.TestCase):
     def _common_env(self, home_dir: str) -> dict[str, str]:
         env = os.environ.copy()
         env["HOME"] = home_dir
@@ -86,32 +86,30 @@ class TestIntegrationUpdateAllHttps(unittest.TestCase):
         remove_pkgmgr_from_nix_profile()
         nix_profile_list_debug("AFTER CLEANUP")
 
-    def test_update_all_repositories_https_pkgmgr(self) -> None:
+    def test_update_all_repositories_shallow_pkgmgr_no_system(self) -> None:
         self._common_setup()
-        with tempfile.TemporaryDirectory(prefix="pkgmgr-updateall-") as tmp:
+        with tempfile.TemporaryDirectory(prefix="pkgmgr-updateall-nosys-") as tmp:
             env = self._common_env(tmp)
             args = [
                 "update",
                 "--all",
                 "--clone-mode",
-                "https",
+                "shallow",
                 "--no-verification",
-                "--system-update",
             ]
             self._run_cmd(["pkgmgr", *args], label="pkgmgr", env=env)
             pkgmgr_help_debug()
 
-    def test_update_all_repositories_https_nix_pkgmgr(self) -> None:
+    def test_update_all_repositories_shallow_nix_pkgmgr_no_system(self) -> None:
         self._common_setup()
-        with tempfile.TemporaryDirectory(prefix="pkgmgr-updateall-nix-") as tmp:
+        with tempfile.TemporaryDirectory(prefix="pkgmgr-updateall-nosys-nix-") as tmp:
             env = self._common_env(tmp)
             args = [
                 "update",
                 "--all",
                 "--clone-mode",
-                "https",
+                "shallow",
                 "--no-verification",
-                "--system-update",
             ]
             self._run_cmd(
                 ["nix", "run", ".#pkgmgr", "--", *args],

tests/e2e/test_update_pkgmgr_system.py

@@ -0,0 +1,124 @@
+"""
+Integration test: update ONLY the 'pkgmgr' repository with system updates enabled.
+
+This test is intended to be run inside the Docker container where:
+  - network access is available,
+  - the config/config.yaml is present,
+  - and it is safe to perform real git operations.
+
+It passes if BOTH commands complete successfully (in separate tests):
+  1) pkgmgr update pkgmgr --clone-mode shallow --no-verification --system
+  2) nix run .#pkgmgr -- update pkgmgr --clone-mode shallow --no-verification --system
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import tempfile
+import unittest
+from pathlib import Path
+
+from test_install_pkgmgr_shallow import (
+    nix_profile_list_debug,
+    remove_pkgmgr_from_nix_profile,
+    pkgmgr_help_debug,
+)
+
+
+def _make_temp_gitconfig_with_safe_dirs(home: Path) -> Path:
+    gitconfig = home / ".gitconfig"
+    gitconfig.write_text(
+        "[safe]\n"
+        "\tdirectory = /src\n"
+        "\tdirectory = /src/.git\n"
+        "\tdirectory = *\n"
+    )
+    return gitconfig
+
+
+class TestIntegrationUpdatePkgmgrWithSystem(unittest.TestCase):
+    def _common_env(self, home_dir: str) -> dict[str, str]:
+        env = os.environ.copy()
+        env["HOME"] = home_dir
+
+        home = Path(home_dir)
+        home.mkdir(parents=True, exist_ok=True)
+
+        env["GIT_CONFIG_GLOBAL"] = str(_make_temp_gitconfig_with_safe_dirs(home))
+
+        # Ensure nix is discoverable if the container has it
+        env["PATH"] = "/nix/var/nix/profiles/default/bin:" + env.get("PATH", "")
+
+        return env
+
+    def _run_cmd(self, cmd: list[str], label: str, env: dict[str, str]) -> None:
+        cmd_repr = " ".join(cmd)
+        print(f"\n[TEST] Running ({label}): {cmd_repr}")
+
+        proc = subprocess.run(
+            cmd,
+            check=False,
+            cwd=os.getcwd(),
+            env=env,
+            text=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+        )
+
+        print(proc.stdout.rstrip())
+
+        if proc.returncode != 0:
+            print(f"\n[TEST] Command failed ({label})")
+            print(f"[TEST] Command : {cmd_repr}")
+            print(f"[TEST] Exit code: {proc.returncode}")
+
+            nix_profile_list_debug(f"ON FAILURE ({label})")
+
+            raise AssertionError(
+                f"({label}) {cmd_repr!r} failed with exit code {proc.returncode}.\n\n"
+                f"--- output ---\n{proc.stdout}\n"
+            )
+
+    def _common_setup(self) -> None:
+        nix_profile_list_debug("BEFORE CLEANUP")
+        remove_pkgmgr_from_nix_profile()
+        nix_profile_list_debug("AFTER CLEANUP")
+
+    def test_update_pkgmgr_shallow_pkgmgr_with_system(self) -> None:
+        self._common_setup()
+        with tempfile.TemporaryDirectory(prefix="pkgmgr-update-pkgmgr-sys-") as tmp:
+            env = self._common_env(tmp)
+            args = [
+                "update",
+                "pkgmgr",
+                "--clone-mode",
+                "shallow",
+                "--no-verification",
+                "--system",
+            ]
+            self._run_cmd(["pkgmgr", *args], label="pkgmgr", env=env)
+            pkgmgr_help_debug()
+
+    def test_update_pkgmgr_shallow_nix_pkgmgr_with_system(self) -> None:
+        self._common_setup()
+        with tempfile.TemporaryDirectory(prefix="pkgmgr-update-pkgmgr-sys-nix-") as tmp:
+            env = self._common_env(tmp)
+            args = [
+                "update",
+                "pkgmgr",
+                "--clone-mode",
+                "shallow",
+                "--no-verification",
+                "--system",
+            ]
+            self._run_cmd(
+                ["nix", "run", ".#pkgmgr", "--", *args],
+                label="nix run .#pkgmgr",
+                env=env,
+            )
+            pkgmgr_help_debug()
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/integration/test_recursive_capabilities.py

@@ -23,7 +23,7 @@ from unittest.mock import patch
 import pkgmgr.actions.install as install_mod
 from pkgmgr.actions.install import install_repos
 from pkgmgr.actions.install.installers.makefile import MakefileInstaller
-from pkgmgr.actions.install.installers.nix_flake import NixFlakeInstaller
+from pkgmgr.actions.install.installers.nix import NixFlakeInstaller
 from pkgmgr.actions.install.installers.os_packages.arch_pkgbuild import (
     ArchPkgbuildInstaller,
 )

tests/unit/pkgmgr/actions/install/installers/nix/test_legacy.py

@@ -20,9 +20,10 @@ import subprocess
 import tempfile
 import unittest
 from contextlib import redirect_stdout
+from typing import List
 from unittest.mock import patch
 
-from pkgmgr.actions.install.installers.nix_flake import NixFlakeInstaller
+from pkgmgr.actions.install.installers.nix import NixFlakeInstaller
 
 
 class DummyCtx:
@@ -60,42 +61,51 @@ class TestNixFlakeInstaller(unittest.TestCase):
             shutil.rmtree(self._tmpdir, ignore_errors=True)
 
     @staticmethod
-    def _cp(code: int) -> subprocess.CompletedProcess:
+    def _cp(code: int, stdout: str = "", stderr: str = "") -> subprocess.CompletedProcess:
-        # stdout/stderr are irrelevant here, but keep shape realistic
+        return subprocess.CompletedProcess(args=["nix"], returncode=code, stdout=stdout, stderr=stderr)
-        return subprocess.CompletedProcess(args=["nix"], returncode=code, stdout="", stderr="")
 
     @staticmethod
     def _enable_nix_in_module(which_patch) -> None:
-        """Ensure shutil.which('nix') in nix_flake module returns a path."""
+        """Ensure shutil.which('nix') in nix installer module returns a path."""
         which_patch.return_value = "/usr/bin/nix"
 
+    @staticmethod
+    def _install_cmds_from_calls(call_args_list) -> List[str]:
+        cmds: List[str] = []
+        for c in call_args_list:
+            if not c.args:
+                continue
+            cmd = c.args[0]
+            if isinstance(cmd, str) and cmd.startswith("nix profile install "):
+                cmds.append(cmd)
+        return cmds
+
     def test_nix_flake_run_success(self) -> None:
         """
-        When run_command returns success (returncode 0), installer
+        When install returns success (returncode 0), installer
         should report success and not raise.
         """
         ctx = DummyCtx(identifier="some-lib", repo_dir=self.repo_dir)
         installer = NixFlakeInstaller()
 
+        install_results = [self._cp(0)]  # first install succeeds
+
+        def fake_subprocess_run(cmd, *args, **kwargs):
+            # cmd is a string because CommandRunner uses shell=True
+            if isinstance(cmd, str) and cmd.startswith("nix profile list --json"):
+                return self._cp(0, stdout='{"elements": []}', stderr="")
+            if isinstance(cmd, str) and cmd.startswith("nix profile install "):
+                return install_results.pop(0)
+            return self._cp(0)
+
         buf = io.StringIO()
-        with patch("pkgmgr.actions.install.installers.nix_flake.shutil.which") as which_mock, patch(
+        with patch("pkgmgr.actions.install.installers.nix.installer.shutil.which") as which_mock, patch(
-            "pkgmgr.actions.install.installers.nix_flake.subprocess.run"
+            "pkgmgr.actions.install.installers.nix.installer.os.path.exists", return_value=True
-        ) as subproc_mock, patch(
+        ), patch(
-            "pkgmgr.actions.install.installers.nix_flake.run_command"
+            "pkgmgr.actions.install.installers.nix.runner.subprocess.run", side_effect=fake_subprocess_run
-        ) as run_cmd_mock, redirect_stdout(buf):
+        ) as subproc_mock, redirect_stdout(buf):
             self._enable_nix_in_module(which_mock)
 
-            # For profile list JSON (used only on failure paths, but keep deterministic)
-            subproc_mock.return_value = subprocess.CompletedProcess(
-                args=["nix", "profile", "list", "--json"],
-                returncode=0,
-                stdout='{"elements": []}',
-                stderr="",
-            )
-
-            # Install succeeds
-            run_cmd_mock.return_value = self._cp(0)
-
             self.assertTrue(installer.supports(ctx))
             installer.run(ctx)
 
@@ -103,12 +113,8 @@ class TestNixFlakeInstaller(unittest.TestCase):
         self.assertIn("[nix] install: nix profile install", out)
         self.assertIn("[nix] output 'default' successfully installed.", out)
 
-        run_cmd_mock.assert_called_with(
+        install_cmds = self._install_cmds_from_calls(subproc_mock.call_args_list)
-            f"nix profile install {self.repo_dir}#default",
+        self.assertEqual(install_cmds, [f"nix profile install {self.repo_dir}#default"])
-            cwd=self.repo_dir,
-            preview=False,
-            allow_failure=True,
-        )
 
     def test_nix_flake_run_mandatory_failure_raises(self) -> None:
         """
@@ -118,34 +124,43 @@ class TestNixFlakeInstaller(unittest.TestCase):
         ctx = DummyCtx(identifier="some-lib", repo_dir=self.repo_dir)
         installer = NixFlakeInstaller()
 
+        # retry layer does one attempt (non-403), then fallback does final attempt => 2 installs
+        install_results = [self._cp(1), self._cp(1)]
+
+        def fake_subprocess_run(cmd, *args, **kwargs):
+            if isinstance(cmd, str) and cmd.startswith("nix profile list --json"):
+                return self._cp(0, stdout='{"elements": []}', stderr="")
+            if isinstance(cmd, str) and cmd.startswith("nix profile install "):
+                return install_results.pop(0)
+            return self._cp(0)
+
         buf = io.StringIO()
-        with patch("pkgmgr.actions.install.installers.nix_flake.shutil.which") as which_mock, patch(
+        with patch("pkgmgr.actions.install.installers.nix.installer.shutil.which") as which_mock, patch(
-            "pkgmgr.actions.install.installers.nix_flake.subprocess.run"
+            "pkgmgr.actions.install.installers.nix.installer.os.path.exists", return_value=True
-        ) as subproc_mock, patch(
+        ), patch(
-            "pkgmgr.actions.install.installers.nix_flake.run_command"
+            "pkgmgr.actions.install.installers.nix.runner.subprocess.run", side_effect=fake_subprocess_run
-        ) as run_cmd_mock, redirect_stdout(buf):
+        ) as subproc_mock, redirect_stdout(buf):
             self._enable_nix_in_module(which_mock)
 
-            # No indices available (empty list)
-            subproc_mock.return_value = subprocess.CompletedProcess(
-                args=["nix", "profile", "list", "--json"],
-                returncode=0,
-                stdout='{"elements": []}',
-                stderr="",
-            )
-
-            # First install fails, retry fails -> should raise SystemExit(1)
-            run_cmd_mock.side_effect = [self._cp(1), self._cp(1)]
-
             self.assertTrue(installer.supports(ctx))
             with self.assertRaises(SystemExit) as cm:
                 installer.run(ctx)
 
         self.assertEqual(cm.exception.code, 1)
+
         out = buf.getvalue()
         self.assertIn("[nix] install: nix profile install", out)
         self.assertIn("[ERROR] Failed to install Nix flake output 'default' (exit 1)", out)
 
+        install_cmds = self._install_cmds_from_calls(subproc_mock.call_args_list)
+        self.assertEqual(
+            install_cmds,
+            [
+                f"nix profile install {self.repo_dir}#default",
+                f"nix profile install {self.repo_dir}#default",
+            ],
+        )
+
     def test_nix_flake_run_optional_failure_does_not_raise(self) -> None:
         """
         For pkgmgr/package-manager repositories:
@@ -156,29 +171,26 @@ class TestNixFlakeInstaller(unittest.TestCase):
         ctx = DummyCtx(identifier="pkgmgr", repo_dir=self.repo_dir)
         installer = NixFlakeInstaller()
 
+        # pkgmgr success (1 call), default fails (2 calls: attempt + final)
+        install_results = [self._cp(0), self._cp(1), self._cp(1)]
+
+        def fake_subprocess_run(cmd, *args, **kwargs):
+            if isinstance(cmd, str) and cmd.startswith("nix profile list --json"):
+                return self._cp(0, stdout='{"elements": []}', stderr="")
+            if isinstance(cmd, str) and cmd.startswith("nix profile install "):
+                return install_results.pop(0)
+            return self._cp(0)
+
         buf = io.StringIO()
-        with patch("pkgmgr.actions.install.installers.nix_flake.shutil.which") as which_mock, patch(
+        with patch("pkgmgr.actions.install.installers.nix.installer.shutil.which") as which_mock, patch(
-            "pkgmgr.actions.install.installers.nix_flake.subprocess.run"
+            "pkgmgr.actions.install.installers.nix.installer.os.path.exists", return_value=True
-        ) as subproc_mock, patch(
+        ), patch(
-            "pkgmgr.actions.install.installers.nix_flake.run_command"
+            "pkgmgr.actions.install.installers.nix.runner.subprocess.run", side_effect=fake_subprocess_run
-        ) as run_cmd_mock, redirect_stdout(buf):
+        ) as subproc_mock, redirect_stdout(buf):
             self._enable_nix_in_module(which_mock)
 
-            # No indices available (empty list)
-            subproc_mock.return_value = subprocess.CompletedProcess(
-                args=["nix", "profile", "list", "--json"],
-                returncode=0,
-                stdout='{"elements": []}',
-                stderr="",
-            )
-
-            # pkgmgr install ok; default fails twice (initial + retry)
-            run_cmd_mock.side_effect = [self._cp(0), self._cp(1), self._cp(1)]
-
             self.assertTrue(installer.supports(ctx))
-
+            installer.run(ctx)  # must NOT raise
-            # Must NOT raise despite optional failure
-            installer.run(ctx)
 
         out = buf.getvalue()
 
@@ -192,14 +204,15 @@ class TestNixFlakeInstaller(unittest.TestCase):
         self.assertIn("[ERROR] Failed to install Nix flake output 'default' (exit 1)", out)
         self.assertIn("[WARNING] Continuing despite failure of optional output 'default'.", out)
 
-        # Verify run_command was called for both outputs (default twice due to retry)
+        install_cmds = self._install_cmds_from_calls(subproc_mock.call_args_list)
-        expected_calls = [
+        self.assertEqual(
-            (f"nix profile install {self.repo_dir}#pkgmgr",),
+            install_cmds,
-            (f"nix profile install {self.repo_dir}#default",),
+            [
-            (f"nix profile install {self.repo_dir}#default",),
+                f"nix profile install {self.repo_dir}#pkgmgr",
-        ]
+                f"nix profile install {self.repo_dir}#default",
-        actual_cmds = [c.args[0] for c in run_cmd_mock.call_args_list]
+                f"nix profile install {self.repo_dir}#default",
-        self.assertEqual(actual_cmds, [e[0] for e in expected_calls])
+            ],
+        )
 
     def test_nix_flake_supports_respects_disable_env(self) -> None:
         """
@@ -209,7 +222,9 @@ class TestNixFlakeInstaller(unittest.TestCase):
         ctx = DummyCtx(identifier="pkgmgr", repo_dir=self.repo_dir, quiet=False)
         installer = NixFlakeInstaller()
 
-        with patch("pkgmgr.actions.install.installers.nix_flake.shutil.which") as which_mock:
+        with patch("pkgmgr.actions.install.installers.nix.installer.shutil.which") as which_mock, patch(
+            "pkgmgr.actions.install.installers.nix.installer.os.path.exists", return_value=True
+        ):
             self._enable_nix_in_module(which_mock)
             os.environ["PKGMGR_DISABLE_NIX_FLAKE_INSTALLER"] = "1"
             self.assertFalse(installer.supports(ctx))

tests/unit/pkgmgr/actions/install/installers/nix/test_nix_retry_403.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+import unittest
+from unittest.mock import patch
+
+from pkgmgr.actions.install.installers.nix.retry import GitHubRateLimitRetry, RetryPolicy
+from pkgmgr.actions.install.installers.nix.types import RunResult
+
+
+class DummyCtx:
+    def __init__(self, quiet: bool = True) -> None:
+        self.quiet = quiet
+
+
+class FakeRunner:
+    """
+    Simulates a runner that returns:
+      - HTTP 403 for the first N calls
+      - success afterwards
+    """
+
+    def __init__(self, fail_count: int) -> None:
+        self.fail_count = fail_count
+        self.calls = 0
+
+    def run(self, ctx: DummyCtx, cmd: str, allow_failure: bool) -> RunResult:
+        self.calls += 1
+
+        if self.calls <= self.fail_count:
+            return RunResult(
+                returncode=1,
+                stdout="",
+                stderr="error: HTTP error 403: rate limit exceeded (simulated)",
+            )
+
+        return RunResult(returncode=0, stdout="ok", stderr="")
+
+
+class TestGitHub403Retry(unittest.TestCase):
+    def test_retries_on_403_without_realtime_waiting(self) -> None:
+        """
+        Ensure:
+          - It retries only on GitHub 403-like errors
+          - It does not actually sleep in realtime (time.sleep patched)
+          - It stops once a success occurs
+          - Wait times follow Fibonacci(base=30) + jitter
+        """
+        policy = RetryPolicy(
+            max_attempts=3,          # attempts: 1,2,3
+            base_delay_seconds=30,   # fibonacci delays: 30, 30, 60
+            jitter_seconds_min=0,
+            jitter_seconds_max=60,
+        )
+
+        retry = GitHubRateLimitRetry(policy=policy)
+        ctx = DummyCtx(quiet=True)
+        runner = FakeRunner(fail_count=2)  # fail twice (403), then succeed
+
+        # Make jitter deterministic and prevent real sleeping.
+        with patch("pkgmgr.actions.install.installers.nix.retry.random.randint", return_value=5) as jitter_mock, patch(
+            "pkgmgr.actions.install.installers.nix.retry.time.sleep"
+        ) as sleep_mock:
+            res = retry.run_with_retry(ctx, runner, "nix profile install /tmp#default")
+
+        # Result should be success on 3rd attempt.
+        self.assertEqual(res.returncode, 0)
+        self.assertEqual(runner.calls, 3)
+
+        # jitter should be used for each retry sleep (attempt 1->2, attempt 2->3) => 2 sleeps
+        self.assertEqual(jitter_mock.call_count, 2)
+        self.assertEqual(sleep_mock.call_count, 2)
+
+        # Fibonacci delays for attempts=3: [30, 30, 60]
+        # sleep occurs after failed attempt 1 and 2, so base delays are 30 and 30
+        # wait_time = base_delay + jitter(5) => 35, 35
+        sleep_args = [c.args[0] for c in sleep_mock.call_args_list]
+        self.assertEqual(sleep_args, [35, 35])
+
+    def test_does_not_retry_on_non_403_errors(self) -> None:
+        """
+        Ensure it does not retry when the error is not recognized as GitHub 403/rate limit.
+        """
+        policy = RetryPolicy(max_attempts=7, base_delay_seconds=30)
+        retry = GitHubRateLimitRetry(policy=policy)
+        ctx = DummyCtx(quiet=True)
+
+        class Non403Runner:
+            def __init__(self) -> None:
+                self.calls = 0
+
+            def run(self, ctx: DummyCtx, cmd: str, allow_failure: bool) -> RunResult:
+                self.calls += 1
+                return RunResult(returncode=1, stdout="", stderr="some other error (simulated)")
+
+        runner = Non403Runner()
+
+        with patch("pkgmgr.actions.install.installers.nix.retry.time.sleep") as sleep_mock:
+            res = retry.run_with_retry(ctx, runner, "nix profile install /tmp#default")
+
+        self.assertEqual(res.returncode, 1)
+        self.assertEqual(runner.calls, 1)      # no retries
+        self.assertEqual(sleep_mock.call_count, 0)
+
+
+if __name__ == "__main__":
+    unittest.main()