prgen-cli 0.2.1__py3-none-any.whl

prgen/config.py

@@ -0,0 +1,203 @@
+"""User config: JSON file under XDG config dir."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Literal, cast, get_args
+
+from prgen.defaults import ModelTier, ProviderChoice
+
+# Secrets merged into os.environ via load_prgen_env (setdefault only).
+SECRET_KEYS = frozenset(
+    {
+        "OPENAI_API_KEY",
+        "GOOGLE_API_KEY",
+    }
+)
+
+# Optional CLI defaults (same JSON file).
+SETTINGS_KEYS = frozenset({"base", "provider", "tier"})
+
+PERSISTED_KEYS = SECRET_KEYS | SETTINGS_KEYS
+
+PersistedConfigKey = Literal["OPENAI_API_KEY", "GOOGLE_API_KEY", "base", "provider", "tier"]
+assert frozenset(get_args(PersistedConfigKey)) == PERSISTED_KEYS
+
+CONFIG_FILENAME = "config.json"
+
+
+def config_dir() -> Path:
+    """XDG-style config directory: $XDG_CONFIG_HOME/prgen or ~/.config/prgen."""
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    if xdg:
+        return Path(xdg) / "prgen"
+    return Path.home() / ".config" / "prgen"
+
+
+def user_config_path() -> Path:
+    """Machine-wide config file (JSON)."""
+    return config_dir() / CONFIG_FILENAME
+
+
+def _atomic_write_json(path: Path, data: dict[str, str]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    text = json.dumps(data, indent=2, sort_keys=True) + "\n"
+    tmp = path.with_name(path.name + ".tmp")
+    tmp.write_text(text, encoding="utf-8")
+    tmp.replace(path)
+    try:
+        path.chmod(0o600)
+    except OSError:
+        pass
+
+
+def _normalize_raw_dict(raw: dict) -> dict[str, str]:
+    """Coerce JSON object to string values; skip non-scalars."""
+    out: dict[str, str] = {}
+    for k, v in raw.items():
+        if not isinstance(k, str):
+            continue
+        if v is None:
+            continue
+        if isinstance(v, str):
+            out[k] = v
+        elif isinstance(v, bool):
+            out[k] = str(v).lower()
+        elif isinstance(v, int | float):
+            out[k] = str(v)
+    return out
+
+
+def validate_persisted_config(data: dict[str, str], *, path_hint: Path | None = None) -> None:
+    """Raise ValueError if base/provider/tier are present but invalid."""
+    loc = f" in {path_hint}" if path_hint else ""
+    if "base" in data and not data["base"].strip():
+        raise ValueError(f"config key 'base' must be non-empty{loc}")
+    if "provider" in data:
+        p = data["provider"]
+        if p not in ("auto", "openai", "gemini"):
+            raise ValueError(
+                f"config key 'provider' must be auto, openai, or gemini{loc}; got {p!r}"
+            )
+    if "tier" in data:
+        t = data["tier"]
+        if t not in ("default", "pro"):
+            raise ValueError(f"config key 'tier' must be default or pro{loc}; got {t!r}")
+
+
+def _read_raw_config() -> dict[str, str]:
+    path = user_config_path()
+    if not path.is_file():
+        return {}
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise ValueError(
+            f"Invalid JSON in {path}: {exc}. Fix or remove the file and run prgen config."
+        ) from exc
+    if not isinstance(raw, dict):
+        raise ValueError(f"{path} must contain a JSON object.")
+    out = _normalize_raw_dict(raw)
+    validate_persisted_config(out, path_hint=path)
+    return out
+
+
+def read_persisted_config() -> dict[str, str]:
+    """Load validated config.json; empty dict if the file is missing."""
+    return _read_raw_config()
+
+
+def load_prgen_env() -> None:
+    """Merge secret keys from config.json into os.environ (setdefault only)."""
+    data = _read_raw_config()
+    for key in SECRET_KEYS:
+        if key in data:
+            os.environ.setdefault(key, data[key])
+
+
+DISPLAY_KEY_ORDER: tuple[str, ...] = (
+    "OPENAI_API_KEY",
+    "GOOGLE_API_KEY",
+    "base",
+    "provider",
+    "tier",
+)
+
+
+def public_config_rows() -> list[tuple[str, str, bool]]:
+    """Safe rows for printing: (key, display_value, is_secret).
+
+    Secrets are never echoed; value is \"set\" or \"unset\".
+    """
+    data = _read_raw_config()
+    rows: list[tuple[str, str, bool]] = []
+    for key in DISPLAY_KEY_ORDER:
+        is_secret = key in SECRET_KEYS
+        if is_secret:
+            raw = data.get(key, "")
+            disp = "set" if (isinstance(raw, str) and raw.strip()) else "unset"
+        else:
+            raw = data.get(key)
+            if raw is None or not str(raw).strip():
+                disp = "unset"
+            else:
+                disp = str(raw).strip()
+        rows.append((key, disp, is_secret))
+    return rows
+
+
+def read_cli_defaults_from_config() -> tuple[str | None, ProviderChoice | None, ModelTier | None]:
+    """Optional base, provider, tier from config.json (CLI uses when flags are omitted)."""
+    data = _read_raw_config()
+    base: str | None = None
+    if "base" in data:
+        b = data["base"].strip()
+        if b:
+            base = b
+    provider: ProviderChoice | None = None
+    if "provider" in data:
+        provider = cast(ProviderChoice, data["provider"])
+    tier: ModelTier | None = None
+    if "tier" in data:
+        tier = cast(ModelTier, data["tier"])
+    return base, provider, tier
+
+
+def set_user_key(key: str, value: str) -> Path:
+    """Set KEY in config.json (creates or updates)."""
+    k = key.strip()
+    if k not in PERSISTED_KEYS:
+        raise ValueError(f"Unsupported key {k!r}. Supported: {', '.join(sorted(PERSISTED_KEYS))}")
+    path = user_config_path()
+    data = _read_raw_config()
+    data[k] = value.strip()
+    clean = {k2: v2 for k2, v2 in data.items() if k2 in PERSISTED_KEYS}
+    validate_persisted_config(clean, path_hint=path)
+    _atomic_write_json(path, clean)
+    return path
+
+
+def unset_user_key(key: str) -> Path:
+    """Remove KEY from config.json."""
+    k = key.strip()
+    if k not in PERSISTED_KEYS:
+        raise ValueError(f"Unsupported key {k!r}. Supported: {', '.join(sorted(PERSISTED_KEYS))}")
+    path = user_config_path()
+    if not path.is_file():
+        raise ValueError(f"No config file: {path}")
+    data = _read_raw_config()
+    if k not in data:
+        raise ValueError(f"Key {k!r} not found in {path}")
+    del data[k]
+    clean = {k2: v2 for k2, v2 in data.items() if k2 in PERSISTED_KEYS}
+    if clean:
+        validate_persisted_config(clean, path_hint=path)
+        _atomic_write_json(path, clean)
+    else:
+        try:
+            path.unlink()
+        except OSError:
+            pass
+    return path

prgen/defaults.py

@@ -0,0 +1,24 @@
+"""Model presets per provider: default (efficient) vs pro (strongest)."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+ModelTier = Literal["default", "pro"]
+ProviderChoice = Literal["auto", "openai", "gemini"]
+
+OPENAI_MODELS: dict[ModelTier, str] = {
+    "default": "gpt-5.4-mini",
+    "pro": "gpt-5.4",
+}
+
+# Default: gemini-3-flash-preview (standard Flash). For lower cost/latency use
+# gemini-3.1-flash-lite-preview instead.
+GEMINI_MODELS: dict[ModelTier, str] = {
+    "default": "gemini-3-flash-preview",
+    "pro": "gemini-3.1-pro-preview",
+}
+
+
+def model_for_tier(backend: Literal["openai", "gemini"], tier: ModelTier) -> str:
+    return (OPENAI_MODELS if backend == "openai" else GEMINI_MODELS)[tier]

