devgen-cli 0.2.4__tar.gz → 0.2.6__tar.gz

devgen_cli-0.2.6/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: devgen-cli
+Version: 0.2.6
+Summary: A collection of developer tools
+Home-page: https://github.com/S4NKALP/devgen
+Author: Sankalp Tharu
+Author-email: Sankalp Tharu <sankalptharu50028@gmail.com>
+License: GPL-3.0-or-later
+Project-URL: Homepage, https://github.com/S4NKALP/devgen
+Keywords: devgen,cli,git,changelog,gitignore,license,commit-generator,commit
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: anthropic>=0.75.0
+Requires-Dist: google-genai>=0.1.0
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: openai>=2.11.0
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: questionary>=2.1.1
+Requires-Dist: requests>=2.32.5
+Requires-Dist: rich>=14.2.0
+Requires-Dist: toml>=0.10.2
+Requires-Dist: typer>=0.20.0
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# DevGen
+
+<div align="center">
+
+**AI-Powered Git & Project Workflows in One CLI**
+
+Stop wasting time on repetitive tasks. DevGen automates commits, changelogs, `.gitignore`, and license files using AI — from cloud providers or a local Ollama model.
+
+> PyPI didn't allow the original name, so you'll find it as **devgen-cli** on PyPI
+
+> <a href="https://pypi.org/project/devgen-cli"><img src="https://img.shields.io/pypi/v/devgen-cli?color=blue&label=PyPI&logo=pypi&logoColor=white" alt="PyPI"></a>
+> <img src="https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white" alt="Python">
+> <a href="https://github.com/S4NKALP/DevGen/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-GPL--3.0--or--later-blue.svg" alt="License"></a>
+> <a href="https://github.com/S4NKALP/DevGen/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/S4NKALP/DevGen/ci.yml?branch=main&label=CI" alt="CI"></a>
+> <a href="https://github.com/S4NKALP/DevGen/actions/workflows/pre-commit.yml"><img src="https://img.shields.io/github/actions/workflow/status/S4NKALP/DevGen/pre-commit.yml?branch=main&label=Pre-Commit" alt="Pre-Commit"></a>
+
+</div>
+
+## Why DevGen
+
+DevGen is a CLI for the parts of development that should be invisible. It writes Conventional Commits from your diff, drafts SemVer changelogs, fetches `.gitignore` and license templates, and routes everything through whichever AI provider you prefer — including a fully local Ollama model if you don't want to send code to the cloud.
+
+## Features
+
+- **AI-Powered Commits** — Conventional Commit messages generated from your staged diff, grouped by directory, with optional emoji prefixes.
+- **Multiple Providers** — Google Gemini, OpenAI, Anthropic, OpenRouter, HuggingFace, and local Ollama, all behind one CLI.
+- **Smart Caching** — `.gitignore` and license templates are cached for offline use; AI responses are de-duplicated.
+- **Conventional Changelogs** — `feat`, `fix`, `refactor`, `perf`, `docs`, `test`, `build`, `ci`, `chore`, `style`, and a `BREAKING CHANGES` section.
+- **Project Scaffolding** — Pull `.gitignore` from GitHub's collection and drop in SPDX license files (MIT, Apache-2.0, GPL-3.0, AGPL-3.0, BSD, MPL-2.0, …).
+- **Custom Templates** — Override the commit-message prompt via a `.tpl` file in your config.
+- **Interactive Setup** — `devgen setup` walks you through provider + API key + options.
+- **Undo Support** — `devgen commit undo` rolls back the last AI commit while keeping changes staged.
+- **Token-Limit Aware** — When a diff exceeds a model's context window, you get a single actionable error with `--max-groups` and `--max-diff-size` hints.
+
+## Supported AI Providers
+
+| Provider          | Notes                                                |
+| ----------------- | ---------------------------------------------------- |
+| **Google Gemini** | Default-friendly, generous free tier                 |
+| **OpenAI**        | GPT-4o, GPT-4.1, o-series                            |
+| **Anthropic**     | Claude 3.5 / 3.7 / 4                                 |
+| **OpenRouter**    | Single key, many models                              |
+| **HuggingFace**   | Inference API                                        |
+| **Ollama**        | Fully local, no API key, no data leaves your machine |
+
+## Installation
+
+```bash
+# Recommended: isolated environment
+pipx install devgen-cli
+
+# Or use uv for speed
+uv tool install devgen-cli
+
+# Or plain pip
+pip install devgen-cli
+
+# Shell completion (bash/zsh/fish)
+devgen --install-completion
+```
+
+Requires **Python 3.10 or newer**.
+
+## Quick Start
+
+```bash
+# 1. Configure a provider and API key
+devgen setup config
+
+# 2. Stage your work as usual
+git add .
+
+# 3. Let DevGen write the commit message
+devgen commit run
+
+# 4. Or preview first, then commit
+devgen commit run --dry-run
+devgen commit run --push
+```
+
+## Commands
+
+| Command                         | Description                                                                   |
+| ------------------------------- | ----------------------------------------------------------------------------- |
+| `devgen setup config`           | Interactive provider / API key / options wizard                               |
+| `devgen commit run`             | Stage, generate message, commit (optionally `--push`, `--check`, `--dry-run`) |
+| `devgen commit undo`            | Undo the last AI commit, keep changes staged                                  |
+| `devgen changelog`              | Generate a Conventional Commits changelog from recent history                 |
+| `devgen release-notes`          | Generate release notes for a version range                                    |
+| `devgen gitignore list`         | List available GitHub `.gitignore` templates                                  |
+| `devgen gitignore add <name> …` | Add `.gitignore` entries to the current project                               |
+| `devgen license list`           | List available SPDX licenses                                                  |
+| `devgen license add <spdx>`     | Add a LICENSE file to the current project                                     |
+
+Run `devgen <command> --help` for full options on any subcommand.
+
+## Custom Templates
+
+DevGen uses `.tpl` files for its commit prompt. To override the default, set `custom_template` in your config (see `devgen config info`) and point it at a `.tpl` file with `{{ diff_text }}`, `{{ context }}`, `{{ group_name }}`, and the conditional `{% if use_emoji %}` block.
+
+Example minimal template:
+
+```
+{{ diff_text }}
+Summarize the change above in one Conventional Commit line.
+```
+
+## Architecture
+
+DevGen is built around a small set of composable components:
+
+- **`BaseProvider`** — abstract base for every AI provider; handles API-key validation, token-limit detection, and error wrapping. Adding a new provider is one subclass with a single `_generate()` method.
+- **`GitOperator`** — all `subprocess` calls to `git` live here, behind a `GitError` exception.
+- **`DiffBuilder` / `FileGrouper` / `ManifestInspector`** — split a staged diff into per-directory groups with compact project context, so the model sees a focused slice instead of a wall of text.
+- **`Section` enum** — single source of truth for changelog ordering and emoji, shared by `ChangelogGenerator` and `ReleaseNotesGenerator`.
+
+The CLI entry point is `devgen.cli.main:app` (Typer), exposed as the `devgen` script.
+
+## Development
+
+```bash
+git clone https://github.com/S4NKALP/DevGen.git
+cd DevGen
+uv sync --all-extras --dev      # install runtime + dev deps
+uv run pre-commit run --all-files
+uv run devgen --help
+```
+
+The project uses `uv` for dependency management, `ruff` for lint + format, and `pyright` for type checking. CI runs all three on Python 3.10 through 3.13 (see `.github/workflows/ci.yml`).
+
+## Contributing
+
+Issues and PRs welcome. Please run `uv run pre-commit run --all-files` before opening a PR so CI stays green.
+
+## License
+
+GPL-3.0-or-later. See [LICENSE](LICENSE).
+
+## Acknowledgments
+
+Built on the shoulders of:
+
+- **Typer** & **Rich** — CLI and terminal UI
+- **Questionary** — interactive prompts
+- **Google Gemini**, **OpenAI**, **Anthropic**, **OpenRouter**, **HuggingFace**, and **Ollama** — AI providers
+- **Ruff** — lint and format
+
+<div align="center">
+Made with ❤️ by <a href="https://github.com/S4NKALP">Sankalp</a>
+</div>

