recon-github 0.1.0__py3-none-any.whl

app/cli.py

@@ -0,0 +1,13 @@
+import typer
+
+from app.commands import auth, me, repo
+
+app = typer.Typer()
+
+# Commands that can be ran in the CLI
+app.command(name="login")(auth.login)
+app.command(name="logout")(auth.logout)
+app.command(name="me")(me.me)
+app.command(name="scout")(me.scout)
+app.command(name="list")(repo.list)
+app.command(name="details")(repo.details)

app/commands/auth.py

@@ -0,0 +1,17 @@
+import typer
+
+from app.services import auth
+
+app = typer.Typer()
+
+
+@app.command()
+def login():
+    """Login to GitHub using the device flow."""
+    auth.login()
+
+
+@app.command()
+def logout():
+    """Logout of GitHub."""
+    auth.logout()

app/commands/me.py

@@ -0,0 +1,23 @@
+import typer
+
+from app.ui.display import display_user
+
+app = typer.Typer()
+
+
+@app.command()
+def me():
+    """Get information about me!"""
+    from app.services.github import get_authenticated_user
+
+    user = get_authenticated_user()
+    display_user(user)
+
+
+@app.command()
+def scout(user: str):
+    """Scout another GitHub user."""
+    from app.services.github import get_user
+
+    profile = get_user(user)
+    display_user(profile)

app/commands/repo.py

@@ -0,0 +1,202 @@
+from builtins import list as builtins_list
+from typing import cast
+
+import typer
+
+app = typer.Typer()
+
+units = ["KB", "MB", "GB", "TB", "PB"]
+
+
+def format_topics(topics: list[str], max_topics: int = 5) -> str:
+    shown = topics[:max_topics]
+    remaining = len(topics) - len(shown)
+    rendered = ", ".join(shown)
+    if remaining > 0:
+        rendered = f"{rendered} + {remaining} more..."
+    return rendered
+
+
+def format_description(description: str, max_chars: int = 90) -> str:
+    if len(description) <= max_chars:
+        return description
+
+    # Truncate at or after max_chars, but never in the middle of a word.
+    cutoff = description.find(" ", max_chars)
+    if cutoff == -1:
+        cutoff = max_chars
+
+    shown = description[:cutoff].rstrip()
+    return f"{shown}..."
+
+
+def format_size(size: int) -> str:
+    units = ["KB", "MB", "GB", "TB", "PB"]
+
+    current_unit = 0
+    scaled_size: float = size
+
+    while scaled_size >= 1000 and current_unit < len(units) - 1:
+        scaled_size = scaled_size / 1000
+        current_unit += 1
+
+    return f"{scaled_size:.1f} {units[current_unit]}"
+
+
+def format_languages(languages: dict[str, int], max_languages: int = 5) -> list[str]:
+    if not languages:
+        return ["No language data returned."]
+
+    total_bytes = sum(languages.values())
+
+    sorted_languages = sorted(languages.items(), key=lambda item: item[1], reverse=True)
+
+    shown = sorted_languages[:max_languages]
+    remaining = len(sorted_languages) - len(shown)
+
+    formatted = []
+
+    for language, byte_count in shown:
+        percent = (byte_count / total_bytes * 100) if total_bytes else 0
+        formatted.append(f"{language}: {percent:.1f}%")
+
+    if remaining > 0:
+        formatted.append(f"+ {remaining} more...")
+
+    return formatted
+
+
+@app.command()
+def list():
+    """See a list of all your repos."""
+    from app.services.github import get_user_repos
+
+    repos = get_user_repos()
+
+    for repo in repos:
+        typer.echo(f"{repo['full_name']}")
+        description = repo.get("description") or "—"
+        typer.echo(f"description: {format_description(description)}")
+        typer.echo(
+            f"visibility: {repo.get('visibility') or ('private' if repo.get('private') else 'public')}"
+        )
+        typer.echo(f"language: {repo.get('language') or '—'}")
+        typer.echo(f"default branch: {repo.get('default_branch') or '—'}")
+        typer.echo(
+            f"stars: {repo.get('stargazers_count', 0)}  forks: {repo.get('forks_count', 0)}  open issues: {repo.get('open_issues_count', 0)}"
+        )
+        typer.echo(f"  url: {repo['html_url']}")
+
+        topics = repo.get("topics") or []
+        if topics:
+            typer.echo(f"  topics: {format_topics(topics)}")
+
+        typer.echo("")
+
+
+@app.command()
+def details(
+    owner: str = typer.Argument(..., help="Repository owner, e.g. owenpalfreymandev"),
+    repo: str = typer.Argument(..., help="Repository name, e.g. reconcli"),
+    contributors: bool = typer.Option(False, help="View contributors in more detail."),
+    languages: bool = typer.Option(False, help="View language usage in more detail."),
+):
+    """Gain insights into your repo"""
+    if contributors and languages:
+        raise typer.BadParameter("Choose either --contributors or --languages.")
+
+    from app.services.github import (
+        ContributorResults,
+        get_authenticated_user,
+        get_languages,
+        get_repo_details,
+        get_top_contributors,
+    )
+    from app.ui.repo import display_view_header
+
+    details = get_repo_details(owner, repo)
+
+    if languages:
+        from app.ui.repo import display_languages
+
+        display_languages(
+            details.get("full_name", f"{owner}/{repo}"),
+            get_languages(owner, repo),
+        )
+        return
+
+    if contributors:
+        from app.ui.repo import display_contributors
+
+        try:
+            authenticated_user = get_authenticated_user()
+        except RuntimeError:
+            # Contributor statistics remain useful when GitHub cannot identify
+            # the token owner for this request.
+            authenticated_user = {}
+        results = cast(
+            ContributorResults,
+            get_top_contributors(
+                owner,
+                repo,
+                limit=5,
+                current_login=authenticated_user.get("login"),
+                include_metadata=True,
+            ),
+        )
+        display_contributors(
+            details.get("full_name", f"{owner}/{repo}"),
+            results.contributors,
+            results.total_contributors,
+            results.total_commits,
+            authenticated_user.get("login"),
+            results.current_contributor,
+        )
+        return
+
+    language_data = get_languages(owner, repo)
+    contributions = cast(
+        builtins_list[dict[str, str | int | None]],
+        get_top_contributors(owner, repo, limit=5),
+    )
+
+    display_view_header("Details", details.get("full_name", f"{owner}/{repo}"))
+
+    # Repo Details
+    typer.echo("Repository")
+    typer.echo("-----------")
+    typer.echo(f"{details.get('full_name', f'{owner}/{repo}')}")  # Name
+    description = details.get("description") or "—"
+    typer.echo(f"description: {format_description(description)}")  # Description
+    typer.echo(
+        f"visibility: {details.get('visibility') or ('private' if details.get('private') else 'public')}"  # Visibility
+    )
+    typer.echo(
+        f"url: {details.get('html_url') or f'https://github.com/{owner}/{repo}'}"
+    )  # URL
+
+    # Stats
+    typer.echo("")
+    typer.echo("Stats")
+    typer.echo("-----------")
+    typer.echo(f"stars: {details.get('stargazers_count') or 0}")  # Stars
+    typer.echo(f"forks: {details.get('forks_count')}")  # Forks
+    typer.echo(f"issues: {details.get('open_issues_count') or 0}")  # Issues
+    typer.echo(f"size: {format_size(details.get('size'))}")  # Size
+
+    typer.echo("")
+    typer.echo("Contributions")
+    typer.echo("-----------")
+    if not contributions:
+        typer.echo("No contributor data returned.")
+    else:
+        for contributor in contributions:
+            typer.echo(f"{contributor['login']}: {contributor['commits']} commits")
+
+    # Tech
+    typer.echo("")
+    typer.echo("Languages")
+    typer.echo("---------")
+
+    for language in format_languages(language_data):
+        typer.echo(language)