prgen/git_utils.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+
+class GitRefError(ValueError):
+    """Raised when a git ref cannot be resolved."""
+
+
+class GitNotFoundError(RuntimeError):
+    """Raised when the git executable is not available."""
+
+
+def ensure_git_available() -> None:
+    """Raise GitNotFoundError if `git` is not installed or not on PATH."""
+    if shutil.which("git") is None:
+        raise GitNotFoundError(
+            "git is not installed or not on your PATH. Install Git and ensure `git` is available."
+        )
+
+
+def run_git_command(args: list[str], *, cwd: Path | None = None) -> str:
+    kw: dict = {"capture_output": True, "text": True, "check": True}
+    if cwd is not None:
+        kw["cwd"] = cwd
+    result = subprocess.run(["git", *args], **kw)
+    return result.stdout.strip()
+
+
+def verify_base_ref(base: str, *, cwd: Path | None = None) -> None:
+    """Ensure `base` resolves so `git diff base...HEAD` and `git log base..HEAD` work."""
+    r = subprocess.run(
+        ["git", "rev-parse", "-q", "--verify", base],
+        cwd=cwd,
+        capture_output=True,
+        text=True,
+    )
+    if r.returncode != 0:
+        raise GitRefError(
+            f"Cannot resolve --base {base!r}. "
+            "If you meant the remote default branch, try: git fetch origin   "
+            f"or pass an existing local branch, e.g. --base main"
+        )
+
+
+def git_repo_root(path: Path) -> Path:
+    """Resolve path and verify it is inside a git working tree."""
+    resolved = path.resolve()
+    r = subprocess.run(
+        ["git", "-C", str(resolved), "rev-parse", "--show-toplevel"],
+        capture_output=True,
+        text=True,
+    )
+    if r.returncode != 0:
+        msg = (r.stderr or r.stdout or "not a git repository").strip()
+        raise ValueError(f"{resolved}: {msg}")
+    return Path(r.stdout.strip())
+
+
+def get_diff(base: str = "origin/main", *, cwd: Path | None = None) -> str:
+    return run_git_command(["diff", f"{base}...HEAD"], cwd=cwd)
+
+
+def get_commits(base: str = "origin/main", *, cwd: Path | None = None) -> str:
+    return run_git_command(
+        [
+            "log",
+            "--format=<commit-message %cI>%n%s%n%n%b%n<end-of-commit-message>",
+            f"{base}..HEAD",
+        ],
+        cwd=cwd,
+    )