devgen_cli-0.2.6/README.md

@@ -0,0 +1,150 @@
+# DevGen
+
+<div align="center">
+
+**AI-Powered Git & Project Workflows in One CLI**
+
+Stop wasting time on repetitive tasks. DevGen automates commits, changelogs, `.gitignore`, and license files using AI — from cloud providers or a local Ollama model.
+
+> PyPI didn't allow the original name, so you'll find it as **devgen-cli** on PyPI
+
+> <a href="https://pypi.org/project/devgen-cli"><img src="https://img.shields.io/pypi/v/devgen-cli?color=blue&label=PyPI&logo=pypi&logoColor=white" alt="PyPI"></a>
+> <img src="https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white" alt="Python">
+> <a href="https://github.com/S4NKALP/DevGen/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-GPL--3.0--or--later-blue.svg" alt="License"></a>
+> <a href="https://github.com/S4NKALP/DevGen/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/S4NKALP/DevGen/ci.yml?branch=main&label=CI" alt="CI"></a>
+> <a href="https://github.com/S4NKALP/DevGen/actions/workflows/pre-commit.yml"><img src="https://img.shields.io/github/actions/workflow/status/S4NKALP/DevGen/pre-commit.yml?branch=main&label=Pre-Commit" alt="Pre-Commit"></a>
+
+</div>
+
+## Why DevGen
+
+DevGen is a CLI for the parts of development that should be invisible. It writes Conventional Commits from your diff, drafts SemVer changelogs, fetches `.gitignore` and license templates, and routes everything through whichever AI provider you prefer — including a fully local Ollama model if you don't want to send code to the cloud.
+
+## Features
+
+- **AI-Powered Commits** — Conventional Commit messages generated from your staged diff, grouped by directory, with optional emoji prefixes.
+- **Multiple Providers** — Google Gemini, OpenAI, Anthropic, OpenRouter, HuggingFace, and local Ollama, all behind one CLI.
+- **Smart Caching** — `.gitignore` and license templates are cached for offline use; AI responses are de-duplicated.
+- **Conventional Changelogs** — `feat`, `fix`, `refactor`, `perf`, `docs`, `test`, `build`, `ci`, `chore`, `style`, and a `BREAKING CHANGES` section.
+- **Project Scaffolding** — Pull `.gitignore` from GitHub's collection and drop in SPDX license files (MIT, Apache-2.0, GPL-3.0, AGPL-3.0, BSD, MPL-2.0, …).
+- **Custom Templates** — Override the commit-message prompt via a `.tpl` file in your config.
+- **Interactive Setup** — `devgen setup` walks you through provider + API key + options.
+- **Undo Support** — `devgen commit undo` rolls back the last AI commit while keeping changes staged.
+- **Token-Limit Aware** — When a diff exceeds a model's context window, you get a single actionable error with `--max-groups` and `--max-diff-size` hints.
+
+## Supported AI Providers
+
+| Provider          | Notes                                                |
+| ----------------- | ---------------------------------------------------- |
+| **Google Gemini** | Default-friendly, generous free tier                 |
+| **OpenAI**        | GPT-4o, GPT-4.1, o-series                            |
+| **Anthropic**     | Claude 3.5 / 3.7 / 4                                 |
+| **OpenRouter**    | Single key, many models                              |
+| **HuggingFace**   | Inference API                                        |
+| **Ollama**        | Fully local, no API key, no data leaves your machine |
+
+## Installation
+
+```bash
+# Recommended: isolated environment
+pipx install devgen-cli
+
+# Or use uv for speed
+uv tool install devgen-cli
+
+# Or plain pip
+pip install devgen-cli
+
+# Shell completion (bash/zsh/fish)
+devgen --install-completion
+```
+
+Requires **Python 3.10 or newer**.
+
+## Quick Start
+
+```bash
+# 1. Configure a provider and API key
+devgen setup config
+
+# 2. Stage your work as usual
+git add .
+
+# 3. Let DevGen write the commit message
+devgen commit run
+
+# 4. Or preview first, then commit
+devgen commit run --dry-run
+devgen commit run --push
+```
+
+## Commands
+
+| Command                         | Description                                                                   |
+| ------------------------------- | ----------------------------------------------------------------------------- |
+| `devgen setup config`           | Interactive provider / API key / options wizard                               |
+| `devgen commit run`             | Stage, generate message, commit (optionally `--push`, `--check`, `--dry-run`) |
+| `devgen commit undo`            | Undo the last AI commit, keep changes staged                                  |
+| `devgen changelog`              | Generate a Conventional Commits changelog from recent history                 |
+| `devgen release-notes`          | Generate release notes for a version range                                    |
+| `devgen gitignore list`         | List available GitHub `.gitignore` templates                                  |
+| `devgen gitignore add <name> …` | Add `.gitignore` entries to the current project                               |
+| `devgen license list`           | List available SPDX licenses                                                  |
+| `devgen license add <spdx>`     | Add a LICENSE file to the current project                                     |
+
+Run `devgen <command> --help` for full options on any subcommand.
+
+## Custom Templates
+
+DevGen uses `.tpl` files for its commit prompt. To override the default, set `custom_template` in your config (see `devgen config info`) and point it at a `.tpl` file with `{{ diff_text }}`, `{{ context }}`, `{{ group_name }}`, and the conditional `{% if use_emoji %}` block.
+
+Example minimal template:
+
+```
+{{ diff_text }}
+Summarize the change above in one Conventional Commit line.
+```
+
+## Architecture
+
+DevGen is built around a small set of composable components:
+
+- **`BaseProvider`** — abstract base for every AI provider; handles API-key validation, token-limit detection, and error wrapping. Adding a new provider is one subclass with a single `_generate()` method.
+- **`GitOperator`** — all `subprocess` calls to `git` live here, behind a `GitError` exception.
+- **`DiffBuilder` / `FileGrouper` / `ManifestInspector`** — split a staged diff into per-directory groups with compact project context, so the model sees a focused slice instead of a wall of text.
+- **`Section` enum** — single source of truth for changelog ordering and emoji, shared by `ChangelogGenerator` and `ReleaseNotesGenerator`.
+
+The CLI entry point is `devgen.cli.main:app` (Typer), exposed as the `devgen` script.
+
+## Development
+
+```bash
+git clone https://github.com/S4NKALP/DevGen.git
+cd DevGen
+uv sync --all-extras --dev      # install runtime + dev deps
+uv run pre-commit run --all-files
+uv run devgen --help
+```
+
+The project uses `uv` for dependency management, `ruff` for lint + format, and `pyright` for type checking. CI runs all three on Python 3.10 through 3.13 (see `.github/workflows/ci.yml`).
+
+## Contributing
+
+Issues and PRs welcome. Please run `uv run pre-commit run --all-files` before opening a PR so CI stays green.
+
+## License
+
+GPL-3.0-or-later. See [LICENSE](LICENSE).
+
+## Acknowledgments
+
+Built on the shoulders of:
+
+- **Typer** & **Rich** — CLI and terminal UI
+- **Questionary** — interactive prompts
+- **Google Gemini**, **OpenAI**, **Anthropic**, **OpenRouter**, **HuggingFace**, and **Ollama** — AI providers
+- **Ruff** — lint and format
+
+<div align="center">
+Made with ❤️ by <a href="https://github.com/S4NKALP">Sankalp</a>
+</div>

