feat(dist): System package manager distribution (Homebrew, WinGet, Scoop, Linux DEB & RPM)

.github/workflows/packages.yml

@@ -0,0 +1,191 @@
+name: System Package Distribution (DEB, RPM, Homebrew, WinGet, Scoop)
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+    paths:
+      - 'packaging/**'
+      - 'Formula/**'
+      - '.github/workflows/packages.yml'
+  pull_request:
+    paths:
+      - 'packaging/**'
+      - 'Formula/**'
+      - '.github/workflows/packages.yml'
+  workflow_dispatch:
+    inputs:
+      release_tag:
+        description: 'Release Tag (e.g. v0.3.0)'
+        required: true
+        default: 'v0.3.0'
+
+permissions:
+  contents: write
+  id-token: write
+  attestations: write
+
+jobs:
+  validate-manifests:
+    name: Validate Package Manifests (Homebrew, WinGet, Scoop, nFPM)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install Validation Tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install pyyaml jsonschema
+
+      - name: Validate YAML and JSON Manifests Syntax
+        run: |
+          python -c "
+          import yaml, json, glob, sys
+          print('Validating YAML files...')
+          for yml in glob.glob('packaging/**/*.yaml', recursive=True) + glob.glob('packaging/**/*.yml', recursive=True):
+              with open(yml, 'r') as f:
+                  yaml.safe_load(f)
+                  print(f'  ✓ {yml}')
+
+          print('Validating JSON files...')
+          for jsn in glob.glob('packaging/**/*.json', recursive=True):
+              with open(jsn, 'r') as f:
+                  json.load(f)
+                  print(f'  ✓ {jsn}')
+          "
+
+      - name: Validate Homebrew Formula Ruby Syntax
+        run: |
+          ruby -c Formula/reliadl.rb
+          ruby -c packaging/homebrew/reliadl.rb
+          echo "Homebrew formula Ruby syntax valid ✓"
+
+  build-linux-packages:
+    name: Build Linux Packages (DEB & RPM)
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        arch: [amd64]
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install Runtime & Build Tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt pyinstaller
+
+      - name: Build Binary for Packaging
+        run: |
+          mkdir -p dist
+          python scripts/build_binary.py --output-name "reliadl-linux-${{ matrix.arch }}"
+
+      - name: Install nFPM
+        run: |
+          NFPM_VERSION="2.41.1"
+          curl -sfLo /tmp/nfpm.tar.gz "https://github.com/goreleaser/nfpm/releases/download/v${NFPM_VERSION}/nfpm_${NFPM_VERSION}_Linux_x86_64.tar.gz"
+          tar -xzf /tmp/nfpm.tar.gz -C /tmp
+          sudo mv /tmp/nfpm /usr/local/bin/nfpm
+          nfpm --version
+
+      - name: Determine Version
+        id: vars
+        run: |
+          if [[ "${{ github.ref }}" == refs/tags/v* ]]; then
+            VERSION="${GITHUB_REF#refs/tags/v}"
+          elif [[ -n "${{ github.event.inputs.release_tag }}" ]]; then
+            VERSION="${{ github.event.inputs.release_tag }}"
+            VERSION="${VERSION#v}"
+          else
+            VERSION="0.3.0"
+          fi
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+
+      - name: Package DEB
+        env:
+          ARCH: ${{ matrix.arch }}
+          VERSION: ${{ steps.vars.outputs.version }}
+          BINARY_PATH: dist/reliadl-linux-${{ matrix.arch }}
+        run: |
+          mkdir -p packages
+          python3 -c "
+          import os
+          content = open('packaging/nfpm/nfpm.yaml').read()
+          for k, v in [('\${ARCH}', os.environ['ARCH']), ('\${VERSION}', os.environ['VERSION']), ('\${BINARY_PATH}', os.environ['BINARY_PATH'])]:
+              content = content.replace(k, v)
+          open('/tmp/nfpm_deb.yaml', 'w').write(content)
+          "
+          nfpm package \
+            --config /tmp/nfpm_deb.yaml \
+            --packager deb \
+            --target "packages/reliadl_${VERSION}_${{ matrix.arch }}.deb"
+          ls -lh packages/
+
+      - name: Package RPM
+        env:
+          ARCH: ${{ matrix.arch == 'amd64' && 'x86_64' || 'aarch64' }}
+          VERSION: ${{ steps.vars.outputs.version }}
+          BINARY_PATH: dist/reliadl-linux-${{ matrix.arch }}
+        run: |
+          mkdir -p packages
+          RPM_ARCH="${{ matrix.arch == 'amd64' && 'x86_64' || 'aarch64' }}"
+          python3 -c "
+          import os
+          content = open('packaging/nfpm/nfpm.yaml').read()
+          for k, v in [('\${ARCH}', os.environ['ARCH']), ('\${VERSION}', os.environ['VERSION']), ('\${BINARY_PATH}', os.environ['BINARY_PATH'])]:
+              content = content.replace(k, v)
+          open('/tmp/nfpm_rpm.yaml', 'w').write(content)
+          "
+          nfpm package \
+            --config /tmp/nfpm_rpm.yaml \
+            --packager rpm \
+            --target "packages/reliadl-${VERSION}-1.${RPM_ARCH}.rpm"
+          ls -lh packages/
+
+      - name: Upload Linux Package Artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: linux-packages-${{ matrix.arch }}
+          path: packages/*
+          retention-days: 7
+
+  publish-packages:
+    name: Publish Linux Packages to Release Assets
+    runs-on: ubuntu-latest
+    needs: [validate-manifests, build-linux-packages]
+    if: startsWith(github.ref, 'refs/tags/')
+
+    steps:
+      - name: Download all Linux packages
+        uses: actions/download-artifact@v4
+        with:
+          path: packages/
+          pattern: linux-packages-*
+          merge-multiple: true
+
+      - name: Generate Checksums
+        working-directory: packages
+        run: |
+          sha256sum * > SHA256SUMS-PACKAGES
+          cat SHA256SUMS-PACKAGES
+
+      - name: Attach Packages to GitHub Release
+        uses: softprops/action-gh-release@v3
+        with:
+          files: |
+            packages/*.deb
+            packages/*.rpm
+            packages/SHA256SUMS-PACKAGES
+          generate_release_notes: false
+          fail_on_unmatched_files: false

Dockerfile

@@ -15,7 +15,7 @@ WORKDIR /build
 
 # Copy only dependency manifests first to exploit layer caching
 COPY requirements.txt pyproject.toml README.md LICENSE ./
-COPY src/ ./src/
+COPY reliadl/ ./reliadl/
 
 # Install into an isolated prefix so we can COPY just the result
 RUN pip install --no-cache-dir --prefix=/install .
@@ -54,7 +54,7 @@ EXPOSE 9090
 
 # Health-check: verify the CLI entrypoint is importable
 HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
-    CMD python -c "import src; print('ok')" || exit 1
+    CMD python -c "import reliadl; print('ok')" || exit 1
 
 ENTRYPOINT ["reliadl"]
 CMD ["--help"]

Formula/reliadl.rb

@@ -0,0 +1,48 @@
+# typed: false
+# frozen_string_literal: true
+
+# Homebrew Formula for ReliaDL
+# Tap repository: PxA-Labs/homebrew-tap
+# Installation: brew install pxa-labs/tap/reliadl
+
+class Reliadl < Formula
+  desc "Production-grade fault-tolerant parallel file downloader with per-chunk verification"
+  homepage "https://github.com/PxA-Labs/ReliaDL"
+  version "0.3.0"
+  license "Apache-2.0"
+
+  on_macos do
+    if Hardware::CPU.arm?
+      url "https://github.com/PxA-Labs/ReliaDL/releases/download/v#{version}/reliadl-darwin-arm64"
+      # sha256 will be updated by release automation
+    else
+      url "https://github.com/PxA-Labs/ReliaDL/releases/download/v#{version}/reliadl-darwin-amd64"
+      # sha256 will be updated by release automation
+    end
+  end
+
+  on_linux do
+    if Hardware::CPU.arm? && Hardware::CPU.is_64_bit?
+      url "https://github.com/PxA-Labs/ReliaDL/releases/download/v#{version}/reliadl-linux-arm64"
+      # sha256 will be updated by release automation
+    else
+      url "https://github.com/PxA-Labs/ReliaDL/releases/download/v#{version}/reliadl-linux-amd64"
+      # sha256 will be updated by release automation
+    end
+  end
+
+  def install
+    binary_name = if OS.mac?
+      Hardware::CPU.arm? ? "reliadl-darwin-arm64" : "reliadl-darwin-amd64"
+    else
+      Hardware::CPU.arm? ? "reliadl-linux-arm64" : "reliadl-linux-amd64"
+    end
+
+    bin.install binary_name => "reliadl"
+  end
+
+  test do
+    assert_match "ReliaDL", shell_output("#{bin}/reliadl --help")
+    assert_match version.to_s, shell_output("#{bin}/reliadl --version 2>&1", 0)
+  end
+end

docs/PACKAGES.md

@@ -0,0 +1,115 @@
+# System Package Managers & OS Distribution — ReliaDL
+
+> **Audience**: Systems Administrators, DevOps Engineers, and End Users  
+> **Target Version**: ReliaDL v0.3.0+  
+
+---
+
+## 1. Overview
+
+To reduce installation friction for command-line users and automation environments, ReliaDL is distributed across major operating system package managers:
+
+| Package Manager | Platform | Command |
+| :--- | :--- | :--- |
+| **Homebrew** | macOS (Apple Silicon & Intel) / Linux | `brew install pxa-labs/tap/reliadl` |
+| **Windows Package Manager (WinGet)** | Windows 10 & 11 (x64) | `winget install PxA-Labs.ReliaDL` |
+| **Scoop** | Windows (x64) | `scoop bucket add pxa-labs https://github.com/PxA-Labs/scoop-bucket`<br>`scoop install reliadl` |
+| **Debian / Ubuntu (.deb)** | Linux (`amd64`, `arm64`) | `sudo apt install ./reliadl_0.3.0_amd64.deb` |
+| **RHEL / Fedora / CentOS (.rpm)** | Linux (`x86_64`, `aarch64`) | `sudo dnf install ./reliadl-0.3.0-1.x86_64.rpm` |
+
+---
+
+## 2. Homebrew (macOS & Linux)
+
+ReliaDL maintains an official Homebrew tap repository at `PxA-Labs/homebrew-tap`.
+
+### Quick Installation
+
+```bash
+# Add custom tap and install ReliaDL
+brew tap pxa-labs/tap
+brew install reliadl
+
+# Or in a single one-liner
+brew install pxa-labs/tap/reliadl
+```
+
+### Verification & Upgrade
+
+```bash
+reliadl --version
+brew upgrade reliadl
+```
+
+---
+
+## 3. Windows Package Managers
+
+### 3.1 WinGet (Official Microsoft Community Repository)
+
+WinGet manifests are hosted in the `microsoft/winget-pkgs` catalog under package ID `PxA-Labs.ReliaDL`.
+
+```powershell
+# Search for ReliaDL
+winget search PxA-Labs.ReliaDL
+
+# Install portable binary
+winget install PxA-Labs.ReliaDL
+
+# Update to latest version
+winget upgrade PxA-Labs.ReliaDL
+```
+
+### 3.2 Scoop (Command-Line Installer for Windows)
+
+```powershell
+# Add PxA-Labs Scoop bucket
+scoop bucket add pxa-labs https://github.com/PxA-Labs/scoop-bucket
+
+# Install ReliaDL
+scoop install reliadl
+
+# Update
+scoop update reliadl
+```
+
+---
+
+## 4. Linux Native Packages (.deb & .rpm)
+
+Pre-built native package archives are built using `nFPM` during GitHub Actions CI/CD and attached to every [GitHub Release](https://github.com/PxA-Labs/ReliaDL/releases).
+
+### 4.1 Debian / Ubuntu (.deb)
+
+```bash
+# Download the .deb package for your architecture
+curl -LO https://github.com/PxA-Labs/ReliaDL/releases/latest/download/reliadl_0.3.0_amd64.deb
+
+# Install via apt (automatically resolves system dependencies)
+sudo apt install ./reliadl_0.3.0_amd64.deb
+
+# Verify installation
+reliadl --version
+```
+
+### 4.2 Fedora / RHEL / Rocky Linux / openSUSE (.rpm)
+
+```bash
+# Download the .rpm package for your architecture
+curl -LO https://github.com/PxA-Labs/ReliaDL/releases/latest/download/reliadl-0.3.0-1.x86_64.rpm
+
+# Install via dnf / zypper
+sudo dnf install ./reliadl-0.3.0-1.x86_64.rpm
+
+# Verify installation
+reliadl --version
+```
+
+---
+
+## 5. Automated CI/CD Packaging Pipeline
+
+Packaging is managed by `.github/workflows/packages.yml`:
+1. **Validation**: Validates Ruby syntax for Homebrew formulas and YAML/JSON schemas for WinGet, Scoop, and nFPM.
+2. **Build**: Compiles standalone binaries for `amd64` and `arm64`, and packages them into `.deb` and `.rpm` containers via `nFPM`.
+3. **Publishing**: Automatically calculates cryptographic SHA-256 sums and attaches `.deb` and `.rpm` files directly to GitHub Releases.

mkdocs.yml

@@ -98,8 +98,11 @@ nav:
     - Project Overview: PROJECT_OVERVIEW.md
     - User Guide: USER_GUIDE.md
     - FAQ: FAQ.md
-  - CLI Reference:
+  - CLI & Deployment:
     - CLI Guide: CLI_GUIDE.md
+    - Standalone Executables: BINARIES.md
+    - System Package Managers: PACKAGES.md
+    - Docker Container: DOCKER.md
     - Deployment Guide: DEPLOYMENT_GUIDE.md
   - Architecture:
     - System Architecture: ARCHITECTURE.md