PkgForge

Modern, Sandboxed .deb and .rpm Package Converter & Lifecycle Manager for Arch Linux & CachyOS

PkgForge converts Debian (.deb) and RedHat (.rpm) packages into Arch Linux compatible .pkg.tar.zst packages. It features a high-speed pure Python native converter, Bubblewrap sandbox isolation, full Headless CLI, Tauri desktop app, URL direct downloading, package lifecycle management (uninstall & rollback), and upstream update tracking.

---

🧪 Demo (real output)

$ pkgforge convert hello_1.0.0-1_amd64.deb --dry-run
    ==> "hello" paketi oluşturuluyor...
    ==> hello 1.0.0-1 paketinin derlenmesi tamamlandı
✅ Paket başarıyla dönüştürüldü: hello-1.0.0-1-x86_64.pkg.tar.zst
📊 Uyumluluk notu: B (warning)
📁 Kurulacak dosyalar: 2
    ./usr/bin/hello
    ./usr/share/hello/data.txt
📋 Provenance: hello-1.0.0-1-x86_64.pkg.tar.zst.provenance.json

---

🖥️ Screenshots (Tauri desktop, dark theme)

Convert	Security

Installed	Settings

Captured headlessly via desktop/scripts/visual-tour.py (12/12 pages render-checked). Backend-dependent panels show their empty states here; connected screenshots require the Tauri runtime.

---

🎯 Key Features