prgen/prompting.py

@@ -0,0 +1,23 @@
+from importlib.resources import files
+
+
+def load_prompt_template() -> str:
+    return (
+        files("prgen")
+        .joinpath("prompts")
+        .joinpath("pr_description.txt")
+        .read_text(encoding="utf-8")
+    )
+
+
+def build_prompt(
+    template: str,
+    diff: str,
+    commits: str,
+    additional_context: str,
+) -> str:
+    return (
+        template.replace("{{DIFF}}", diff or "No diff provided.")
+        .replace("{{COMMITS}}", commits or "No commits provided.")
+        .replace("{{ADDITIONAL_CONTEXT}}", additional_context or "none")
+    )

prgen/prompts/pr_description.txt

@@ -0,0 +1,64 @@
+You are an advanced AI programming assistant and are tasked with summarizing code changes into a concise but meaningful pull request title and description.
+
+You will be provided with:
+- a code diff
+- a list of commits
+- optional additional context
+
+Your goal is to analyze the changes and create a clear, informative title and description that accurately represents the modifications made to the code.
+
+First, examine the following code changes provided in Git diff format:
+
+<~~diff~~>
+{{DIFF}}
+</~~diff~~>
+
+Then, review the list of commits to help understand the motivation behind the changes and any relevant background information:
+
+<~~data~~>
+{{COMMITS}}
+</~~data~~>
+
+Now, if provided, use this context to understand the motivation behind the changes and any relevant background information:
+
+<~~additional-context~~>
+{{ADDITIONAL_CONTEXT}}
+</~~additional-context~~>
+
+To create an effective pull request title and description, follow these steps:
+
+1. Carefully analyze the diff, commit messages, and context, focusing on:
+- The purpose and rationale of the changes
+- Any problems addressed or benefits introduced
+- Any significant logic changes or algorithmic improvements
+
+2. Ensure the following when composing the pull request title and description:
+- Emphasize the "why" of the change, its benefits, or the problem it addresses
+- Use an informal yet professional tone
+- Use a future-oriented manner, third-person singular present tense
+- Be clear and concise
+- Synthesize only meaningful information from the diff and context
+- Avoid outputting code, specific code identifiers, names, or file names unless crucial for understanding
+- Avoid repeating information, broad generalities, and unnecessary phrases
+
+3. Summarize the main purpose of the changes in a single, concise sentence:
+- Start with a third-person singular present tense verb
+- Limit to 50 characters if possible
+
+4. Provide a detailed explanation of the changes:
+- Add line breaks for readability
+- Focus on the "why" rather than only the "what"
+- Structure the body with markdown bullets and headings
+
+5. If relevant, include any issue reference at the end
+
+Write your title inside <summary> tags and your description inside <body> tags and include no other text.
+
+Output structure:
+
+<summary>
+[pull-request-title]
+</summary>
+<body>
+[pull-request-body]
+</body>

