ghud 0.1.0__tar.gz

ghud-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest -v --tb=short

ghud-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,47 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

ghud-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+docs/_build/
+*.egg
+.venv/

ghud-0.1.0/.readthedocs.yaml

@@ -0,0 +1,16 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

ghud-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Teague Sterling
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ghud-0.1.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: ghud
+Version: 0.1.0
+Summary: GitHub Heads-Up Display — terminal dashboard for your portfolio repos
+Project-URL: Homepage, https://github.com/teaguesterling/ghud
+Project-URL: Documentation, https://ghud.readthedocs.io
+Project-URL: Repository, https://github.com/teaguesterling/ghud
+Project-URL: Issues, https://github.com/teaguesterling/ghud/issues
+Author-email: Teague Sterling <teague@teaguesterling.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,dashboard,github,rich,terminal
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.10
+Requires-Dist: rich>=13.0
+Requires-Dist: ruamel-yaml>=0.18
+Provides-Extra: dev
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: myst-parser; extra == 'docs'
+Requires-Dist: sphinx-rtd-theme; extra == 'docs'
+Requires-Dist: sphinx>=7.0; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# ghud
+
+**GitHub Heads-Up Display** — a terminal dashboard for your portfolio repos.
+
+[![PyPI version](https://img.shields.io/pypi/v/ghud)](https://pypi.org/project/ghud/)
+[![Documentation](https://readthedocs.org/projects/ghud/badge/?version=latest)](https://ghud.readthedocs.io)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+ghud gives you a single-command overview of your GitHub activity:
+
+- **Important notifications** — review requests, mentions, assignments
+- **Your open PRs** — with age and comment counts
+- **Recently merged PRs** — what shipped this week
+- **Issues from others** — on your portfolio repos
+- **Other activity** — repos outside your portfolio
+
+Plus a `discover` command to find repos missing from your portfolio config.
+
+## Installation
+
+```bash
+pip install ghud
+```
+
+Requires the [GitHub CLI](https://cli.github.com/) (`gh`) to be installed and authenticated.
+
+## Quick Start
+
+```bash
+# Show your dashboard
+ghud
+
+# Include low-priority notifications
+ghud --all
+
+# Extend merged-PR lookback to 30 days
+ghud --days 30
+
+# Find repos not yet in your portfolio config
+ghud discover --dry-run
+```
+
+## Configuration
+
+ghud reads a `projects.yaml` file that lists your portfolio repos. It checks these locations:
+
+1. `~/Projects/pages/src/_data/projects.yaml`
+2. `/mnt/aux-data/teague/Projects/pages/src/_data/projects.yaml`
+
+The YAML uses a nested category/subcategory/project structure. Repos in the `ignored` category are excluded from the dashboard.
+
+## Features
+
+### Responsive Layout
+
+On wide terminals (>=120 columns), ghud uses a two-column layout:
+- **Left:** things needing your attention (notifications, issues from others)
+- **Right:** your activity (open PRs, recently merged)
+
+Narrow terminals get a single-column stack.
+
+### Notification Filtering
+
+By default, ghud shows only important notifications: `review_requested`, `mention`, `assign`, `team_mention`, `security_alert`. Use `--all` to include subscribed/comment notifications.
+
+### Repo Discovery
+
+`ghud discover` queries your GitHub account for all repos and compares against your `projects.yaml`. New repos are listed (with `--dry-run`) or added to an `uncategorized` section for you to organize.
+
+### Performance
+
+ghud fetches all data in ~2 seconds using concurrent API calls and GraphQL batching for per-repo issue queries.
+
+## Development
+
+```bash
+git clone https://github.com/teaguesterling/ghud.git
+cd ghud
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

ghud-0.1.0/README.md

@@ -0,0 +1,85 @@
+# ghud
+
+**GitHub Heads-Up Display** — a terminal dashboard for your portfolio repos.
+
+[![PyPI version](https://img.shields.io/pypi/v/ghud)](https://pypi.org/project/ghud/)
+[![Documentation](https://readthedocs.org/projects/ghud/badge/?version=latest)](https://ghud.readthedocs.io)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+ghud gives you a single-command overview of your GitHub activity:
+
+- **Important notifications** — review requests, mentions, assignments
+- **Your open PRs** — with age and comment counts
+- **Recently merged PRs** — what shipped this week
+- **Issues from others** — on your portfolio repos
+- **Other activity** — repos outside your portfolio
+
+Plus a `discover` command to find repos missing from your portfolio config.
+
+## Installation
+
+```bash
+pip install ghud
+```
+
+Requires the [GitHub CLI](https://cli.github.com/) (`gh`) to be installed and authenticated.
+
+## Quick Start
+
+```bash
+# Show your dashboard
+ghud
+
+# Include low-priority notifications
+ghud --all
+
+# Extend merged-PR lookback to 30 days
+ghud --days 30
+
+# Find repos not yet in your portfolio config
+ghud discover --dry-run
+```
+
+## Configuration
+
+ghud reads a `projects.yaml` file that lists your portfolio repos. It checks these locations:
+
+1. `~/Projects/pages/src/_data/projects.yaml`
+2. `/mnt/aux-data/teague/Projects/pages/src/_data/projects.yaml`
+
+The YAML uses a nested category/subcategory/project structure. Repos in the `ignored` category are excluded from the dashboard.
+
+## Features
+
+### Responsive Layout
+
+On wide terminals (>=120 columns), ghud uses a two-column layout:
+- **Left:** things needing your attention (notifications, issues from others)
+- **Right:** your activity (open PRs, recently merged)
+
+Narrow terminals get a single-column stack.
+
+### Notification Filtering
+
+By default, ghud shows only important notifications: `review_requested`, `mention`, `assign`, `team_mention`, `security_alert`. Use `--all` to include subscribed/comment notifications.
+
+### Repo Discovery
+
+`ghud discover` queries your GitHub account for all repos and compares against your `projects.yaml`. New repos are listed (with `--dry-run`) or added to an `uncategorized` section for you to organize.
+
+### Performance
+
+ghud fetches all data in ~2 seconds using concurrent API calls and GraphQL batching for per-repo issue queries.
+
+## Development
+
+```bash
+git clone https://github.com/teaguesterling/ghud.git
+cd ghud
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

ghud-0.1.0/docs/api.rst

@@ -0,0 +1,17 @@
+API Reference
+=============
+
+.. automodule:: ghud.config
+   :members:
+
+.. automodule:: ghud.github
+   :members:
+
+.. automodule:: ghud.dashboard
+   :members:
+
+.. automodule:: ghud.discover
+   :members:
+
+.. automodule:: ghud.cli
+   :members:

ghud-0.1.0/docs/conf.py

@@ -0,0 +1,21 @@
+"""Sphinx configuration for ghud documentation."""
+
+project = "ghud"
+copyright = "2026, Teague Sterling"
+author = "Teague Sterling"
+release = "0.1.0"
+
+extensions = [
+    "myst_parser",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build"]
+
+html_theme = "sphinx_rtd_theme"
+
+myst_enable_extensions = [
+    "colon_fence",
+]

ghud-0.1.0/docs/index.rst

@@ -0,0 +1,27 @@
+ghud — GitHub Heads-Up Display
+==============================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   installation
+   usage
+   api
+
+ghud gives you a single-command overview of your GitHub activity across all your portfolio repos.
+
+.. code-block:: bash
+
+   $ ghud
+
+Features
+--------
+
+- Important notifications (review requests, mentions, assignments)
+- Your open PRs with age and comment counts
+- Recently merged PRs
+- Issues from others on your portfolio repos
+- Repo discovery to keep your portfolio config complete
+- Responsive two-column layout on wide terminals
+- Fast: ~2 seconds using GraphQL batching

ghud-0.1.0/docs/installation.rst

@@ -0,0 +1,31 @@
+Installation
+============
+
+Requirements
+------------
+
+- Python 3.10+
+- `GitHub CLI <https://cli.github.com/>`_ (``gh``) installed and authenticated
+
+From PyPI
+---------
+
+.. code-block:: bash
+
+   pip install ghud
+
+From Source
+-----------
+
+.. code-block:: bash
+
+   git clone https://github.com/teaguesterling/ghud.git
+   cd ghud
+   pip install -e ".[dev]"
+
+Verify
+------
+
+.. code-block:: bash
+
+   ghud --help

ghud-0.1.0/docs/usage.rst

@@ -0,0 +1,54 @@
+Usage
+=====
+
+Dashboard
+---------
+
+.. code-block:: bash
+
+   # Show your dashboard (default)
+   ghud
+
+   # Include low-priority notifications (subscribed, comment, etc.)
+   ghud --all
+
+   # Extend merged-PR lookback to 30 days
+   ghud --days 30
+
+The dashboard shows five sections (empty sections are hidden):
+
+1. **Important Notifications** — review_requested, mention, assign, team_mention, security_alert
+2. **New Issues From Others** — open issues on your portfolio repos, excluding your own
+3. **Your Open PRs** — PRs you authored, with age and comment counts
+4. **Recently Merged** — your PRs merged within the lookback window
+5. **Other Activity** — notifications from repos not in your portfolio
+
+On wide terminals (>=120 columns), sections are arranged in two columns:
+attention-needed on the left, your activity on the right.
+
+Discover
+--------
+
+.. code-block:: bash
+
+   # See what repos are missing from your portfolio config
+   ghud discover --dry-run
+
+   # Add missing repos to the 'uncategorized' section
+   ghud discover
+
+The discover command queries your GitHub account for all repos and compares
+against your ``projects.yaml``. New repos are added to an ``uncategorized``
+section for you to organize later.
+
+Configuration
+-------------
+
+ghud reads a ``projects.yaml`` file that lists your portfolio repos.
+It checks these locations in order:
+
+1. ``~/Projects/pages/src/_data/projects.yaml``
+2. ``/mnt/aux-data/teague/Projects/pages/src/_data/projects.yaml``
+
+The YAML uses a nested ``categories -> subcategories -> projects`` structure.
+Repos in the ``ignored`` category are excluded from the dashboard.

ghud-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ghud"
+version = "0.1.0"
+description = "GitHub Heads-Up Display — terminal dashboard for your portfolio repos"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Teague Sterling", email = "teague@teaguesterling.com" },
+]
+keywords = ["github", "dashboard", "terminal", "cli", "rich"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Version Control :: Git",
+]
+dependencies = [
+    "rich>=13.0",
+    "ruamel.yaml>=0.18",
+]
+
+[project.scripts]
+ghud = "ghud.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/teaguesterling/ghud"
+Documentation = "https://ghud.readthedocs.io"
+Repository = "https://github.com/teaguesterling/ghud"
+Issues = "https://github.com/teaguesterling/ghud/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov",
+]
+docs = [
+    "sphinx>=7.0",
+    "sphinx-rtd-theme",
+    "myst-parser",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ghud"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

ghud-0.1.0/src/ghud/__init__.py

@@ -0,0 +1,3 @@
+"""ghud — GitHub Heads-Up Display."""
+
+__version__ = "0.1.0"

ghud-0.1.0/src/ghud/cli.py

@@ -0,0 +1,110 @@
+"""CLI argument parsing and command dispatch."""
+
+import argparse
+import sys
+from concurrent.futures import ThreadPoolExecutor
+
+from ghud.config import find_yaml_path, load_repos_from_yaml
+from ghud.github import (
+    get_username,
+    get_notifications,
+    get_open_prs,
+    get_merged_prs,
+    get_issues_for_repos_batch,
+)
+from ghud.dashboard import render_dashboard
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="ghud",
+        description="GitHub Heads-Up Display — terminal dashboard for your portfolio repos",
+    )
+    parser.add_argument("--all", action="store_true", help="Include all notifications")
+    parser.add_argument("--days", type=int, default=7, help="Lookback days for merged PRs")
+
+    subparsers = parser.add_subparsers(dest="command")
+
+    discover_parser = subparsers.add_parser("discover", help="Discover new repos")
+    discover_parser.add_argument("--dry-run", action="store_true", help="Show changes without writing")
+
+    return parser.parse_args(argv)
+
+
+def _collect_other_activity(
+    notifications: list[dict], portfolio_repos: set[str]
+) -> tuple[list[dict], list[dict]]:
+    """Split notifications into portfolio and other activity.
+
+    Returns (portfolio_notifications, other_activity_summary).
+    """
+    portfolio = []
+    other: dict[str, dict] = {}
+
+    for n in notifications:
+        repo = n.get("repository", {}).get("full_name", "")
+        if repo in portfolio_repos:
+            portfolio.append(n)
+        else:
+            if repo not in other:
+                other[repo] = {"repo": repo, "count": 0, "reason_set": set()}
+            other[repo]["count"] += 1
+            other[repo]["reason_set"].add(n.get("reason", "unknown"))
+
+    other_summary = [
+        {"repo": v["repo"], "count": v["count"], "reasons": ", ".join(sorted(v["reason_set"]))}
+        for v in sorted(other.values(), key=lambda x: x["count"], reverse=True)
+    ]
+    return portfolio, other_summary
+
+
+def run_dashboard(args: argparse.Namespace) -> None:
+    yaml_path = find_yaml_path()
+    if not yaml_path:
+        print("Error: Could not find projects.yaml", file=sys.stderr)
+        sys.exit(1)
+
+    repos = load_repos_from_yaml(yaml_path)
+    portfolio_set = set(repos)
+    username = get_username()
+
+    if not username:
+        print("Error: Could not determine GitHub username. Run 'gh auth login'.", file=sys.stderr)
+        sys.exit(1)
+
+    # Fetch all data concurrently: notifications, PRs, merged PRs, and issues
+    with ThreadPoolExecutor(max_workers=4) as pool:
+        notif_future = pool.submit(get_notifications)
+        prs_future = pool.submit(get_open_prs, username)
+        merged_future = pool.submit(get_merged_prs, username, args.days)
+        issues_future = pool.submit(get_issues_for_repos_batch, repos, username)
+
+        all_notifications = notif_future.result()
+        open_prs = prs_future.result()
+        merged_prs = merged_future.result()
+        other_issues = issues_future.result()
+        other_issues.sort(key=lambda x: x.get("createdAt", ""), reverse=True)
+
+    portfolio_notifications, other_activity = _collect_other_activity(
+        all_notifications, portfolio_set
+    )
+
+    data = {
+        "notifications": portfolio_notifications,
+        "open_prs": open_prs,
+        "merged_prs": merged_prs,
+        "other_issues": other_issues,
+        "other_activity": other_activity,
+    }
+
+    render_dashboard(data, show_all=args.all)
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = parse_args(argv)
+
+    if args.command == "discover":
+        from ghud.discover import run_discover
+        run_discover(args)
+    else:
+        run_dashboard(args)