• ⚡ Fast Pure Python Native Converter: Converts .deb packages directly into PKGBUILD and .pkg.tar.zst in seconds without slow external scripts.
• 🛡️ 12 Security Layers & Bubblewrap Sandbox: Executes makepkg and conversions inside isolated bwrap sandboxes with strict MIME, GPG, SHA-256, Path Traversal, and ClamAV malware scanning checks.
• 💻 Dual Interface (Headless CLI + Tauri Desktop): CLI runs without any GUI dependencies. The primary graphical interface is the Tauri 2 + React desktop app (desktop/, build with cd desktop && pnpm tauri build). The legacy PyQt6 GUI (pkgforge gui) is frozen — security fixes only, removal planned for v3.0.
• 🖥️ Native Tauri Desktop App: A modern Tauri 2 + React 19 shell (in desktop/) with tr/en i18n, theme + accent colors, command palette, feature tour, lazy-loaded pages, and a Python sidecar over JSON-RPC. Build with cd desktop && pnpm tauri build.
• 🌐 Direct URL Conversion: Download and convert packages directly from HTTP/HTTPS links (pkgforge convert https://...).
• 📸 Atomic Snapshot Rollback: Automatically takes Btrfs/ZFS filesystem snapshots before installation for instant atomic rollback.
• 🐳 OCI Container Export: Convert any .deb/.rpm to a portable OCI container image (pkgforge convert --to-oci).
• 📦 Binary Delta Updates: Use xdelta3 to download only the diff for faster updates (pkgforge convert --delta).
• ⏪ Lifecycle & Rollback Management: Uninstall converted packages via pacman -R or rollback to previous saved backups stored in ~/.config/pkgforge/backups/.
• 📡 Upstream Auto-Tracker: Compares stored ETag/Last-Modified headers against current values to detect actual content changes.
• 🔀 Cross-Check Engine: Compares versions across Local files, AUR, and Flatpak using pacman's vercmp to recommend the newest release.

---

🚀 Quick Installation

Option 1: Automated System Installer (Recommended)

Clone the repository and run the automated system installer:

git clone https://github.com/goun7/pkgforge.git
cd pkgforge
sudo ./scripts/install.sh

This installs:

• The application tree to /usr/lib/pkgforge
• Executable wrapper to /usr/local/bin/pkgforge
• Desktop shortcut to /usr/share/applications/pkgforge.desktop
• SVG application icon to /usr/share/icons/hicolor/scalable/apps/pkgforge.svg
• Polkit policy to /usr/share/polkit-1/actions/org.pkgforge.app.policy
• Shell completion scripts for Bash and Zsh

To uninstall:

sudo ./scripts/uninstall.sh

---

Option 2: pip / wheel

pip install .                                    # from a checkout
# or build a wheel first:
pip wheel . --no-deps -w dist/ && pip install dist/pkgforge-*.whl

AUR note: An AUR package is planned but not yet published. Until it exists, use Option 1 (installer script) or Option 2 (pip/wheel).

---

💻 CLI Usage

PkgForge includes a complete headless CLI interface (no PyQt6 required for CLI):

# Core conversion
pkgforge convert package.deb                    # Convert DEB → Arch
pkgforge convert package.rpm --install           # Convert + install
pkgforge convert https://example.com/pkg.deb    # Convert from URL
pkgforge convert package.deb --to-oci            # Export as OCI container
pkgforge convert package.deb --delta             # Binary delta download
pkgforge convert package.deb --sign              # Auto-sign with GPG
pkgforge convert package.deb --resolve-deps      # Auto-resolve missing deps
pkgforge convert package.deb --verify-build      # Reproducible build check

# Package lifecycle
pkgforge list                                    # Conversion history
pkgforge remove package-name                     # Uninstall package
pkgforge rollback package-name                   # Restore backup
pkgforge check-updates                           # Check upstream updates
pkgforge check-updates --watch                   # Watch mode (polls every 5min)

# Cross-conversion
pkgforge rpm-to-deb package.rpm                  # RPM → DEB
pkgforge flatpak-export org.mozilla.firefox      # Flatpak → DEB
pkgforge appimage-export app.AppImage            # AppImage → DEB
pkgforge from-source https://github.com/repo     # Generate PKGBUILD from source

# Security & Analysis
pkgforge quality package.pkg.tar.zst             # Quality score (A-F)
pkgforge abi-check package.pkg.tar.zst           # GLIBC/GLIBCXX symbol check
pkgforge scan-image image.tar                    # OCI image security scan
pkgforge sign package.pkg.tar.zst                # GPG sign package
pkgforge verify package.pkg.tar.zst              # Verify GPG signature
pkgforge provenance package.pkg.tar.zst          # SLSA provenance check

# System Management
pkgforge health                                  # Health dashboard
pkgforge graph package-name                      # Dependency graph
pkgforge audit                                   # Audit trail + anomaly detection
pkgforge snapshot-cleanup --install              # Auto-cleanup old snapshots
pkgforge benchmark --quick                       # Performance benchmarks
pkgforge publish package.pkg.tar.zst             # Publish to AUR
pkgforge verify-rollback                         # Test rollback mechanism
pkgforge --clear-cache                           # Clear offline cache

# GUI (primary: Tauri desktop — see below)
pkgforge desktop
pkgforge gui          # legacy PyQt6 (frozen; security fixes only)

UI decision (2026-09-05): the primary interface is the Tauri desktop (desktop/) + Python sidecar, opened with pkgforge desktop. PyQt6 (pkgforge gui) is frozen: no new features, security fixes only; removal planned for v3.0. pkgforge desktop finds a locally built binary (source tree, $PKGFORGE_DESKTOP_BIN, or the system install); if it cannot, it prints the reason and falls back to the legacy GUI.

---

🖼️ Desktop App (primary)

Build and run the Tauri 2 + React 19 desktop shell (tr/en i18n, themes, command palette, feature tour, lazy-loaded pages, Python sidecar over JSON-RPC):

cd desktop && pnpm install && pnpm tauri dev
# production bundle:
cd desktop && pnpm tauri build

🖼️ Legacy PyQt6 GUI (frozen)

Launch via pkgforge desktop (primary; falls back to PyQt6 if the Tauri binary is missing) or directly pkgforge gui (requires sudo pacman -S python-pyqt6). No new features are added here.

---

Legacy PyQt6 feature set

• Drag-and-Drop Drop Zone: Drop .deb or .rpm files directly onto the app.
• Multi-Package Queue Sidebar: Process multiple packages sequentially.
• 🌐 Link Input Dialog: Click the globe icon to paste package URLs.
• 📋 History & Package Manager: Click the clipboard icon to view converted packages, uninstall (pacman -R), or rollback (pacman -U).
• 📡 Upstream Update Check: Click the antenna icon to scan for package updates.
• 🌙 Dark/Light Theme Support: Automatic Breeze / KDE dark and light mode adaptation.

---

🔒 Security Architecture

PkgForge runs a layered set of checks before installing any converted archive. We are deliberate about what each layer does and does not guarantee — a converter can never make a genuinely malicious package safe, so the goal is to surface risk and require review, not to promise absolute safety.

#	Security Layer	Description
1	MIME Type Validation	Strict file --mime-type checking for genuine .deb / .rpm archives
2	GPG Signature Detection	Detects embedded signatures (presence check — not a trust-chain verification, since third-party packages are rarely signed against a known keyring)
3	SHA-256 Integrity	Computes the file hash; for URL downloads it is verified against a caller-supplied checksum when provided
4	Path Traversal & Symlink Shield	Rejects archives containing ../ escapes and extracted symlinks that point outside the build tree
5	HTTPS-Only Downloads	URL downloads require HTTPS by default (plain http:// is opt-in via the allow_insecure_http setting) to prevent MITM tampering
6	Bubblewrap Sandbox	Runs makepkg inside restricted bwrap container mounts with --unshare-net
7	Namcap Static Analysis	Runs Arch Linux namcap static analysis (quality/packaging lint)
8	Dependency Resolution	Resolves required packages and shared libraries dynamically via pacman -Fq
9	File Conflict Detection	Scans the system via pacman -Qo to prevent file collisions
10	Shared Library Audit	ldd analysis to detect missing ELF shared objects and glibc requirements
11	Polkit Privilege Gate	Privileged installation runs exclusively via pkexec, with an explicit confirmation step (--yes to bypass in CLI)
12	Orphan Cleanup GC	Automated purge of stale /tmp/pkgforge_* directories on startup

⚠️ Trust note: The sandbox protects the build step. The final pacman -U installs files onto your real system as root. Always review the compatibility report and the file list before installing packages from untrusted sources.

---

🧪 Running Tests

To run the automated test suite (requires dev dependencies):

pip install -e ".[dev]"
make verify     # ruff + mypy + bandit + full pytest with coverage gate

Current status (measured 2026-09-17, make verify + pnpm test): 2582 tests collected: 2577 passed, 4 skipped, 0 failed · coverage 99.61% on core/+ui/+i18n/ (12 835 statements, 50 missed) · mypy --strict: 0 errors (core/+cli.py+main.py+config.py+ui/, imports followed) · bandit CI-parity: clean (-ll 0 Medium/0 High) · i18n parity 993/993 (tr/en) · desktop: 582/582 vitest, tsc 0 errors. Real tauri build --no-bundle + PyInstaller sidecar built and pkgforge desktop launched end-to-end on this machine.

What the numbers do not prove. High coverage is necessary but not sufficient: this release still shipped a launcher that could not open, because the failure was in the install/build layer that unit tests do not exercise. Verified install + real launch is the only trustworthy end-to-end gate — see docs/RELEASE_READINESS.md.

---

💖 Support / Destek

PkgForge is free and open-source, and it will stay that way — every feature, including the converter, CLI, desktop UI and security scanning, is GPL-3.0 with no paywall. If it saves you time, sponsorship helps keep the project actively maintained.

PkgForge ücretsiz ve açık kaynaklıdır ve öyle kalır — dönüştürücü, CLI, masaüstü arayüzü ve güvenlik taraması dahil her özellik GPL-3.0 altında, paywall'suz. Size zaman kazandırıyorsa sponsorluk projenin aktif bakımını destekler.

• GitHub Sponsors: github.com/sponsors/goun7 (Türkiye'de 20/B istisna hesabı veya şahıs şirketi kurulana dek kapalı)
• Polar.sh: polar.sh/goun7 (aynı nedenle kapalı)

Kripto ödeme bilinçli olarak kabul edilmez. Gelir modeli için acik-kaynak-gelir-modeli.md'ye bakın.

---

📜 License

Distributed under the GNU General Public License v3.0 or later (GPL-3.0-or-later). See LICENSE for details.