app/services/auth.py

@@ -0,0 +1,79 @@
+import os
+import time
+import webbrowser
+
+import requests
+from dotenv import load_dotenv
+
+from app.services.storage import clear_token, save_token
+
+load_dotenv()
+
+CLIENT_ID = os.getenv("GITHUB_CLIENT_ID")
+
+DEVICE_CODE_URL = "https://github.com/login/device/code"
+TOKEN_URL = "https://github.com/login/oauth/access_token"
+
+
+def login():
+    if not CLIENT_ID:
+        raise RuntimeError("Missing GITHUB_CLIENT_ID in .env")
+
+    device = request_device_code()
+
+    print("Opening GitHub authentication...")
+
+    webbrowser.open(device.get("verification_uri_complete", device["verification_uri"]))
+
+    print(f"If required, enter code: {device['user_code']}")
+
+    token = poll_for_token(device)
+
+    save_token(token)
+
+    print("Successfully logged into GitHub!")
+
+
+def request_device_code():
+    response = requests.post(
+        DEVICE_CODE_URL,
+        headers={"Accept": "application/json"},
+        data={"client_id": CLIENT_ID, "scope": "read:user repo"},
+        timeout=10,
+    )
+
+    response.raise_for_status()
+
+    return response.json()
+
+
+def poll_for_token(device):
+    interval = device.get("interval", 5)
+
+    while True:
+        response = requests.post(
+            TOKEN_URL,
+            headers={"Accept": "application/json"},
+            data={
+                "client_id": CLIENT_ID,
+                "device_code": device["device_code"],
+                "grant_type": ("urn:ietf:params:oauth:grant-type:device_code"),
+            },
+            timeout=10,
+        )
+
+        data = response.json()
+
+        if "access_token" in data:
+            return data["access_token"]
+
+        if data.get("error") != "authorization_pending":
+            raise RuntimeError(data)
+
+        time.sleep(interval)
+
+
+def logout():
+    clear_token()
+
+    print("Successfully logged out of GitHub!")