prgen/providers/gemini_provider.py

@@ -0,0 +1,29 @@
+from dataclasses import dataclass
+
+from prgen.defaults import GEMINI_MODELS
+
+
+@dataclass
+class GeminiProvider:
+    api_key: str
+    model: str = GEMINI_MODELS["default"]
+
+    def generate(self, prompt: str) -> str:
+        try:
+            from google import genai
+            from google.genai import types
+        except ImportError as exc:
+            raise ImportError(
+                "The Google GenAI SDK is not installed. Install with: pip install google-genai"
+            ) from exc
+
+        client = genai.Client(api_key=self.api_key)
+        response = client.models.generate_content(
+            model=self.model,
+            contents=prompt,
+            config=types.GenerateContentConfig(
+                temperature=0.2,
+                max_output_tokens=8192,
+            ),
+        )
+        return (response.text or "").strip()

prgen/providers/openai_provider.py

@@ -0,0 +1,29 @@
+from dataclasses import dataclass
+
+from prgen.defaults import OPENAI_MODELS
+
+
+@dataclass
+class OpenAIProvider:
+    api_key: str
+    model: str = OPENAI_MODELS["default"]
+
+    def generate(self, prompt: str) -> str:
+        try:
+            from openai import OpenAI
+        except ImportError as exc:
+            raise ImportError(
+                "The OpenAI SDK is not installed. Install with: pip install openai"
+            ) from exc
+
+        client = OpenAI(api_key=self.api_key)
+
+        response = client.responses.create(
+            model=self.model,
+            input=prompt,
+            temperature=0.2,
+            max_output_tokens=8192,
+            store=False,
+        )
+
+        return response.output_text.strip()

prgen/ui.py

