# pag – PaganOS Package Manager

Menedżer pakietów dla [PaganOS](https://paganlinux.eu). Instalacja atomowa ze
staging, weryfikacja podpisów GPG (z pinningiem fingerprintu), SHA256 per-plik,
rollback transakcji, hooki pre/post-install i wsparcie systemów immutable.

```bash
pag --version        # wersja klienta
pag                  # pełna pomoc (lista komend)
```

---

## PODSTAWY

| Komenda | Opis |
|---|---|
| `pag install <pkg>...` | Instaluje pakiety (razem z zależnościami) |
| `pag install -f <pkg>...` | **Wymusza reinstalację** (nawet tej samej wersji) – odtwarza pliki, puste katalogi i hooki |
| `pag remove <pkg>...` | Usuwa pakiety |
| `pag update` | Aktualizuje **pakiety** do nowszych wersji |
| `pag sync` | Odświeża indeksy repozytoriów + pokazuje ile pakietów czeka na aktualizację |
| `pag upgrade` | Aktualizacja **systemu**: pakiety + kernel / initramfs / GRUB |
| `pag list` | Lista pakietów dostępnych w repozytorium |
| `pag list --installed` | Lista zainstalowanych pakietów |
| `pag search <query>` | Szukaj pakietów w repo (+ Flathub) |
| `pag info <pkg>` | Szczegóły pakietu (wersja, zależności, rozmiar, podpis) |
| `pag files <pkg>` | Lista plików należących do pakietu |
| `pag verify` | Weryfikacja integralności zainstalowanych plików |
| `pag verify --deep` | Pełna weryfikacja SHA256 per-plik |
| `pag clean` | Czyści cache pobierania |
| `pag stats` | Statystyki systemu (liczba pakietów, rozmiar, cache…) |
| `pag download <pkg>...` | Pobiera pakiety do cache (tryb offline) |

**Smart search:** `pag <nazwa>` (dowolna nieznana komenda) przeszukuje repo
i Flathub oraz podpowiada nazwy – np. `pag firefox` znajdzie pakiet.

---

## BEZPIECZEŃSTWO / KLUCZE GPG

| Komenda | Opis |
|---|---|
| `pag key-add <url\|plik>` | Importuje klucz GPG repozytorium |
| `pag key-list` | Lista zaufanych kluczy |
| `pag key-remove <id>` | Usuwa klucz |
| `pag key-trust <repo>` | Przypina fingerprint klucza repo (TOFU wyłączone) |
| `pag key-untrust <repo>` | Zapomina fingerprint (powrót do TOFU) |
| `pag key-trusted` | Lista przypiętych fingerprintów repo |

---

## ZAAWANSOWANE

| Komenda | Opis |
|---|---|
| `pag why <pkg>` | Dlaczego pakiet jest zainstalowany (kto go zależy) |
| `pag autoremove` | Usuwa osierocone zależności |
| `pag remove-orphans` | Usuwa osierocone zależności (alias) |
| `pag pin <pkg> [wersja]` | Przypina pakiet do wersji (blokada aktualizacji) |
| `pag unpin <pkg>` | Zdejmuje przypięcie |
| `pag pinned` | Lista przypiętych pakietów |
| `pag history` | Historia transakcji |
| `pag rollback` | Cofa **ostatnią** transakcję (przywraca pliki z backupu) |
| `pag repo-add <url> [nazwa]` | Dodaje repozytorium (drop-in w `/etc/pag/repos/`) |
| `pag repo-list` | Lista skonfigurowanych repozytoriów |
| `pag sbom export [spdx\|cyclonedx]` | Eksportuje manifest SBOM wszystkich zainstalowanych komponentów |
| `pag self-update` | Aktualizuje samego klienta `pag` (podpis GPG + SHA256 + składnia, atomowo) |

---

## FLATPAK

| Komenda | Opis |
|---|---|
| `pag flatpak [<query>]` | Szukaj i instaluj z Flathub |
| `pag flatpak search <query>` | Szukaj na Flathub |
| `pag flatpak install <id>` | Instaluje flatpak |
| `pag flatpak remove <id>` | Usuwa flatpak |
| `pag flatpak list` | Lista zainstalowanych flatpaków |
| `pag flatpak update` | Aktualizuje wszystkie flatpaki |
| `pag flatpak info <id>` | Szczegóły flatpaka |

---

## SYSTEM IMMUTABLE (PAG_IMMUTABLE=1)

| Komenda | Opis |
|---|---|
| `pag deploy-list` | Lista wdrożeń (deployments) |
| `pag deploy-rollback` | Przełącza na poprzednie wdrożenie |
| `pag deploy-cleanup [N]` | Usuwa stare wdrożenia (zachowuje N, domyślnie 3) |
| `pag initramfs-update` | Przebudowuje initramfs |
| `pag grub-update` | Regeneruje wpisy GRUB |

---

## Przykłady

```bash
# Instalacja i aktualizacje
sudo pag install firefox gimp
sudo pag update                # same pakiety
sudo pag upgrade               # pakiety + kernel/initramfs/GRUB
sudo pag sync                  # odśwież indeksy + info o aktualizacjach

# Naprawa pakietu (brakujące pliki/katalogi, np. /etc/pulse/default.pa.d)
sudo pag install -f pulseaudio

# Ikony aplikacji po instalacji motywu (cache budowany automatycznie)
sudo pag install papirus-icon-theme

# Bezpieczeństwo
sudo pag key-add https://repo.paganlinux.eu/paganos.asc
sudo pag verify --deep

# Cofnij ostatnią transakcję
sudo pag rollback
```

## Instalacja w systemie

```bash
# Z poziomu działającego PaganOS (pag jest w repo bazowym):
sudo pag self-update
```

## Licencja

PaganOS / pag – projekt open source. Szczegóły w repozytorium dystrybucji.