app/services/github.py

@@ -0,0 +1,184 @@
+import time
+from dataclasses import dataclass
+from urllib.parse import quote
+
+import requests
+
+from app.services.github_errors import (
+    github_headers,
+    raise_for_github_error,
+)
+from app.services.storage import get_token
+
+GITHUB_API = "https://api.github.com"
+
+TOP_CONTRIBUTORS = 10
+STATS_POLL_ATTEMPTS = 5
+STATS_POLL_INTERVAL_SECONDS = 1
+
+
+@dataclass
+class ContributorResults:
+    """Top contributor rows plus metadata from GitHub's statistics response."""
+
+    contributors: list[dict[str, str | int | None]]
+    total_contributors: int
+    total_commits: int
+    current_contributor: dict[str, str | int | None] | None = None
+
+
+def _get_auth_headers():
+    token = get_token()
+
+    if not token:
+        raise RuntimeError("Not authenticated with GitHub. Run `auth login`.")
+
+    return github_headers(token)
+
+
+def get_authenticated_user():
+    response = requests.get(
+        f"{GITHUB_API}/user",
+        headers=_get_auth_headers(),
+        timeout=10,
+    )
+
+    raise_for_github_error(response)
+
+    return response.json()
+
+
+def get_user(username: str):
+    """Return a GitHub user's public profile."""
+    if not username:
+        raise ValueError("username must not be empty")
+
+    response = requests.get(
+        f"{GITHUB_API}/users/{quote(username, safe='')}",
+        headers=_get_auth_headers(),
+        timeout=10,
+    )
+
+    raise_for_github_error(response)
+
+    return response.json()
+
+
+def get_user_repos():
+    response = requests.get(
+        f"{GITHUB_API}/user/repos",
+        headers=_get_auth_headers(),
+        timeout=10,
+    )
+
+    raise_for_github_error(response)
+
+    return response.json()
+
+
+def get_repo_details(owner: str, repo: str):
+    response = requests.get(
+        f"{GITHUB_API}/repos/{owner}/{repo}",
+        headers=_get_auth_headers(),
+        timeout=10,
+    )
+
+    raise_for_github_error(response)
+
+    return response.json()
+
+
+def get_languages(owner: str, repo: str):
+    response = requests.get(
+        f"{GITHUB_API}/repos/{owner}/{repo}/languages",
+        headers=_get_auth_headers(),
+        timeout=10,
+    )
+
+    raise_for_github_error(response)
+
+    return response.json()
+
+
+def get_top_contributors(
+    owner: str,
+    repo: str,
+    limit: int = TOP_CONTRIBUTORS,
+    current_login: str | None = None,
+    include_metadata: bool = False,
+) -> list[dict[str, str | int | None]] | ContributorResults:
+    """
+    Return contributors ranked by commit count.
+
+    GitHub may return 202 while it calculates statistics,
+    so we retry until the data is available.
+    """
+
+    if limit < 1:
+        raise ValueError("limit must be at least 1")
+
+    url = f"{GITHUB_API}/repos/{owner}/{repo}/stats/contributors"
+
+    for attempt in range(STATS_POLL_ATTEMPTS):
+        response = requests.get(
+            url,
+            headers=_get_auth_headers(),
+            timeout=10,
+        )
+
+        if response.status_code == 202:
+            if attempt < STATS_POLL_ATTEMPTS - 1:
+                time.sleep(STATS_POLL_INTERVAL_SECONDS)
+                continue
+
+            raise RuntimeError(
+                "GitHub is still computing contributor statistics. Try again shortly."
+            )
+
+        raise_for_github_error(response)
+
+        statistics = [
+            contributor
+            for contributor in response.json()
+            if contributor.get("author") is not None
+        ]
+        contributors = sorted(
+            statistics,
+            key=lambda contributor: contributor["total"],
+            reverse=True,
+        )
+
+        def format_contributor(contributor: dict) -> dict[str, str | int | None]:
+            author = contributor["author"]
+            return {
+                "login": author["login"],
+                "commits": contributor["total"],
+                "profile_url": author["html_url"],
+                "avatar_url": author["avatar_url"],
+            }
+
+        current_contributor = next(
+            (
+                format_contributor(contributor)
+                for contributor in contributors
+                if current_login
+                and contributor["author"]["login"].casefold()
+                == current_login.casefold()
+            ),
+            None,
+        )
+
+        top_contributors = [
+            format_contributor(contributor) for contributor in contributors[:limit]
+        ]
+        if not include_metadata:
+            return top_contributors
+
+        return ContributorResults(
+            contributors=top_contributors,
+            total_contributors=len(contributors),
+            total_commits=sum(contributor["total"] for contributor in contributors),
+            current_contributor=current_contributor,
+        )
+
+    return ContributorResults([], 0, 0) if include_metadata else []

