gh-weekly-updates 0.1.0__tar.gz

gh_weekly_updates-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sahan Serasinghe <sahan.serasinghe@gmail.com>
+
+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.

gh_weekly_updates-0.1.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: gh-weekly-updates
+Version: 0.1.0
+Summary: Automatically discover and summarise your weekly GitHub impact
+License: MIT
+Project-URL: Homepage, https://github.com/sahansera/gh-weekly-updates
+Project-URL: Repository, https://github.com/sahansera/gh-weekly-updates
+Project-URL: Issues, https://github.com/sahansera/gh-weekly-updates/issues
+Keywords: github,weekly,impact,summary,engineering
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: openai>=1.30
+Provides-Extra: dev
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# gh-weekly-updates
+
+> Automatically discover and summarise your weekly GitHub impact using AI.
+
+`gh-weekly-updates` collects your GitHub activity — pull requests authored & reviewed, issues created & commented on, discussions — and generates a structured Markdown summary using [GitHub Models](https://github.com/marketplace/models).
+
+## Features
+
+- **Auto-discover repos** via the GitHub GraphQL Contributions API, or provide an explicit list
+- **Collect detailed activity**: PRs, reviews, issues, issue comments, discussions
+- **AI-powered summarisation** via GitHub Models (`openai/gpt-4.1` by default)
+- **Structured output**: Wins / Strategic Influence / Challenges with inline links
+- **Push to a repo**: automatically commit summaries to a GitHub repo for sharing
+- **Fully configurable**: org, repos, model, prompt — via YAML config or CLI flags
+- **Custom prompts**: tailor the AI summary to your team's format
+
+## Installation
+
+```bash
+pip install gh-weekly-updates
+```
+
+### Requirements
+
+- Python 3.11+
+- A GitHub personal access token (PAT) **or** the [GitHub CLI](https://cli.github.com/) (`gh`) authenticated
+  - Required scopes: `repo`, `read:org`
+  - The token also needs access to [GitHub Models](https://github.com/marketplace/models) for AI summarisation
+
+## Quick start
+
+```bash
+# Authenticate with the GitHub CLI (easiest)
+gh auth login
+
+# Run with defaults — covers the past week
+gh-weekly-updates
+
+# Or specify a date range
+gh-weekly-updates --since 2025-06-01 --until 2025-06-07
+```
+
+## Configuration
+
+Create a `config.yaml` (see [config.example.yaml](config.example.yaml)):
+
+```yaml
+# GitHub org to scope repo discovery to
+org: my-org
+
+# Explicit repo list (skips auto-discovery)
+repos:
+  - my-org/api-service
+  - my-org/web-app
+
+# GitHub Model for summarisation
+model: openai/gpt-4.1
+
+# Push summary to a repo under weekly-updates/
+push_repo: my-user/my-updates
+
+# Custom system prompt (inline)
+prompt: |
+  You are an engineering manager writing a concise weekly summary...
+
+# Or load prompt from a file
+# prompt_file: my-prompt.txt
+```
+
+## CLI reference
+
+```
+Usage: gh-weekly-updates [OPTIONS]
+
+Options:
+  --config PATH    Path to YAML config file. Default: ./config.yaml
+  --since TEXT      Start date (ISO 8601). Default: previous Monday.
+  --until TEXT      End date (ISO 8601). Default: now.
+  --user TEXT       GitHub username. Default: authenticated user.
+  --repos TEXT      Comma-separated list of repos (owner/name).
+  --org TEXT        GitHub org to scope repo discovery to.
+  --output PATH    Write summary to a file instead of stdout.
+  --push TEXT       Push summary to a GitHub repo (owner/name).
+  --model TEXT      GitHub Model to use. Default: openai/gpt-4.1.
+  --verbose         Enable debug logging.
+  --help            Show this message and exit.
+```
+
+## Authentication
+
+`gh-weekly-updates` resolves a GitHub token in this order:
+
+1. `GITHUB_TOKEN` environment variable
+2. `gh auth token` (GitHub CLI)
+
+For GitHub Enterprise with SSO, ensure the token is authorised for your org.
+
+## Using with GitHub Actions
+
+You can run `gh-weekly-updates` on a schedule in a GitHub Actions workflow:
+
+```yaml
+name: Weekly Impact Summary
+
+on:
+  schedule:
+    - cron: '0 9 * * 1'  # Every Monday at 9am UTC
+  workflow_dispatch:
+
+jobs:
+  summarise:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install gh-weekly-updates
+        run: pip install gh-weekly-updates
+
+      - name: Generate summary
+        env:
+          GITHUB_TOKEN: ${{ secrets.GH_PAT }}
+        run: |
+          gh-weekly-updates \
+            --config config.yaml \
+            --push my-user/my-updates
+```
+
+> **Note**: The default `GITHUB_TOKEN` provided by Actions has limited scope.
+> Use a [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) stored as a repository secret with `repo` and `read:org` scopes, plus GitHub Models access.
+
+## Development
+
+```bash
+git clone https://github.com/sahansera/gh-weekly-updates.git
+cd gh-weekly-updates
+python -m venv .venv && source .venv/bin/activate
+make dev   # install in editable mode with dev deps
+make run   # run with defaults
+make lint  # ruff check
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for more details.
+
+## License
+
+[MIT](LICENSE)

gh_weekly_updates-0.1.0/README.md

@@ -0,0 +1,150 @@
+# gh-weekly-updates
+
+> Automatically discover and summarise your weekly GitHub impact using AI.
+
+`gh-weekly-updates` collects your GitHub activity — pull requests authored & reviewed, issues created & commented on, discussions — and generates a structured Markdown summary using [GitHub Models](https://github.com/marketplace/models).
+
+## Features
+
+- **Auto-discover repos** via the GitHub GraphQL Contributions API, or provide an explicit list
+- **Collect detailed activity**: PRs, reviews, issues, issue comments, discussions
+- **AI-powered summarisation** via GitHub Models (`openai/gpt-4.1` by default)
+- **Structured output**: Wins / Strategic Influence / Challenges with inline links
+- **Push to a repo**: automatically commit summaries to a GitHub repo for sharing
+- **Fully configurable**: org, repos, model, prompt — via YAML config or CLI flags
+- **Custom prompts**: tailor the AI summary to your team's format
+
+## Installation
+
+```bash
+pip install gh-weekly-updates
+```
+
+### Requirements
+
+- Python 3.11+
+- A GitHub personal access token (PAT) **or** the [GitHub CLI](https://cli.github.com/) (`gh`) authenticated
+  - Required scopes: `repo`, `read:org`
+  - The token also needs access to [GitHub Models](https://github.com/marketplace/models) for AI summarisation
+
+## Quick start
+
+```bash
+# Authenticate with the GitHub CLI (easiest)
+gh auth login
+
+# Run with defaults — covers the past week
+gh-weekly-updates
+
+# Or specify a date range
+gh-weekly-updates --since 2025-06-01 --until 2025-06-07
+```
+
+## Configuration
+
+Create a `config.yaml` (see [config.example.yaml](config.example.yaml)):
+
+```yaml
+# GitHub org to scope repo discovery to
+org: my-org
+
+# Explicit repo list (skips auto-discovery)
+repos:
+  - my-org/api-service
+  - my-org/web-app
+
+# GitHub Model for summarisation
+model: openai/gpt-4.1
+
+# Push summary to a repo under weekly-updates/
+push_repo: my-user/my-updates
+
+# Custom system prompt (inline)
+prompt: |
+  You are an engineering manager writing a concise weekly summary...
+
+# Or load prompt from a file
+# prompt_file: my-prompt.txt
+```
+
+## CLI reference
+
+```
+Usage: gh-weekly-updates [OPTIONS]
+
+Options:
+  --config PATH    Path to YAML config file. Default: ./config.yaml
+  --since TEXT      Start date (ISO 8601). Default: previous Monday.
+  --until TEXT      End date (ISO 8601). Default: now.
+  --user TEXT       GitHub username. Default: authenticated user.
+  --repos TEXT      Comma-separated list of repos (owner/name).
+  --org TEXT        GitHub org to scope repo discovery to.
+  --output PATH    Write summary to a file instead of stdout.
+  --push TEXT       Push summary to a GitHub repo (owner/name).
+  --model TEXT      GitHub Model to use. Default: openai/gpt-4.1.
+  --verbose         Enable debug logging.
+  --help            Show this message and exit.
+```
+
+## Authentication
+
+`gh-weekly-updates` resolves a GitHub token in this order:
+
+1. `GITHUB_TOKEN` environment variable
+2. `gh auth token` (GitHub CLI)
+
+For GitHub Enterprise with SSO, ensure the token is authorised for your org.
+
+## Using with GitHub Actions
+
+You can run `gh-weekly-updates` on a schedule in a GitHub Actions workflow:
+
+```yaml
+name: Weekly Impact Summary
+
+on:
+  schedule:
+    - cron: '0 9 * * 1'  # Every Monday at 9am UTC
+  workflow_dispatch:
+
+jobs:
+  summarise:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install gh-weekly-updates
+        run: pip install gh-weekly-updates
+
+      - name: Generate summary
+        env:
+          GITHUB_TOKEN: ${{ secrets.GH_PAT }}
+        run: |
+          gh-weekly-updates \
+            --config config.yaml \
+            --push my-user/my-updates
+```
+
+> **Note**: The default `GITHUB_TOKEN` provided by Actions has limited scope.
+> Use a [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) stored as a repository secret with `repo` and `read:org` scopes, plus GitHub Models access.
+
+## Development
+
+```bash
+git clone https://github.com/sahansera/gh-weekly-updates.git
+cd gh-weekly-updates
+python -m venv .venv && source .venv/bin/activate
+make dev   # install in editable mode with dev deps
+make run   # run with defaults
+make lint  # ruff check
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for more details.
+
+## License
+
+[MIT](LICENSE)

gh_weekly_updates-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gh-weekly-updates"
+version = "0.1.0"
+description = "Automatically discover and summarise your weekly GitHub impact"
+requires-python = ">=3.11"
+readme = "README.md"
+license = {text = "MIT"}
+keywords = ["github", "weekly", "impact", "summary", "engineering"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development",
+]
+dependencies = [
+    "click>=8.1",
+    "httpx>=0.27",
+    "pydantic>=2.0",
+    "pyyaml>=6.0",
+    "rich>=13.0",
+    "openai>=1.30",
+]
+
+[project.optional-dependencies]
+dev = [
+    "ruff>=0.4",
+    "pytest>=8.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/sahansera/gh-weekly-updates"
+Repository = "https://github.com/sahansera/gh-weekly-updates"
+Issues = "https://github.com/sahansera/gh-weekly-updates/issues"
+
+[project.scripts]
+gh-weekly-updates = "gh_weekly_updates.cli:main"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]
+
+[tool.setuptools.packages.find]
+where = ["src"]

gh_weekly_updates-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

gh_weekly_updates-0.1.0/src/gh_weekly_updates/__init__.py

@@ -0,0 +1 @@
+"""gh-weekly-updates — auto-discover and summarise your weekly GitHub contributions."""

gh_weekly_updates-0.1.0/src/gh_weekly_updates/cli.py

@@ -0,0 +1,238 @@
+"""CLI entrypoint for gh-weekly-updates."""
+
+from __future__ import annotations
+
+import logging
+import sys
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+import click
+import yaml
+from rich.console import Console
+from rich.logging import RichHandler
+from rich.markdown import Markdown
+from rich.panel import Panel
+
+from gh_weekly_updates.collector import collect_activity
+from gh_weekly_updates.config import get_github_token, get_github_username
+from gh_weekly_updates.contributions import discover_repos
+from gh_weekly_updates.publisher import publish_to_repo
+from gh_weekly_updates.summariser import DEFAULT_MODEL, summarise
+
+console = Console()
+
+DEFAULT_CONFIG_PATH = "config.yaml"
+
+
+def _load_config(path: str | None) -> dict:
+    """Load YAML config file. Returns empty dict if not found."""
+    config_path = Path(path) if path else Path(DEFAULT_CONFIG_PATH)
+    if config_path.exists():
+        with open(config_path) as f:
+            return yaml.safe_load(f) or {}
+    return {}
+
+
+def _default_since() -> datetime:
+    """Return the previous Monday 00:00 UTC so we always cover at least a full week."""
+    now = datetime.now(timezone.utc)
+    today_midnight = now.replace(hour=0, minute=0, second=0, microsecond=0)
+    days_since_monday = now.weekday()  # Monday=0
+    # Always go back to LAST week's Monday (7 + days_since_monday days back)
+    # e.g. Tuesday → 8 days back, Monday → 7 days back
+    return today_midnight - timedelta(days=days_since_monday + 7)
+
+
+def _parse_date(value: str) -> datetime:
+    """Parse an ISO-8601 date string into a timezone-aware datetime."""
+    dt = datetime.fromisoformat(value)
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt
+
+
+@click.command()
+@click.option(
+    "--config",
+    "config_path",
+    default=None,
+    type=click.Path(),
+    help="Path to YAML config file. Default: ./config.yaml",
+)
+@click.option(
+    "--since",
+    default=None,
+    help="Start date (ISO 8601). Default: Monday of previous week.",
+)
+@click.option(
+    "--until",
+    default=None,
+    help="End date (ISO 8601). Default: now.",
+)
+@click.option(
+    "--user",
+    default=None,
+    help="GitHub username. Default: authenticated user.",
+)
+@click.option(
+    "--repos",
+    default=None,
+    help="Comma-separated list of repos (owner/name). Skips auto-discovery.",
+)
+@click.option(
+    "--output",
+    default=None,
+    type=click.Path(),
+    help="Write summary to file instead of stdout.",
+)
+@click.option(
+    "--org",
+    default=None,
+    help="GitHub org to scope repo discovery to.",
+)
+@click.option(
+    "--push",
+    "push_repo",
+    default=None,
+    help="Push summary to a GitHub repo (owner/name).",
+)
+@click.option(
+    "--model",
+    default=DEFAULT_MODEL,
+    show_default=True,
+    help="GitHub Model to use for summarisation.",
+)
+@click.option(
+    "--verbose",
+    is_flag=True,
+    help="Enable debug logging.",
+)
+def main(
+    config_path: str | None,
+    since: str | None,
+    until: str | None,
+    user: str | None,
+    repos: str | None,
+    org: str | None,
+    push_repo: str | None,
+    output: str | None,
+    model: str,
+    verbose: bool,
+) -> None:
+    """Discover your weekly GitHub impact and generate a structured summary."""
+    # --- Load config ---
+    cfg = _load_config(config_path)
+
+    # CLI flags override config file values
+    org = org or cfg.get("org")
+    model = model if model != DEFAULT_MODEL else cfg.get("model", model)
+    push_repo = push_repo or cfg.get("push_repo")
+
+    # Custom prompt: inline in config or from a file
+    custom_prompt = cfg.get("prompt")
+    if not custom_prompt and cfg.get("prompt_file"):
+        prompt_path = Path(cfg["prompt_file"])
+        if prompt_path.exists():
+            custom_prompt = prompt_path.read_text()
+
+    # Repos: CLI --repos flag (comma-separated) > config file list
+    if repos:
+        repo_list_override = [r.strip() for r in repos.split(",") if r.strip()]
+    elif cfg.get("repos"):
+        repo_list_override = cfg["repos"]
+    else:
+        repo_list_override = None
+
+    # --- Logging ---
+    log_level = logging.DEBUG if verbose else logging.INFO
+    logging.basicConfig(
+        level=log_level,
+        format="%(message)s",
+        handlers=[RichHandler(rich_tracebacks=True, show_path=False)],
+    )
+    log = logging.getLogger("gh_weekly_updates")
+
+    # --- Auth ---
+    with console.status("[bold green]Authenticating with GitHub..."):
+        token = get_github_token()
+
+    # --- Resolve user ---
+    if not user:
+        with console.status("[bold green]Resolving GitHub username..."):
+            user = get_github_username(token)
+    console.print(f"[bold]User:[/bold] {user}")
+    if org:
+        console.print(f"[bold]Org:[/bold]  {org}")
+
+    # --- Date range ---
+    since_dt = _parse_date(since) if since else _default_since()
+    until_dt = _parse_date(until) if until else datetime.now(timezone.utc)
+
+    console.print(
+        f"[bold]Period:[/bold] {since_dt.strftime('%Y-%m-%d')} → "
+        f"{until_dt.strftime('%Y-%m-%d %H:%M')} UTC"
+    )
+
+    # --- Resolve repos ---
+    if repo_list_override:
+        repo_list = repo_list_override
+        console.print(f"[bold]Using configured repos:[/bold] {len(repo_list)}")
+    else:
+        with console.status("[bold green]Discovering repos you contributed to..."):
+            repo_list = discover_repos(token, user, since_dt, until_dt, org=org)
+
+    if not repo_list:
+        console.print("[yellow]No repos found for this period. Nothing to summarise.[/yellow]")
+        sys.exit(0)
+
+    console.print(f"[bold]Repos:[/bold] {len(repo_list)}")
+    for r in repo_list:
+        console.print(f"  • {r}")
+
+    # --- Collect activity ---
+    with console.status("[bold green]Collecting activity across repos..."):
+        activity = collect_activity(token, user, repo_list, since_dt, until_dt)
+
+    console.print(
+        Panel(
+            f"[bold]{activity.total_activities}[/bold] activities collected\n"
+            f"  PRs authored:         {len(activity.prs_authored)}\n"
+            f"  PRs reviewed:         {len(activity.prs_reviewed)}\n"
+            f"  Issues created:       {len(activity.issues_created)}\n"
+            f"  Issue comments:       {len(activity.issue_comments)}\n"
+            f"  Discussions created:  {len(activity.discussions_created)}\n"
+            f"  Discussion comments:  {len(activity.discussion_comments)}",
+            title="Activity Summary",
+            border_style="green",
+        )
+    )
+
+    if activity.total_activities == 0:
+        console.print("[yellow]No activities found. Nothing to summarise.[/yellow]")
+        sys.exit(0)
+
+    # --- Summarise ---
+    with console.status("[bold green]Generating impact summary via AI..."):
+        summary = summarise(activity, token, model, custom_prompt=custom_prompt)
+
+    # --- Output ---
+    if output:
+        with open(output, "w") as f:
+            f.write(summary)
+        console.print(f"\n[bold green]Summary written to {output}[/bold green]")
+    else:
+        console.print()
+        console.print(Markdown(summary))
+
+    # --- Push to repo ---
+    if push_repo:
+        with console.status(f"[bold green]Pushing to {push_repo}..."):
+            publish_to_repo(summary, push_repo, since_dt, until_dt)
+        console.print(
+            f"\n[bold green]Pushed to https://github.com/{push_repo}/tree/main/weekly-updates[/bold green]"
+        )
+
+
+if __name__ == "__main__":
+    main()