{devgen_cli-0.2.4 → devgen_cli-0.2.6}/devgen/ai.py

@@ -21,8 +21,17 @@ def generate_with_ai(
         provider_module = import_module(f"devgen.providers.{provider}")
         class_name = "".join([x.capitalize() for x in provider.split("_")]) + "Provider"
         provider_class = getattr(provider_module, class_name)
-    except (ModuleNotFoundError, AttributeError) as e:
-        raise ImportError(f"Provider `{provider}` not found or invalid: {e}") from e
+    except ModuleNotFoundError as e:
+        raise ImportError(
+            f"Provider `{provider}` is not a built-in module: {e}. "
+            f"Available providers: gemini, openai, anthropic, huggingface, "
+            f"openrouter, ollama."
+        ) from e
+    except AttributeError as e:
+        raise ImportError(
+            f"Provider `{provider}` exists but does not expose a "
+            f"`{class_name}` class. This is a packaging bug."
+        ) from e
 
     provider_instance = provider_class()
     return provider_instance.generate(prompt, api_key=api_key, model=model, **kwargs)

{devgen_cli-0.2.4 → devgen_cli-0.2.6}/devgen/cli/commit.py

@@ -58,12 +58,28 @@ def run_commit(
             help="Review/edit commit message before committing.",
         ),
     ] = False,