app/services/github_errors.py

@@ -0,0 +1,39 @@
+from requests import Response
+
+
+def github_headers(token: str) -> dict[str, str]:
+    """Build headers for GitHub REST API requests."""
+    return {
+        "Authorization": f"Bearer {token}",
+        "Accept": "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2026-03-10",
+    }
+
+
+def raise_for_github_error(response: Response) -> None:
+    """Raise a useful error message for failed GitHub API requests."""
+    if response.ok:
+        return
+
+    try:
+        message = response.json().get("message", response.reason)
+    except ValueError:
+        message = response.text or response.reason
+
+    details = [f"GitHub API returned {response.status_code}: {message}"]
+
+    request_id = response.headers.get("X-GitHub-Request-Id")
+    if request_id:
+        details.append(f"request ID: {request_id}")
+
+    if response.status_code in {403, 429}:
+        remaining = response.headers.get("X-RateLimit-Remaining")
+
+        if remaining == "0":
+            details.append("primary API rate limit exhausted")
+
+        retry_after = response.headers.get("Retry-After")
+        if retry_after:
+            details.append(f"retry after {retry_after} seconds")
+
+    raise RuntimeError("; ".join(details))

app/services/storage.py

@@ -0,0 +1,27 @@
+import json
+from pathlib import Path
+
+ATLAS_DIR = Path.home() / ".atlas"
+CONFIG_FILE = ATLAS_DIR / "config.json"
+
+
+def save_token(token: str):
+    ATLAS_DIR.mkdir(exist_ok=True)
+
+    data = {"github_token": token}
+
+    CONFIG_FILE.write_text(json.dumps(data, indent=4), encoding="utf-8")
+
+
+def get_token():
+    if not CONFIG_FILE.exists():
+        return None
+
+    data = json.loads(CONFIG_FILE.read_text(encoding="utf-8"))
+
+    return data.get("github_token")
+
+
+def clear_token():
+    if CONFIG_FILE.exists():
+        CONFIG_FILE.unlink()

app/ui/avatar.py

@@ -0,0 +1,24 @@
+from io import BytesIO
+
+import requests
+from PIL import Image
+from rich_pixels import Pixels
+
+
+def get_profile_picture(user: dict):
+    """Return user profile picture as a small Rich renderable."""
+
+    avatar_url = user.get("avatar_url")
+
+    if not avatar_url:
+        return ""
+
+    response = requests.get(avatar_url, timeout=10)
+    response.raise_for_status()
+
+    image = Image.open(BytesIO(response.content))
+
+    # Resize avatar for terminal display
+    image.thumbnail((28, 28))
+
+    return Pixels.from_image(image)

app/ui/display.py

@@ -0,0 +1,53 @@
+from rich.columns import Columns
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from app.ui.avatar import get_profile_picture
+
+console = Console()
+
+
+def display_user(user: dict):
+    """Display a GitHub profile with avatar."""
+
+    title = user.get("name") or user["login"]
+    subtitle = f"@{user['login']}"
+
+    profile = Table(show_header=False, box=None, pad_edge=False)
+    profile.add_column("Field", style="cyan")
+    profile.add_column("Value")
+
+    profile.add_row("Repositories", str(user["public_repos"]))
+    profile.add_row("Followers", str(user["followers"]))
+    profile.add_row("Following", str(user["following"]))
+    profile.add_row("Location", user.get("location") or "—")
+    profile.add_row("Company", user.get("company") or "—")
+    profile.add_row("Joined", user["created_at"][:10])
+
+    profile_panel = Panel(
+        profile,
+        title=f"[bold]{title}[/bold]",
+        subtitle=subtitle,
+        expand=False,
+    )
+
+    avatar_panel = Panel(
+        get_profile_picture(user),
+        # Pixels does not report its natural width to Rich, so constrain this
+        # panel to the 28-column thumbnail plus its border and horizontal padding.
+        width=32,
+        padding=(0, 1),
+        expand=False,
+    )
+
+    console.print(
+        Columns(
+            [
+                profile_panel,
+                avatar_panel,
+            ],
+            expand=False,
+            equal=False,
+        )
+    )

app/ui/repo.py

