Cross-Platform Support

.github/workflows/build.yml

@@ -0,0 +1,48 @@
+# .github/workflows/build.yml
+name: Build Binaries
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v4
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Build binary
+        run: uv run pyinstaller hubfetch.spec
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: hubfetch-${{ matrix.os }}
+          path: dist/hubfetch*
+
+  release:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: artifacts/
+          merge-multiple: true
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: artifacts/*
+          generate_release_notes: true

.github/ci.yml → .github/workflows/ci.yml

@@ -18,7 +18,6 @@ jobs:
         uses: astral-sh/setup-uv@v5
         with:
           enable-cache: true # cache is nice
-          python-version: "3.10"
 
       - name: Install dependencies
         run: |

.gitignore

@@ -4,4 +4,8 @@
 
 # fucking cache
 /.ruff_cache
-/__pycache__/
+/__pycache__/ 
+
+# build files
+dist/
+build/

CONTRIBUTING.md

@@ -0,0 +1,78 @@
+# Contributing
+
+Thanks for even considering to contribute to hubfetch!
+
+## Dev Setup
+
+- Python 3.14+
+- A GitHub Personal Access Token (needed to actually run the tool during development)
+- [chafa](https://hpjansson.org/chafa/) installed for testing image rendering fallback
+
+This project uses [uv](https://github.com/astral-sh/uv) as its package manager. After installing uv, run:
+
+```bash
+uv sync
+```
+
+This picks up all required dependencies from the lock file. To run the tool locally during development:
+
+```bash
+uv run hubfetch
+```
+
+## Quality Assurance
+
+Before opening a PR:
+
+- Run unit tests:
+
+```bash
+uv run pytest
+```
+
+- Format the codebase with Ruff:
+
+```bash
+uv run ruff format .
+```
+
+- Lint the codebase:
+
+```bash
+uv run ruff check .
+```
+
+- Keep functions small and documented with docstrings.
+- If your change touches the GitHub API integration, make sure it works with both authenticated and unauthenticated states.
+
+## Building Locally
+
+To test the PyInstaller binary build locally:
+
+```bash
+uv run pyinstaller hubfetch.spec
+./dist/hubfetch
+```
+
+## Packaging
+
+This project is **NOT A MONO-REPO**
+
+Packaging files are mirrored under `contrib/` for reference only. The canonical sources are:
+
+| Package Manager | Canonical Source |
+|---|---|
+| Homebrew | [`PranavU-Coder/homebrew-tap`](https://github.com/PranavU-Coder/homebrew-tap) |
+| AUR | `ssh://aur@aur.archlinux.org/hubfetch.git` |
+| Scoop | [`PranavU-Coder/scoop-bucket`](https://github.com/PranavU-Coder/scoop-bucket) |
+
+If you're fixing a packaging issue, open the PR in the appropriate repo above, not here.
+
+## Reporting Issues
+
+When reporting an issue, please include:
+
+- OS + Python version
+- Terminal emulator (matters for kitty graphics protocol support)
+- The exact command you ran
+- The full error output or a screenshot of the terminal

README.md

@@ -27,8 +27,7 @@ Don't worry if your favorite terminal doesn't support kitty's graphics protocol
 ![Alt](./assets/preview-1.png)
 ![Alt](./assets/preview-2.png)
 ![Alt](./assets/config.png)
-
-https://github.com/user-attachments/assets/9d06be44-fa36-4e24-bdee-a29838a801c3
+![Alt](./assets/first_time.gif)
 
 </details>
 
@@ -44,7 +43,13 @@ https://github.com/user-attachments/assets/9d06be44-fa36-4e24-bdee-a29838a801c3
     * **Stats Cache:** Keeps your GitHub data fresh with a 1-hour expiration to minimize API calls and maximizes speed.
 * **Dynamic Customization**: Fully configurable via `~/.config/hubfetch/config.json` as discussed earlier. Toggle individual fields, adjust image dimensions, or customize the entire color palette with bold and italic Rich styles.
 * **Secure Authentication**: Dedicated `auth` command to securely handle GitHub Personal Access Tokens (PAT) and verify credentials before setup.
-* **Modern CLI Experience** – Built with `Click` for a seamless command-line interface and `Rich` for beautiful, side-by-side terminal layouts.
+* **Modern CLI Experience**: Built with `Click` for a seamless command-line interface and `Rich` for beautiful, side-by-side terminal layouts.
+
+## Dependencies
+
+**[Chafa](https://hpjansson.org/chafa/)** (Highly Recommended): Used as the primary fallback for terminals that do not support the Kitty graphics protocol. It converts your GitHub avatar into high-quality ANSI symbols/block art.
+
+While the script does attempt to install in case terminal emulator appears to not support Kitty's graphics protocol, it is highly recommended to install manually in the event that chafa installation fails.
 
 ## Installation
 
@@ -64,22 +69,22 @@ https://github.com/user-attachments/assets/9d06be44-fa36-4e24-bdee-a29838a801c3
 
 ## Future
 
-Discussed in [[placeholder text till I make it public]]
+Discussed in [discussions](https://github.com/PranavU-Coder/hubfetch/discussions)
 
 All features/bug-fixes being implemented can be visible in the [roadmap](https://github.com/users/PranavU-Coder/projects/11)
 
-A rich issue-template to raise all required changes.
+A rich [issue-template](https://github.com/PranavU-Coder/hubfetch/issues) to raise all required changes.
 
 ## License
 
 [MIT](https://github.com/PranavU-Coder/hubfetch?tab=MIT-1-ov-file)
 
 ## Other
 
-<a href="https://star-history.com/#PranavU-Coder/hubfetch&Date">
+<a href="https://www.star-history.com/?repos=PranavU-Coder%2Fhubfetch&type=date&legend=top-left">
  <picture>
-   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=PranavU-Coder/hubfetch&type=Date&theme=dark" />
-   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=PranavU-Coder/hubfetch&type=Date" />
-   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=PranavU-Coder/hubfetch&type=Date" />
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=PranavU-Coder/hubfetch&type=date&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=PranavU-Coder/hubfetch&type=date&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=PranavU-Coder/hubfetch&type=date&legend=top-left" />
  </picture>
 </a>

contrib/aur/PKGBUILD

@@ -0,0 +1,23 @@
+# Mirror only. Canonical source: ssh://aur@aur.archlinux.org/hubfetch.git
+# Maintainer: Pranav pranavu8406@gmail.com
+pkgname=hubfetch
+pkgver=1.0.0
+pkgrel=1
+pkgdesc="A CLI ricing tool designed to fetch GitHub user stats"
+arch=('any')
+url="https://github.com/PranavU-Coder/hubfetch"
+license=('MIT')
+depends=('python' 'python-click' 'python-requests' 'python-rich')
+makedepends=('python-build' 'python-installer' 'python-wheel' 'python-hatchling')
+source=("https://files.pythonhosted.org/packages/source/h/hubfetch/hubfetch-$pkgver.tar.gz")
+sha256sums=('9fbcf5e1abf22d7b64f4b99b09131607d1b6fa408c6ef2322d73eb8f83ea84f1')
+
+build() {
+  cd "hubfetch-$pkgver"
+  python -m build --wheel --no-isolation
+}
+
+package() {
+  cd "hubfetch-$pkgver"
+  python -m installer --destdir="$pkgdir" dist/*.whl
+}

contrib/homebrew/homebrew.rb

@@ -0,0 +1,70 @@
+# Mirror only. Canonical source: https://github.com/PranavU-Coder/homebrew-tap
+class Hubfetch < Formula
+  include Language::Python::Virtualenv
+
+  desc "Python CLI tool to check GitHub stats via terminal"
+  homepage "https://github.com/PranavU-Coder/hubfetch"
+  url "https://files.pythonhosted.org/packages/70/58/1fbe435900dfaea8a0fd66c28a85604d8f91c09a53d7baf97ac02a88e367/hubfetch-1.0.0.tar.gz"
+  sha256 "9fbcf5e1abf22d7b64f4b99b09131607d1b6fa408c6ef2322d73eb8f83ea84f1"
+  license "MIT"
+
+  depends_on "python@3.14"
+
+  resource "certifi" do
+    url "https://files.pythonhosted.org/packages/af/2d/7bf41579a8986e348fa033a31cdd0e4121114f6bce2457e8876010b092dd/certifi-2026.2.25.tar.gz"
+    sha256 "e887ab5cee78ea814d3472169153c2d12cd43b14bd03329a39a9c6e2e80bfba7"
+  end
+
+  resource "charset-normalizer" do
+    url "https://files.pythonhosted.org/packages/e7/a1/67fe25fac3c7642725500a3f6cfe5821ad557c3abb11c9d20d12c7008d3e/charset_normalizer-3.4.7.tar.gz"
+    sha256 "ae89db9e5f98a11a4bf50407d4363e7b09b31e55bc117b4f7d80aab97ba009e5"
+  end
+
+  resource "click" do
+    url "https://files.pythonhosted.org/packages/3d/fa/656b739db8587d7b5dfa22e22ed02566950fbfbcdc20311993483657a5c0/click-8.3.1.tar.gz"
+    sha256 "12ff4785d337a1bb490bb7e9c2b1ee5da3112e94a8622f26a6c77f5d2fc6842a"
+  end
+
+  resource "idna" do
+    url "https://files.pythonhosted.org/packages/6f/6d/0703ccc57f3a7233505399edb88de3cbd678da106337b9fcde432b65ed60/idna-3.11.tar.gz"
+    sha256 "795dafcc9c04ed0c1fb032c2aa73654d8e8c5023a7df64a53f39190ada629902"
+  end
+
+  resource "markdown-it-py" do
+    url "https://files.pythonhosted.org/packages/5b/f5/4ec618ed16cc4f8fb3b701563655a69816155e79e24a17b651541804721d/markdown_it_py-4.0.0.tar.gz"
+    sha256 "cb0a2b4aa34f932c007117b194e945bd74e0ec24133ceb5bac59009cda1cb9f3"
+  end
+
+  resource "mdurl" do
+    url "https://files.pythonhosted.org/packages/d6/54/cfe61301667036ec958cb99bd3efefba235e65cdeb9c84d24a8293ba1d90/mdurl-0.1.2.tar.gz"
+    sha256 "bb413d29f5eea38f31dd4754dd7377d4465116fb207585f97bf925588687c1ba"
+  end
+
+  resource "pygments" do
+    url "https://files.pythonhosted.org/packages/c3/b2/bc9c9196916376152d655522fdcebac55e66de6603a76a02bca1b6414f6c/pygments-2.20.0.tar.gz"
+    sha256 "6757cd03768053ff99f3039c1a36d6c0aa0b263438fcab17520b30a303a82b5f"
+  end
+
+  resource "requests" do
+    url "https://files.pythonhosted.org/packages/5f/a4/98b9c7c6428a668bf7e42ebb7c79d576a1c3c1e3ae2d47e674b468388871/requests-2.33.1.tar.gz"
+    sha256 "18817f8c57c6263968bc123d237e3b8b08ac046f5456bd1e307ee8f4250d3517"
+  end
+
+  resource "rich" do
+    url "https://files.pythonhosted.org/packages/b3/c6/f3b320c27991c46f43ee9d856302c70dc2d0fb2dba4842ff739d5f46b393/rich-14.3.3.tar.gz"
+    sha256 "b8daa0b9e4eef54dd8cf7c86c03713f53241884e814f4e2f5fb342fe520f639b"
+  end
+
+  resource "urllib3" do
+    url "https://files.pythonhosted.org/packages/c7/24/5f1b3bdffd70275f6661c76461e25f024d5a38a46f04aaca912426a2b1d3/urllib3-2.6.3.tar.gz"
+    sha256 "1b62b6884944a57dbe321509ab94fd4d3b307075e0c2eae991ac71ee15ad38ed"
+  end
+
+  def install
+    virtualenv_install_with_resources
+  end
+
+  test do
+    system bin/"hubfetch", "--help"
+  end
+end

contrib/nix/package.nix

@@ -0,0 +1,37 @@
+# mirror [abandoned for the time being]
+{
+  lib,
+  python3,
+  fetchPypi,
+}:
+
+python3.pkgs.buildPythonApplication rec {
+  pname = "hubfetch";
+  version = "1.0.2";
+  pyproject = true;
+
+  src = fetchPypi {
+    inherit pname version;
+    sha256 = "sha256-L31RCunKz4elsGJL02oR1z8In1ge0LZ5RAA9X4jQhHk=";
+  };
+
+  build-system = [
+    python3.pkgs.hatchling
+  ];
+
+  dependencies = [
+    python3.pkgs.click
+    python3.pkgs.requests
+    python3.pkgs.rich
+  ];
+
+  doCheck = false;
+
+  meta = {
+    description = "A CLI ricing tool designed to fetch GitHub user stats";
+    homepage = "https://github.com/PranavU-Coder/hubfetch";
+    license = lib.licenses.mit;
+    maintainers = [ ];
+    mainProgram = "hubfetch";
+  };
+}

hubfetch.spec

@@ -0,0 +1,45 @@
+# -*- mode: python ; coding: utf-8 -*-
+from PyInstaller.utils.hooks import collect_all
+
+datas = []
+binaries = []
+hiddenimports = []
+tmp_ret = collect_all('hubfetch')
+datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
+
+
+a = Analysis(
+    ['main.py'],
+    pathex=[],
+    binaries=binaries,
+    datas=datas,
+    hiddenimports=hiddenimports,
+    hookspath=[],
+    hooksconfig={},
+    runtime_hooks=[],
+    excludes=[],
+    noarchive=False,
+    optimize=0,
+)
+pyz = PYZ(a.pure)
+
+exe = EXE(
+    pyz,
+    a.scripts,
+    a.binaries,
+    a.datas,
+    [],
+    name='hubfetch',
+    debug=False,
+    bootloader_ignore_signals=False,
+    strip=False,
+    upx=True,
+    upx_exclude=[],
+    runtime_tmpdir=None,
+    console=True,
+    disable_windowed_traceback=False,
+    argv_emulation=False,
+    target_arch=None,
+    codesign_identity=None,
+    entitlements_file=None,
+)

hubfetch/__init__.py

@@ -1,5 +1,3 @@
 from hubfetch import config
-from hubfetch.api import GitHubClient
-from hubfetch.display import render
 
-__all__ = ["config", "GitHubClient", "render"]
+__all__ = ["config"]