@@ -0,0 +1,87 @@
+"""Terminal output and loading indicator (Rich)."""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+from rich.console import Console
+from rich.text import Text
+
+from prgen.about import AUTHOR, REPO_URL, package_version
+
+
+def _stderr_console() -> Console:
+    return Console(stderr=True, highlight=False)
+
+
+def _stdout_console() -> Console:
+    # highlight=False: don't treat diff-like output as Python/etc.
+    return Console(highlight=False, soft_wrap=True)
+
+
+def _print_generation_credit(console: Console) -> None:
+    """Footer after model output: tool version + author (distinct from PR body for copy/paste)."""
+    v = package_version()
+    console.print(
+        "[dim]—[/dim] [dim]Generated with[/dim] [bold cyan]prgen[/bold cyan] "
+        f"[dim]v{v}[/dim] [dim]·[/dim] [dim]{AUTHOR}[/dim]"
+    )
+    console.print(f"[dim]{REPO_URL}[/dim]")
+
+
+@contextmanager
+def loading(message: str = "Generating PR summary", *, model: str | None = None) -> Iterator[None]:
+    """Show a Rich spinner on stderr while the block runs (no-op if stderr is not a TTY)."""
+    if not sys.stderr.isatty():
+        yield
+        return
+
+    console = _stderr_console()
+    label = f"[bold cyan]{message}[/bold cyan]"
+    if model:
+        label += f"  [dim]{model}[/dim]"
+
+    with console.status(
+        label,
+        spinner="dots2",
+        spinner_style="cyan",
+        speed=0.9,
+    ):
+        yield
+
+
+def print_pr_summary(
+    title: str | None,
+    body: str | None,
+    raw_fallback: str,
+) -> None:
+    """
+    Print title/body with styled headers; body is plain text (copy/paste friendly, no box borders).
+    """
+    console = _stdout_console()
+
+    if title is not None and body is not None:
+        console.print()
+        console.print("[bold green]PR title[/bold green]")
+        # Text: no Rich markup parsing in model output (brackets, markdown).
+        console.print(Text(title.strip()))
+        console.print()
+        console.print("[bold blue]PR description[/bold blue]")
+        console.print(Text(body.strip()))
+        console.print()
+        _print_generation_credit(console)
+        console.print()
+        return
+
+    text = raw_fallback.rstrip()
+    if not text:
+        return
+
+    console.print()
+    console.print("[bold yellow]Model output[/bold yellow] [dim](no <summary>/<body> tags)[/dim]")
+    console.print(Text(text))
+    console.print()
+    _print_generation_credit(console)
+    console.print()

