# Project Document: NexusOS Package Management mit `nip`

**Datum**: 15. Juli 2025

## Überblick

`nip` ist ein fortschrittlicher Paketmanager, der für eine modulare, reproduzierbare und leistungsstarke Linux-Distribution entwickelt wurde, inspiriert von den Prinzipien von NexusOS. Er nutzt bestehende Paket-Ökosysteme wie Pacman (Arch Linux) und Nix, um das System schnell zu bootstrapen, während er Pakete in ein natives `.npk`-Format konvertiert, um langfristige Reproduzierbarkeit und Konformität mit der ACUL-Lizenz zu gewährleisten.

## Ziele

- **Schnelles Bootstrapping**: Verwende Pacman und Nix, um Software in eine GoboLinux-ähnliche Dateistruktur (`/Programs/<App>/<Version>/`) zu installieren.
- **Natives Paketformat**: Konvertiere installierte Pakete in `.npk` mit KDL-Metadaten, BLAKE3-Hashes und ACUL-konformen Logs.
- **Modular und reproduzierbar**: Stelle sicher, dass jedes Paket verifiziert, neu erstellt und über ein lokales Repository oder externe Plattformen wie GitHub geteilt werden kann.
- **Zukunftssicher**: Entwickle das System so, dass es erweiterbar ist, mit Plänen für Reverse-Konvertierung und volle Unterstützung nativer Pakete.

---

## CLI-Syntax

### Fremde Pakete graften
```bash
nip graft pacman htop
nip graft nix hello
```
- Installiert Pakete aus Pacman oder Nix in `/Programs/<App>/<Version>/`.
- Erstellt Symlinks in `/System/Index/` für einfachen Zugriff.

### Deklarative Installation
```bash
nip manifest foreign-packages.yaml
```
- Installiert mehrere Pakete deklarativ aus einer YAML-Datei:
  ```yaml
  graft:
    - source: pacman
      package: neofetch
    - source: nix
      package: htop
      version: unstable
  ```

### In `.npk` konvertieren
```bash
nip convert htop
```
- Konvertiert ein installiertes Paket (z. B. `htop`) in das `.npk`-Format.
- Generiert:
  - `htop.npk` (Archiv)
  - `htop.npk.kdl` (Metadaten)
  - `build.log`, `manifest.yaml`, `license.yaml`
- Speichert in `~/.nip/repo/htop/3.2.1/`.

### Konformität verifizieren
```bash
nip verify htop.npk
```
- Überprüft Lizenz, Hashes und Metadaten auf ACUL-Konformität.

### Paketursprung tracken
```bash
nip track htop
```
- Protokolliert die Quelle (Pacman, Nix usw.) des installierten Pakets.

### Systemzustand sperren
```bash
nip lock
```
- Erstellt eine Lockfile (`nip.lock`), die die exakten Versionen und Quellen aller installierten Pakete festhält, um volle Reproduzierbarkeit zu gewährleisten.

---

## Dateistruktur

### Lokale Repository-Struktur
```
~/.nip/repo/
└── htop/
    └── 3.2.1/
        ├── htop.npk           # Tarball der GoboLinux-strukturierten Dateien
        ├── htop.npk.kdl       # KDL-Metadaten
        ├── build.log          # Build-Details
        ├── manifest.yaml      # Dateiliste + Checksums
        ├── license.yaml       # ACUL-Lizenzinformationen
        └── LICENSE-ACUL.txt   # Lizenztext
```

### Beispiel `.npk.kdl`
```
package "htop" {
  version "3.2.1"
  source "pacman"
  checksum "blake3-abc123def4567890"
  license "GPL-2.0"
  description "Interactive process viewer"
  files {
    binary "/Programs/Htop/3.2.1/bin/htop"
    manpage "/Programs/Htop/3.2.1/share/man/man1/htop.1"
  }
}
```

### Beispiel `nip.lock`
```
lockfile {
  package "htop" {
    version "3.2.1"
    source "pacman"
    checksum "blake3-abc123def4567890"
  }
  package "neofetch" {
    version "7.1.0"
    source "nix"
    checksum "blake3-xyz987654321"
  }
}
```

---

## Implementierung

### Phase 0: MVP Wrapper
- **Graft aus Pacman**: Lade mit `pacman -Sw`, extrahiere und platziere in `/Programs/`. *Status: Prototyp in Arbeit, erste Tests mit `neofetch` erfolgreich.*
- **Graft aus Nix**: Baue mit `nix build`, verschiebe aus `/nix/store/` und platziere in `/Programs/`. *Status: Geplant für Woche 2.*

### Phase 1: `.npk`-Erstellung
- Generiere KDL-Metadaten, BLAKE3-Hash und ACUL-erforderliche Dateien.
- Verpacke in `.npk` (Tarball). *Status: Grundgerüst für `nip convert` wird entwickelt.*

### Phase 2: Verifizierung & Repository
- Implementiere `nip verify` für Integrität und Konformität.
- Verwalte das lokale Repository in `~/.nip/repo/`. *Status: Geplant nach Stabilisierung von Phase 1.*

### Phase 3: Lockfile-Unterstützung
- Implementiere `nip lock`, um eine Lockfile zu erstellen, die den Systemzustand festhält. *Status: Geplant nach Phase 2.*

---

## ACUL-Lizenzintegration
Jedes `.npk` muss enthalten:
- `LICENSE-ACUL.txt`
- `license.yaml` (z. B. `expression: ACUL-1.0`)
- `build.log` (Quell-URIs, Hashes, Zeitstempel)
- `manifest.yaml` (Dateiliste, Checksums)

---

## Nächste Schritte
1. **Teste den MVP**: Führe `nip graft pacman htop` aus und überprüfe die Installation in `/Programs/`.
2. **Erweitere Metadaten**: Erweitere `.npk.kdl` um Abhängigkeiten.
3. **Füge `nip verify` hinzu**: Implementiere die Verifizierungslogik.
4. **Implementiere `nip lock`**: Teste die Lockfile-Generierung für Reproduzierbarkeit.
5. **Erweitere Quellen**: Füge bei Bedarf weitere Ökosysteme hinzu (z. B. Nix in Woche 2).

Dieses Dokument beschreibt den aktuellen Stand des `nip`-Paketmanagers und bietet eine Roadmap für seine Entwicklung im NexusOS-ähnlichen System. Lass uns den Schwung beibehalten! 🚀