@@ -0,0 +1,365 @@
+from rich.columns import Columns
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+console = Console()
+
+
+def build_view_header(title: str, subtitle: str) -> Panel:
+    """Create the shared header used by focused repository views."""
+    content = Text(justify="center")
+    content.append(title.upper(), style="bold cyan")
+    content.append("\n")
+    content.append(subtitle, style="bold")
+    return Panel(content, width=60, border_style="cyan")
+
+
+def display_view_header(title: str, subtitle: str) -> None:
+    """Render the shared header used by focused repository views."""
+    console.print(build_view_header(title, subtitle))
+
+
+def format_size(size: int | None) -> str:
+    # Format GitHub's repository size value for display.
+    if size is None:
+        return "Not available"
+
+    units = ["KB", "MB", "GB", "TB", "PB"]
+    value = size
+    current_unit = 0
+
+    while value >= 1000 and current_unit < len(units) - 1:
+        value /= 1000
+        current_unit += 1
+
+    return f"{value:.1f} {units[current_unit]}"
+
+
+def format_bytes(size: int | None) -> str:
+    """Format byte size values for display."""
+    if size is None:
+        return "Not available"
+
+    units = ["B", "KB", "MB", "GB", "TB"]
+    value = float(size)
+    current_unit = 0
+
+    while value >= 1000 and current_unit < len(units) - 1:
+        value /= 1000
+        current_unit += 1
+
+    if current_unit == 0:
+        return f"{int(value)} B"
+    return f"{value:.1f} {units[current_unit]}"
+
+
+def display_repo_details(
+    details: dict,
+    languages: list[str],
+    contributions: list[dict],
+):
+    """Display a repository overview."""
+
+    full_name = details.get("full_name", "Unknown repository")
+    description = details.get("description") or "No description provided."
+    visibility = details.get("visibility") or (
+        "private" if details.get("private") else "public"
+    )
+    primary_language = details.get("language") or "—"
+    url = details.get("html_url") or "—"
+
+    header_panel = build_view_header("Details", full_name)
+
+    # Statistics
+    stats = Table(
+        show_header=False,
+        box=None,
+        pad_edge=False,
+    )
+
+    stats.add_column("Metric", style="dim")
+    stats.add_column("Value", justify="right")
+
+    stats.add_row(
+        "★ Stars",
+        str(details.get("stargazers_count") or 0),
+    )
+    stats.add_row(
+        "⑂ Forks",
+        str(details.get("forks_count") or 0),
+    )
+    stats.add_row(
+        "! Issues",
+        str(details.get("open_issues_count") or 0),
+    )
+    stats.add_row(
+        "Size",
+        format_size(details.get("size")),
+    )
+
+    stats_panel = Panel(
+        stats,
+        title="Statistics",
+        expand=False,
+    )
+
+    # Contributions
+    contribution_table = Table(
+        show_header=False,
+        box=None,
+        pad_edge=False,
+    )
+
+    contribution_table.add_column("Contributor")
+    contribution_table.add_column("Commits", justify="right")
+
+    if contributions:
+        for contributor in contributions:
+            contribution_table.add_row(
+                contributor["login"],
+                str(contributor["commits"]),
+            )
+    else:
+        contribution_table.add_row(
+            "No contributor data",
+            "—",
+        )
+
+    contributions_panel = Panel(
+        contribution_table,
+        title="Contributions",
+        expand=False,
+    )
+
+    # Languages
+    language_table = Table(
+        show_header=False,
+        box=None,
+        pad_edge=False,
+    )
+
+    language_table.add_column("Language")
+    language_table.add_column("Usage")
+
+    for language in languages:
+        language_name, percentage = language.split(": ")
+        language_table.add_row(
+            language_name,
+            percentage,
+        )
+
+    languages_panel = Panel(
+        language_table,
+        title="Languages",
+        expand=False,
+    )
+
+    console.print(header_panel)
+    console.print(Text(description, style="dim"))
+    console.print(
+        Text.assemble(
+            (visibility.capitalize(), "cyan"),
+            ("    "),
+            (primary_language, "green"),
+        )
+    )
+    console.print()
+
+    console.print(
+        Columns(
+            [stats_panel, contributions_panel],
+            expand=False,
+            equal=True,
+        )
+    )
+
+    console.print(languages_panel)
+
+    console.print(
+        Text(
+            f"↗ {url}",
+            style="dim",
+        )
+    )
+
+
+def display_contributors(
+    full_name: str,
+    contributors: list[dict],
+    total_contributors: int,
+    total_commits: int,
+    current_login: str | None = None,
+    current_contributor: dict | None = None,
+):
+    """Display a focused view of GitHub contributor statistics."""
+    display_view_header("Contributors", full_name)
+
+    shown_count = len(contributors)
+    if not total_contributors:
+        console.print(Text("No contributor data returned.", style="dim"))
+        return
+
+    console.print(
+        Text(
+            f"{total_contributors} contributors returned by GitHub · showing top {shown_count}",
+            style="dim",
+        )
+    )
+
+    current_is_ranked = any(
+        current_login and contributor["login"].casefold() == current_login.casefold()
+        for contributor in contributors
+    )
+    largest_count = max(contributor["commits"] for contributor in contributors)
+
+    if current_contributor and not current_is_ranked:
+        console.print()
+        console.print(Text("YOUR CONTRIBUTION", style="bold cyan"))
+        console.print(Text("─" * 58, style="dim"))
+        console.print(
+            _contributor_row(
+                current_contributor,
+                total_commits,
+                largest_count,
+                marker="● ",
+                highlight=True,
+            )
+        )
+
+    console.print()
+    console.print(Text("TOP CONTRIBUTORS", style="bold"))
+    console.print(Text("─" * 58, style="dim"))
+    for rank, contributor in enumerate(contributors, start=1):
+        is_current_user = bool(
+            current_login
+            and contributor["login"].casefold() == current_login.casefold()
+        )
+        console.print(
+            _contributor_row(
+                contributor,
+                total_commits,
+                largest_count,
+                rank=rank,
+                marker="● " if is_current_user else "  ",
+                highlight=is_current_user,
+            )
+        )
+        if rank < shown_count:
+            console.print()
+
+    console.print(Text("─" * 58, style="dim"))
+    console.print(
+        Text(
+            f"Showing {shown_count} of {total_contributors} contributors returned by GitHub",
+            style="dim",
+        )
+    )
+
+
+def display_languages(full_name: str, languages: dict[str, int]) -> None:
+    """Display all languages reported by GitHub with proportional usage bars."""
+    display_view_header("Languages", full_name)
+
+    if not languages:
+        console.print(Text("No language data returned.", style="dim"))
+        return
+
+    total_bytes = sum(languages.values())
+    ranked_languages = sorted(
+        languages.items(),
+        key=lambda language: language[1],
+        reverse=True,
+    )
+    largest_count = ranked_languages[0][1]
+    language_count = len(ranked_languages)
+
+    console.print(
+        Text(
+            f"{language_count} languages returned by GitHub · 100% of reported code",
+            style="dim",
+        )
+    )
+    console.print()
+    console.print(Text("LANGUAGE BREAKDOWN", style="bold"))
+    console.print(Text("─" * 58, style="dim"))
+
+    for index, (language, byte_count) in enumerate(ranked_languages, start=1):
+        console.print(
+            _language_row(
+                language,
+                byte_count,
+                total_bytes,
+                largest_count,
+                rank=index,
+            )
+        )
+        if index < language_count:
+            console.print()
+
+    console.print(Text("─" * 58, style="dim"))
+    console.print(Text(f"Showing all {language_count} languages", style="dim"))
+
+
+def _contributor_row(
+    contributor: dict,
+    total_commits: int,
+    largest_count: int,
+    rank: int | None = None,
+    marker: str = "",
+    highlight: bool = False,
+) -> Text:
+    """Build one compact contributor row with a proportional contribution bar."""
+    commits = int(contributor.get("commits") or 0)
+    percentage = commits / total_commits * 100 if total_commits else 0
+    bar_width = 32
+    filled = (
+        max(1, round(commits / largest_count * bar_width))
+        if commits and largest_count
+        else 0
+    )
+    bar = "█" * filled
+    username_style = "bold cyan" if highlight else ""
+    bar_style = "cyan" if highlight else "green"
+    commit_label = "commit" if commits == 1 else "commits"
+
+    row = Text()
+    if rank is not None:
+        row.append(f"{rank:<2} ", style="dim")
+    row.append(marker, style="cyan" if highlight else "dim")
+    row.append(f"{contributor.get('login', 'Unknown'):<30}", style=username_style)
+    row.append(f"{commits:>6} {commit_label}\n")
+    row.append(" " * (4 if rank is not None else 3))
+    row.append(bar.ljust(bar_width), style=bar_style)
+    row.append(f"  {percentage:.1f}%", style="dim")
+    return row
+
+
+def _language_row(
+    language: str,
+    byte_count: int,
+    total_bytes: int,
+    largest_count: int,
+    rank: int | None = None,
+) -> Text:
+    """Build one compact language row with a proportional usage bar."""
+    percentage = byte_count / total_bytes * 100 if total_bytes else 0
+    bar_width = 32
+    filled = (
+        max(1, round(byte_count / largest_count * bar_width))
+        if byte_count and largest_count
+        else 0
+    )
+    bar = "█" * filled
+
+    row = Text()
+    if rank is not None:
+        row.append(f"{rank:<2} ", style="dim")
+    row.append("  ", style="dim")
+    row.append(f"{language:<30}")
+    row.append(f"{format_bytes(byte_count):>12}\n")
+    row.append(" " * (4 if rank is not None else 3))
+    row.append(bar.ljust(bar_width), style="green")
+    row.append(f"  {percentage:.1f}%", style="dim")
+    return row