+    max_groups: Annotated[
+        int | None,
+        typer.Option(
+            "--max-groups",
+            help="Maximum number of commit groups. Lower this if you hit token-limit errors.",
+        ),
+    ] = None,
+    max_diff_size: Annotated[
+        int | None,
+        typer.Option(
+            "--max-diff-size",
+            help="Maximum diff size in chars per group (default 8000). "
+            "Lower this if you hit token-limit errors.",
+        ),
+    ] = None,
 ) -> None:
     log_file = get_main_log_path()
     logger = configure_logger("devgen.cli.commit", log_file, console=debug)
     logger.info(f"Log file: {log_file}")
     logger.info(
-        f"Options: dry_run={dry_run}, push={push}, debug={debug}, force={force_rebuild}, check={check}"
+        f"Options: dry_run={dry_run}, push={push}, debug={debug}, force={force_rebuild}, "
+        f"check={check}, max_groups={max_groups}, max_diff_size={max_diff_size}"
     )
 
     run_commit_engine(
@@ -73,6 +89,8 @@ def run_commit(
         force_rebuild=force_rebuild,
         check=check,
         logger=logger,
+        max_groups=max_groups,
+        max_diff_size=max_diff_size,
     )
 
 

{devgen_cli-0.2.4 → devgen_cli-0.2.6}/devgen/cli/config.py

@@ -62,7 +62,14 @@ def edit_config(
         if key == "provider":
             value = questionary.select(
                 "Select AI Provider:",
-                choices=["gemini", "openai", "huggingface", "openrouter", "anthropic"],
+                choices=[
+                    "gemini",
+                    "openai",
+                    "huggingface",
+                    "openrouter",
+                    "anthropic",
+                    "ollama",
+                ],
                 default=str(current_val) if current_val else "gemini",
                 style=style,
             ).ask()
@@ -117,7 +124,14 @@ def set_config() -> None:
     # Questions
     provider = questionary.select(
         "Select AI Provider:",
-        choices=["gemini", "openai", "huggingface", "openrouter", "anthropic"],
+        choices=[
+            "gemini",
+            "openai",
+            "huggingface",
+            "openrouter",
+            "anthropic",
+            "ollama",
+        ],
         default=config.get("provider", "gemini"),
         style=style,
     ).ask()
@@ -151,12 +165,24 @@ def set_config() -> None:
         raise typer.Exit(code=130)
     emoji = emoji_choice == "Yes"
 
+    ollama_host = config.get("ollama_host", "http://localhost:11434")
+    if provider == "ollama":
+        ollama_host_input = questionary.text(
+            "Ollama server URL:",
+            default=ollama_host,
+            style=style,
+        ).ask()
+        if ollama_host_input is None:
+            raise typer.Exit(code=130)
+        ollama_host = ollama_host_input.strip() or ollama_host
+
     # Save Config
     new_config = {
         "provider": provider,
         "model": model,
         "api_key": api_key,
         "emoji": emoji,
+        "ollama_host": ollama_host,
     }
 
     # Merge with existing config to preserve other keys?

{devgen_cli-0.2.4 → devgen_cli-0.2.6}/devgen/cli/main.py

@@ -48,13 +48,21 @@ def _version_callback(value: bool) -> None:
                 typer.echo(f"devgen version: {version}")
             else:
                 typer.secho(
-                    "Error: Version not found in pyproject.toml",
+                    "Could not determine version: no `project.version` or "
+                    "`tool.poetry.version` found in pyproject.toml.",
                     fg=typer.colors.RED,
                     err=True,
                 )
-        except (FileNotFoundError, KeyError, Exception) as e:
+        except FileNotFoundError:
             typer.secho(
-                f"Error: Could not determine version: {e}",
+                f"pyproject.toml not found at {pyproject_path}. "
+                "The installation may be corrupt.",
+                fg=typer.colors.RED,
+                err=True,
+            )
+        except toml.TomlDecodeError as e:
+            typer.secho(
+                f"pyproject.toml is not valid TOML: {e}",
                 fg=typer.colors.RED,
                 err=True,
             )

{devgen_cli-0.2.4 → devgen_cli-0.2.6}/devgen/cli/setup.py

@@ -33,7 +33,14 @@ def setup_config() -> None:
     # Questions
     provider = questionary.select(
         "Select AI Provider:",
-        choices=["gemini", "openai", "huggingface", "openrouter", "anthropic"],
+        choices=[
+            "gemini",
+            "openai",
+            "huggingface",
+            "openrouter",
+            "anthropic",
+            "ollama",
+        ],
         default=current_config.get("provider", "gemini"),
         style=style,
     ).ask()
@@ -67,12 +74,24 @@ def setup_config() -> None:
         raise typer.Exit(code=130)
     emoji = emoji_choice == "Yes"
 
+    ollama_host = current_config.get("ollama_host", "http://localhost:11434")
+    if provider == "ollama":
+        ollama_host_input = questionary.text(
+            "Ollama server URL:",
+            default=ollama_host,
+            style=style,
+        ).ask()
+        if ollama_host_input is None:
+            raise typer.Exit(code=130)
+        ollama_host = ollama_host_input.strip() or ollama_host
+
     # Save Config
     new_config = {
         "provider": provider,
         "model": model,
         "api_key": api_key,
         "emoji": emoji,
+        "ollama_host": ollama_host,
     }
 
     try:

devgen_cli-0.2.6/devgen/modules/changelog_generator.py

@@ -0,0 +1,155 @@
+import re
+import subprocess
+from collections import defaultdict
+from datetime import datetime
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from devgen.modules.changelog_sections import (
+    DEFAULT_STYLES,
+    Section,
+    section_for_type,
+)
+from devgen.utils import configure_logger, run_git_command
+
+
+class ChangelogGenerator:
+    """Generates a changelog from git history using Semantic Release style."""
+
+    #: Conventional commit header: ``type(scope)!: subject``
+    _CC_PATTERN = re.compile(r"^(\w+)(?:\(([^)]+)\))?(!?):\s+(.*)")
+
+    def __init__(self, logger=None):
+        self.logger = logger or configure_logger("devgen.changelog")
+
+    # ------------------------------------------------------------------ commits
+
+    def get_commits(self, from_ref: str = "", to_ref: str = "HEAD") -> List[str]:
+        """Fetch commit lines in the requested range."""
+        if from_ref:
+            range_spec = f"{from_ref}..{to_ref}"
+            cmd = self._log_cmd(range_spec)
+        else:
+            cmd = self._resolve_range(to_ref)
+        try:
+            return run_git_command(cmd).split("\n")
+        except subprocess.CalledProcessError as e:
+            self.logger.error(f"Git command failed: {e}")
+            raise RuntimeError(f"Git command failed: {e}") from e
+
+    def _log_cmd(self, range_spec: str) -> List[str]:
+        # Format: hash|author|date|subject|body
+        return [
+            "git",
+            "log",
+            "--format=%H|%an|%ad|%s|%b",
+            "--date=short",
+            range_spec,
+        ]
+
+    def _resolve_range(self, to_ref: str) -> List[str]:
+        try:
+            last_tag = run_git_command(["git", "describe", "--tags", "--abbrev=0"])
+            self.logger.info(f"Generating changelog from last tag: {last_tag}")
+            return self._log_cmd(f"{last_tag}..HEAD")
+        except (RuntimeError, subprocess.CalledProcessError):
+            self.logger.info("No tags found, generating for all commits.")
+            return ["git", "log", "--format=%H|%an|%ad|%s|%b", "--date=short"]
+
+    # ----------------------------------------------------------------- parsing
+
+    def parse_commits(self, raw_commits: List[str]) -> Dict[Section, List[Dict]]:
+        """Group raw commit lines into :class:`Section` buckets."""
+        groups: Dict[Section, List[Dict]] = defaultdict(list)
+        for line in raw_commits:
+            entry = self._parse_line(line)
+            if entry is None:
+                continue
+            section = section_for_type(entry["type"])
+            entry["section"] = section
+            if entry["breaking"]:
+                groups[Section.BREAKING].append(entry)
+            groups[section].append(entry)
+        return dict(groups)
+
+    def _parse_line(self, line: str) -> Dict | None:
+        if not line.strip():
+            return None
+        parts = line.split("|", 4)
+        if len(parts) < 4:
+            return None
+        commit_hash, author, date, subject = parts[:4]
+        body = parts[4] if len(parts) > 4 else ""
+
+        match = self._CC_PATTERN.match(subject)
+        if match:
+            c_type, c_scope, breaking, c_subject = match.groups()
+            return {
+                "type": c_type,
+                "hash": commit_hash,
+                "author": author,
+                "date": date,
+                "scope": c_scope,
+                "subject": c_subject,
+                "body": body,
+                "breaking": bool(breaking),
+            }
+        return {
+            "type": "",
+            "hash": commit_hash,
+            "author": author,
+            "date": date,
+            "scope": None,
+            "subject": subject,
+            "body": body,
+            "breaking": False,
+        }
+
+    # ------------------------------------------------------------------ output
+
+    def generate_markdown(
+        self,
+        groups: Dict[Section, List[Dict]],
+        version: str = "Unreleased",
+    ) -> str:
+        """Render groups as a markdown changelog block."""
+        date_str = datetime.now().strftime("%Y-%m-%d")
+        out = [f"## {version} ({date_str})\n"]
+        for section in Section.ordered():
+            commits = groups.get(section)
+            if not commits:
+                continue
+            style = DEFAULT_STYLES[section]
+            out.append(f"## {style.emoji} {style.heading}\n")
+            for c in commits:
+                scope = f"**{c['scope']}**: " if c.get("scope") else ""
+                out.append(f"- {scope}{c['subject']} ({c['hash'][:7]})")
+            out.append("")
+        return "\n".join(out)
+
+    def run(self, output_file: Optional[str] = "CHANGELOG.md", from_ref: str = ""):
+        """Fetch → parse → write (or print) the changelog."""
+        raw_commits = self.get_commits(from_ref)
+        if not raw_commits or not raw_commits[0]:
+            self.logger.warning("No commits found.")
+            return
+        groups = self.parse_commits(raw_commits)
+        md_content = self.generate_markdown(groups)
+
+        if not output_file:
+            print(md_content)
+            return
+
+        path = Path(output_file)
+        if path.exists():
+            old = path.read_text(encoding="utf-8")
+            if old.strip().startswith("# CHANGELOG"):
+                header, _, rest = old.partition("\n")
+                new_content = f"{header}\n\n{md_content}\n{rest.lstrip()}"
+            else:
+                new_content = f"# CHANGELOG\n\n{md_content}\n\n{old}"
+        else:
+            new_content = f"# CHANGELOG\n\n{md_content}"
+        path.write_text(new_content, encoding="utf-8")
+        self.logger.info(f"Changelog written to {output_file}")
+        print(f" Changelog updated: {output_file}")