prgen_cli-0.2.1.dist-info/METADATA

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: prgen-cli
+Version: 0.2.1
+Summary: Generate PR titles and descriptions from git diff
+Author: Jean Paul Fernandez
+License-Expression: GPL-3.0-only
+Project-URL: Homepage, https://github.com/jpxoi/prgen
+Project-URL: Repository, https://github.com/jpxoi/prgen
+Project-URL: Issues, https://github.com/jpxoi/prgen/issues
+Keywords: cli,git,pull-request,diff,llm,openai,gemini
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Version Control
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: google-genai>=1.70.0
+Requires-Dist: openai>=2.30.0
+Requires-Dist: rich>=14.3.3
+Requires-Dist: typer>=0.24.1
+Dynamic: license-file
+
+# prgen
+
+Generate a pull request title and description from `git diff` and commit history.
+
+**Author:** Jean Paul Fernandez · [github.com/jpxoi/prgen](https://github.com/jpxoi/prgen)
+
+Licensed under the [GNU General Public License v3.0](LICENSE) (GPL-3.0-only): you may share and modify this program under those terms; see the license file for full conditions.
+
+## Requirements
+
+- **Python** 3.10+
+- **`git`** on your `PATH` (install Git and ensure `git` works in a terminal)
+
+## Install
+
+From PyPI, install the **`prgen-cli`** package; the **`prgen`** command is what you run in the terminal.
+
+From [PyPI](https://pypi.org/project/prgen-cli/):
+
+```bash
+pip install prgen-cli
+# or
+uv tool install prgen-cli
+```
+
+From a clone (installs all dependencies):
+
+```bash
+uv sync
+```
+
+Formatting / lint (see `[tool.ruff]` in `pyproject.toml`):
+
+```bash
+uv run ruff format .
+uv run ruff check .
+```
+
+## Setup
+
+Store settings in **`~/.config/prgen/config.json`** using **`prgen config`** (interactive prompts, or `prgen config set …`). Supported fields:
+
+- `OPENAI_API_KEY` — OpenAI API key (also merged into the environment when you run `prgen`, if not already set)
+- `GOOGLE_API_KEY` — Google AI Studio / Gemini API key (same behavior)
+- `base` — optional default for **`--base`** (see [Defaults](#defaults) below)
+- `provider` — optional default for **`--provider`**
+- `tier` — optional default for **`--tier`**
+
+Override the config directory with **`XDG_CONFIG_HOME`** (file is `$XDG_CONFIG_HOME/prgen/config.json`).
+
+## Defaults
+
+Defaults apply to the **main** `prgen` command (generating a PR summary), not to `prgen config …` subcommands.
+
+### Built-in CLI defaults (no config file)
+
+If you do not pass a flag and the key is **not** set in `config.json`, prgen uses:
+
+| What | Default | Meaning |
+| ---: | ---: | ---: |
+| Git repo | current directory | Diff and log are for the repo you run from. Use **`-C` / `--repo`** for another tree. |
+| **`--base`** | `origin/main` | Compare `HEAD` to this ref (`git diff` / `git log` vs merge base). The ref must exist locally (e.g. run **`git fetch origin`** or use a local branch like `main`). |
+| **`--provider`** | `auto` | Pick a backend from your API keys: **Gemini** if `GOOGLE_API_KEY` is set, otherwise **OpenAI** if `OPENAI_API_KEY` is set. If neither is set, prgen exits with an error until you configure keys. |
+| **`--tier`** | `default` | Cheaper/faster model preset. **`pro`** selects a stronger model for the chosen provider. |
+| **`--model`** | *(unset)* | Use the model for the current **`--tier`** (see presets in the source under `defaults.py`). **`--model ID`** overrides **`--tier`** entirely. |
+| **`--context`** | `none` | Extra text merged into the prompt; the literal string **`none`** means “no extra context” unless you change it. |
+
+### Optional overrides from `config.json`
+
+If **`base`**, **`provider`**, or **`tier`** appear in `config.json`, they **replace** the built-in defaults **only when you do not pass the matching flag**.
+
+- Example: `base` in JSON is `main`, and you run **`prgen`** with no **`--base`** → effective base is **`main`**.
+- Example: same config, but you run **`prgen --base origin/main`** → **`--base`** wins; the file is ignored for that run.
+
+**`--model`** and **`--context`** are not read from the JSON file; only **`base`**, **`provider`**, and **`tier`** are.
+
+### Summary
+
+- **Config file** fills in **`--base`**, **`--provider`**, and **`--tier`** when those flags are omitted.
+- **Explicit flags** always override the file.
+- **`auto`** chooses Gemini vs OpenAI from which API keys are available (see **`--provider`** above).
+
+### Set keys from the CLI
+
+Writes go to **`~/.config/prgen/config.json`** (see `prgen config path`). Allowed keys: **`OPENAI_API_KEY`**, **`GOOGLE_API_KEY`**, **`base`**, **`provider`**, **`tier`**.
+
+```bash
+prgen config                    # wizard: API keys + base, provider, tier (Rich prompts)
+prgen config set OPENAI_API_KEY sk-...
+prgen config set GOOGLE_API_KEY - < key.txt    # value read from stdin
+prgen config unset OPENAI_API_KEY
+prgen config show                              # safe summary (keys as set/unset; colors if TTY)
+prgen config path                              # print path to the file
+```
+
+## Run on another project
+
+Use **`-C`** (same idea as `git -C`) so you can run `prgen` from anywhere:
+
+```bash
+prgen -C ~/src/my-application
+```
+
+If `prgen` is not on your `PATH`, invoke it via `uv` from the prgen repo:
+
+```bash
+uv run --directory /path/to/prgen prgen -C ~/src/my-application
+```
+
+## Install globally (optional)
+
+From the prgen project directory:
+
+```bash
+uv tool install .
+# or
+pipx install .
+```
+
+Then `prgen` is available in new shells (ensure your tool install `bin` directory is on `PATH`).
+
+## Options
+
+See **`prgen --help`** for all flags. In addition to [Defaults](#defaults):
+
+- If there is **no diff and no commits** compared to **`--base`**, prgen exits with an error (nothing to summarize).