recon_github-0.1.0.dist-info/METADATA

@@ -0,0 +1,241 @@
+Metadata-Version: 2.4
+Name: recon-github
+Version: 0.1.0
+Summary: Recon is a powerful CLI companion for developers and tools for agents, turning GitHub activity and repository data into useful insights from your terminal
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: dotenv>=0.9.9
+Requires-Dist: requests>=2.34.2
+Requires-Dist: rich>=15.0.0
+Requires-Dist: rich-pixels>=3.0.1
+Requires-Dist: typer>=0.27.1
+Dynamic: license-file
+
+
+# Recon CLI
+
+Recon is a powerful CLI companion for developers and tools for agents, turning GitHub activity and repository data into useful insights from your terminal.
+
+
+
+[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://choosealicense.com/licenses/mit/)
+[![CI](https://github.com/owenpalfreymandev/reconcli/actions/workflows/ci.yml/badge.svg)](https://github.com/owenpalfreymandev/reconcli/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/)
+[![PyPI](https://img.shields.io/pypi/v/recon-cli)](https://pypi.org/)
+[![License](https://img.shields.io/github/license/owenpalfreymandev/reconcli)](https://github.com/owenpalfreymandev/reconcli/blob/main/LICENSE)
+## Overview
+
+Recon allows for developers to view basic GitHub analytics in the terminal quickly, rather than opening up their browser. This means it allows agents to interect with the service without having browser capabilities.
+
+It is powered by [Typer](github.com/fastapi/typer), a library for building fast CLI tools, and made pretty by [Rich](https://github.com/textualize/rich) and it's prebuilt components.
+## Features
+
+* **GitHub Authentication** — Securely authenticate with GitHub using OAuth device flow.
+* **User Information** — View information about your authenticated GitHub account.
+* **Repository Explorer** — List and inspect GitHub repositories directly from the terminal.
+* **Repository Statistics** — Explore repository languages, contributors, and other useful statistics.
+* **Rich Terminal UI** — Clean, structured terminal output powered by Rich.
+* **Fast CLI Workflow** — Quickly access GitHub information without leaving the command line.
+* **Modular Architecture** — Built with reusable services and components to make Recon easy to maintain and extend.
+* **Automated Testing** — Tested with an automated CI pipeline to help maintain reliability and code quality.
+
+## Installation
+
+Since we want you to be able to use Recon from anywhere - not just one directory - we recomend you install it with [uv package manager](https://docs.astral.sh/uv/getting-started/installation/).
+
+```bash
+  uv tool install recon-gh
+```
+For the best experience, then login to your GitHub account (this step is not strictly required).
+```bash
+    recon login
+```
+## Usage
+
+Here you can learn how to get started with terminal commands, and learn how to find more.
+
+### View Your GitHub Profile
+
+The `me` command displays information about your authenticated GitHub account.
+
+```bash
+recon me
+```
+
+Example output:
+
+```text
+╭────── Owen Palfreyman ───────╮ ╭──────────────────────────────╮
+│ Repositories  2              │ │                              │
+│ Followers     7              │ │                              │
+│ Following     2              │ │                              │
+│ Location      United Kingdom │ │                              │
+│ Company       —              │ │                              │
+│ Joined        2023-11-02     │ │                              │
+╰───── @owenpalfreymandev ─────╯ │                              │
+                                 ╰──────────────────────────────╯
+```
+
+### Scout Another GitHub User
+
+Use `scout` to explore another GitHub user's profile.
+
+```bash
+recon scout torvalds
+```
+
+Example output:
+
+```text
+╭──────── Linus Torvalds ────────╮ ╭──────────────────────────────╮
+│ Repositories  12               │ │                              │
+│ Followers     318572           │ │                              │
+│ Following     0                │ │                              │
+│ Location      Portland, OR     │ │                              │
+│ Company       Linux Foundation │ │                              │
+│ Joined        2011-09-03       │ │                              │
+╰────────── @torvalds ───────────╯ │                              │
+                                   ╰──────────────────────────────╯
+```
+
+### List Your Repositories
+
+The `list` command displays your GitHub repositories.
+
+```bash
+recon list
+```
+
+This provides a quick way to see your repositories before using `details` to explore a specific project.
+
+### Authentication
+
+Recon uses GitHub's device flow for authentication.
+
+To log in:
+
+```bash
+recon login
+```
+
+To log out:
+
+```bash
+recon logout
+```
+
+### Explore a Repository
+
+The `details` command gives you an overview of a GitHub repository.
+
+```bash
+recon details owenpalfreymandev fpark
+```
+
+The command takes two arguments:
+
+* `owner` — The GitHub username or organisation that owns the repository.
+* `repo` — The name of the repository.
+
+### Need Some Help?
+
+Not sure what a command can do? Recon has built-in help for every command.
+
+```bash
+recon details --help
+```
+
+This shows you the available arguments and options for the command, including additional ways to get information from a repository.
+
+```text
+Usage: recon details [OPTIONS] {owner} {repo}
+
+Gain insights into your repo
+
+Arguments:
+  owner    Repository owner, e.g. owenpalfreymandev
+  repo     Repository name, e.g. reconcli
+
+Options:
+  --contributors    View contributors in more detail.
+  --languages       View language usage in more detail.
+  --help            Show this message and exit.
+```
+
+For example, the `--languages` option can be used to get a more detailed breakdown of the languages used in a repository:
+
+```bash
+recon details owenpalfreymandev fpark --languages
+```
+
+```text
+╭──────────────────────────────────────────────────────────╮
+│                        LANGUAGES                         │
+│                 owenpalfreymandev/fpark                  │
+╰──────────────────────────────────────────────────────────╯
+4 languages returned by GitHub · 100% of reported code
+
+LANGUAGE BREAKDOWN
+──────────────────────────────────────────────────────────
+1    TypeScript                        279.9 KB
+    ████████████████████████████████  95.9%
+
+2    PLpgSQL                             7.0 KB
+    █                                 2.4%
+
+3    CSS                                 4.3 KB
+    █                                 1.5%
+
+4    JavaScript                           559 B
+    █                                 0.2%
+──────────────────────────────────────────────────────────
+Showing all 4 languages
+```
+
+
+### Explore Further
+
+These are just some of the commands available in Recon. There are plenty more options to play with, with more commands and features coming soon. Check the [roadmap](https://github.com/owenpalfreymandev/reconcli/blob/main/README.md) for more details.
+
+## Contributing
+
+Contributions are always welcome!
+
+To clone the repo and download all dependencies, run:
+```bash
+git clone https://github.com/owenpalfreymandev/reconcli.git
+uv sync
+```
+
+You can run unit tests and type tests with:
+```bash
+uv run pytest
+uv run pyright
+```
+
+Be sure to lint before commiting, or it will fail CI/CD:
+```bash
+uv run ruff check --fix .
+```
+
+### Workflow
+
+A basic workflow to follow is:
+
+1. Fork the repository
+2. Create a branch
+3. Make changes
+4. Run tests/lint/type checks
+5. Open a PR
+## License
+
+Recon is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+## Author
+
+Recon is developed by Owen Palfreyman.
+
+GitHub: @owenpalfreymandev
+Repository: owenpalfreymandev/reconcli
+
+*or could could just run `recon details owenpalfreymandev reconcli --contributors` wink wink*

recon_github-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+app/cli.py,sha256=j_aGv8L7KRteU0Rt6sIaqdIXPjGz8CcczICuOoentlE,336
+app/commands/auth.py,sha256=XP5IehUFW_NMXIzNHRjjFhQd0FeIQn3jjqs_4ZCw7IM,238
+app/commands/me.py,sha256=FCJUYrTUw6rM2OkrGj421TzJJmC61cwEupy4AMUqDB8,434
+app/commands/repo.py,sha256=TapGxTGWP7qJZB4nBju6lMbKFA9T-PVSW83XVbuKGjo,6357
+app/services/auth.py,sha256=3QGHpdfikQblTWjn6j_ePCHet4AVGBtFR73JTZEIQHE,1801
+app/services/github.py,sha256=N86ZFl9l41T_hHIXPvuBPi6fCRinfCVCVgU6dLy5JZY,4727
+app/services/github_errors.py,sha256=14IpoR_mQMqky_tv2vjSrFAK-nO7_YhSbT6OhUgLs6U,1210
+app/services/storage.py,sha256=bO_XKvfQFhS4nKDIkNuJXLFD12ThZi8ztPYOKyKIq24,540
+app/ui/avatar.py,sha256=UAcqWQIk92HoI6TrG8nPvyrIFZhJg6dFNC8OJIu650o,526
+app/ui/display.py,sha256=WUm6jybb3NWgGOE4Xicvj6OO80cwqiCuaKzI_gC-spc,1481
+app/ui/repo.py,sha256=vxlqprTRne6TgCM6QBzVRDJvzklFxOE6xwvZXuoFvKs,10141
+recon_github-0.1.0.dist-info/licenses/LICENSE,sha256=SeqZEVgNw2f7eXshxAwKfEH3Y6K-9QCY0QlrnJKGTBY,1074
+recon_github-0.1.0.dist-info/METADATA,sha256=2pszzpJjIDLO_4Z3D0PqD31pSuWRJ6TI4rd6e1ZPjig,8893
+recon_github-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+recon_github-0.1.0.dist-info/top_level.txt,sha256=io9g7LCbfmTG1SFKgEOGXmCFB9uMP2H5lerm0HiHWQE,4
+recon_github-0.1.0.dist-info/RECORD,,

recon_github-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

recon_github-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 owenpalfreymandev
+
+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.

recon_github-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+app