commit-me 0.5.1__py3-none-any.whl

commit_me/ai.py

@@ -0,0 +1,199 @@
+"""Generate commit messages by streaming an opencode session."""
+
+import pathlib
+from collections.abc import Callable
+from typing import Any, TypedDict
+
+from opencode import Opencode
+from opencode._stream_events import (
+    MessagePartDeltaProps,
+    MessagePartUpdatedProps,
+    MessageUpdatedProps,
+    SessionStatusProps,
+    parse_stream_event,
+)
+
+from commit_me.util.constants import PROMPT
+
+type Callback = Callable[[], None]
+type ProgressCallback = Callable[[str], None]
+type EventCallback = Callable[[dict[str, Any]], None]
+
+Handlers = TypedDict(
+    "Handlers",
+    {
+        "message.updated": EventCallback,
+        "message.part.updated": EventCallback,
+        "message.part.delta": EventCallback,
+        "session.status": EventCallback,
+    },
+)
+
+
+def make_handler(callback: EventCallback) -> EventCallback:
+    """Wrap an event callback into a stream event handler.
+
+    Args:
+        callback: Callback invoked with the event properties.
+
+    Returns:
+        A handler suitable for the handlers mapping.
+    """
+
+    def handler(props: dict[str, Any]) -> None:
+        callback(props)
+
+    return handler
+
+
+def generate_commit_message(
+    opencode_binary: str,
+    directory: pathlib.Path,
+    model: str,
+    *,
+    on_start: Callback,
+    on_thinking: Callback,
+    on_progress: ProgressCallback,
+    on_finish: Callback,
+) -> str:
+    """Generate a Conventional Commit message from the staged changes.
+
+    Starts an opencode session in the given directory, streams its response,
+    and assembles the assistant's text parts into a single commit message.
+
+    Args:
+        opencode_binary: Path to the opencode executable.
+        directory: Directory of the Git repository to analyze.
+        on_start: Called before the opencode session starts.
+        on_thinking: Called once when opencode starts thinking.
+        on_progress: Called with each streamed text delta.
+        on_finish: Called once the message has been assembled.
+
+    Returns:
+        The generated commit message.
+    """
+    assistant_message_ids: set[str] = set()
+    part_message_ids: dict[str, str] = {}
+    part_texts: dict[str, str] = {}
+    part_deltas: dict[str, list[str]] = {}
+    part_order: list[str] = []
+
+    thinking_notified = False
+
+    def notify_thinking() -> None:
+        nonlocal thinking_notified
+
+        if not thinking_notified:
+            thinking_notified = True
+            on_thinking()
+
+    def handle_message_updated(props: dict[str, Any]) -> None:
+        event = MessageUpdatedProps.model_construct(**props)
+        info = event.info
+
+        if info.get("role") == "assistant":
+            message_id = info.get("id")
+            if message_id:
+                assistant_message_ids.add(message_id)
+
+            notify_thinking()
+
+    def handle_part_updated(props: dict[str, Any]) -> None:
+        event = MessagePartUpdatedProps.model_construct(**props)
+        part = event.part
+
+        if part.get("type") != "text":
+            return
+
+        part_id = part.get("id")
+        message_id = part.get("messageID")
+
+        if not part_id:
+            return
+
+        if part_id not in part_order:
+            part_order.append(part_id)
+
+        if message_id:
+            part_message_ids[part_id] = message_id
+
+        if "text" in part:
+            part_texts[part_id] = part.get("text", "")
+
+    def handle_part_delta(props: dict[str, Any]) -> None:
+        event = MessagePartDeltaProps.model_construct(**props)
+
+        if event.field != "text" or not event.delta:
+            return
+
+        part_id = event.partID
+        part_deltas.setdefault(part_id, []).append(event.delta)
+
+        on_progress(event.delta)
+
+    def handle_status(props: dict[str, Any]) -> None:
+        event = SessionStatusProps.model_construct(**props)
+        status = event.status.get("type")
+
+        if status == "busy":
+            notify_thinking()
+
+    handlers: Handlers = {
+        "message.updated": make_handler(handle_message_updated),
+        "message.part.updated": make_handler(handle_part_updated),
+        "message.part.delta": make_handler(handle_part_delta),
+        "session.status": make_handler(handle_status),
+    }
+
+    on_start()
+
+    with Opencode(
+        opencode_binary=opencode_binary,
+        directory=str(directory),
+        model=model,
+    ) as oc:
+        session = oc.create_session()
+        response = oc.client.event_subscribe()
+
+        oc.client.session_send(
+            session.id,
+            {"parts": [{"type": "text", "text": PROMPT}]},
+        )
+
+        for line in response.iter_lines():
+            if not line.startswith("data: "):
+                continue
+
+            event = parse_stream_event(line[6:])
+            props = event.properties
+
+            if props.get("sessionID") not in (None, session.id):
+                continue
+
+            handler = handlers.get(event.type)
+            if handler:
+                handler(props)
+
+            if event.type == "session.idle":
+                break
+
+            if event.type == "session.status":
+                status = SessionStatusProps.model_construct(**props)
+                if status.status.get("type") == "idle":
+                    break
+        response.close()
+
+    result_parts: list[str] = []
+
+    for part_id in part_order:
+        if part_message_ids.get(part_id) not in assistant_message_ids:
+            continue
+
+        if part_id in part_texts:
+            result_parts.append(part_texts[part_id])
+        else:
+            result_parts.append("".join(part_deltas.get(part_id, [])))
+
+    on_finish()
+
+    return "".join(result_parts).strip()

commit_me/cli.py

@@ -0,0 +1,58 @@
+"""Command-line entry point for commit-me."""
+
+import pathlib
+
+import rich_click as click
+from rich.console import Console
+
+from commit_me.ai import generate_commit_message
+from commit_me.exceptions import MissingCliError, NoGitRepoError, NoStagedChangesError
+from commit_me.util.command import check_required_clis, create_commit, has_stage_changes
+
+
+@click.command()
+@click.argument(
+    "directory",
+    type=click.Path(exists=True, path_type=pathlib.Path),
+    default=pathlib.Path.cwd(),
+)
+@click.option("-p", "--preview", is_flag=True)
+@click.option("-m", "--model", default="opencode/big-pickle")
+def commit_me_cli(directory: pathlib.Path, preview: bool, model: str) -> None:
+    """Generate a Conventional Commit message with opencode and commit it.
+
+    Args:
+        directory: Existing directory of the Git repository to commit in.
+        preview: Whether to preview the commit message before committing.
+    """
+    try:
+        clis = check_required_clis()
+
+        contains_stage = has_stage_changes(directory)
+
+        if not contains_stage:
+            raise NoStagedChangesError(directory=directory)
+
+        console = Console()
+        with console.status("Calling opencode") as status:
+            commit_message = generate_commit_message(
+                opencode_binary=clis["opencode"]["path"],
+                directory=directory,
+                model=model,
+                on_start=lambda: status.update("Starting opencode"),
+                on_thinking=lambda: status.update("Opencode is thinking..."),
+                on_progress=lambda _e: None,
+                on_finish=lambda: status.update("Done"),
+            )
+
+        create_commit(
+            message=commit_message,
+            directory=directory,
+            preview=preview,
+        )
+    except (MissingCliError, NoGitRepoError, NoStagedChangesError) as exception:
+        click.echo(exception, err=True)
+
+
+if __name__ == "__main__":
+    commit_me_cli()

commit_me/exceptions.py

@@ -0,0 +1,56 @@
+"""Exceptions raised by the commit-me package."""
+
+import pathlib
+
+
+class MissingCliError(Exception):
+    """Raised when one or more required CLIs are missing or not on the PATH."""
+
+    MESSAGE_TEMPLATE: str = (
+        "Required CLI(s) not found on PATH: {cli_names}."
+        " Install them and make sure they are available in your shell."
+    )
+    cli_names: list[str]
+
+    def __init__(self, *, cli_names: list[str]) -> None:
+        """Initialize the error with the names of the missing CLIs.
+
+        Args:
+            cli_names: Names of the CLIs that are missing.
+        """
+        self.cli_names = cli_names
+        super().__init__(self.MESSAGE_TEMPLATE.format(cli_names=", ".join(cli_names)))
+
+
+class NoGitRepoError(Exception):
+    """Raised when the target directory is not inside a Git repository."""
+
+    MESSAGE = (
+        "No Git repository found in: {directory}."
+        " Run inside a repository or pass a path to one."
+    )
+
+    def __init__(self, *, directory: pathlib.Path) -> None:
+        """Initialize the error with the directory that is not a repository.
+
+        Args:
+            directory: Directory that was checked for a Git repository.
+        """
+        super().__init__(self.MESSAGE.format(directory=str(directory.absolute())))
+
+
+class NoStagedChangesError(Exception):
+    """Raised when the repository has no staged changes to commit."""
+
+    MESSAGE = (
+        "No staged changes found in: {directory}."
+        " Stage your changes first with `git add`."
+    )
+
+    def __init__(self, *, directory: pathlib.Path) -> None:
+        """Initialize the error with the directory that has no staged changes.
+
+        Args:
+            directory: Directory of the repository that was checked.
+        """
+        super().__init__(self.MESSAGE.format(directory=str(directory.absolute())))

commit_me/util/command.py

@@ -0,0 +1,99 @@
+"""Utilities for detecting required command-line tools."""
+
+import pathlib
+import shutil
+import subprocess
+from typing import Never, TypedDict
+
+import rich_click as click
+
+from commit_me.exceptions import MissingCliError, NoGitRepoError
+
+
+class Cli(TypedDict):
+    """Metadata for a command-line tool that must be available."""
+
+    name: str
+    cmd: str
+
+
+REQUIRED_CLIS: list[Cli] = [
+    {"name": "Git", "cmd": "git"},
+    {"name": "Opencode", "cmd": "opencode"},
+]
+
+
+def is_cli_installed(cli_info: Cli) -> bool:
+    """Return whether the given CLI is present on the PATH.
+
+    Args:
+        cli_info: Metadata of the CLI to look up.
+
+    Returns:
+        True if the CLI command was found on the PATH.
+    """
+    return bool(shutil.which(cli_info["cmd"]))
+
+
+def check_required_clis() -> dict[str, dict] | Never:
+    """Raise MissingCliError if any required CLI is not installed."""
+    missing_clis = [cli["name"] for cli in REQUIRED_CLIS if not is_cli_installed(cli)]
+    if missing_clis:
+        raise MissingCliError(cli_names=missing_clis)
+
+    return {cli["cmd"]: {"path": shutil.which(cli["cmd"])} for cli in REQUIRED_CLIS}
+
+
+def create_commit(
+    *,
+    message: str,
+    directory: pathlib.Path,
+    preview: bool,
+) -> None:
+    """Create a Git commit with the given message, optionally after a preview.
+
+    Args:
+        message: Commit message to use.
+        directory: Directory of the Git repository to commit in.
+        preview: Whether to show the message and ask for confirmation first.
+    """
+
+    def git_commit() -> None:
+        """Run `git commit` with the message in the target directory."""
+        subprocess.run(
+            args=["git", "commit", "-m", f"{message}"],
+            cwd=str(directory),
+            check=True,
+        )
+
+    if preview:
+        click.echo(f"Proposed commit message:\n\n{message}")
+        if click.confirm("Create this commit?"):
+            git_commit()
+    else:
+        git_commit()
+
+
+def has_stage_changes(directory: pathlib.Path) -> bool | Never:
+    """Return whether the repository has staged changes.
+
+    Args:
+        directory: Directory of the Git repository to check.
+
+    Returns:
+        True if there are staged changes.
+
+    Raises:
+        NoGitRepoError: If the directory is not inside a Git repository.
+    """
+    result = subprocess.run(
+        ["git", "diff", "--cached", "--quiet"],
+        text=True,
+        capture_output=True,
+        cwd=str(directory),
+    )
+    if result.returncode == 0:
+        return False
+    if result.returncode == 1:
+        return True
+    raise NoGitRepoError(directory=directory)

commit_me/util/constants.py

@@ -0,0 +1,48 @@
+"""Prompt used to ask opencode for a Conventional Commit message."""
+
+from typing import Final
+
+PROMPT: Final[str] = """
+Conventional Commit Generator
+
+Act as an experienced software engineer. Analyze the available code changes, diffs,
+staged changes, or modified files and generate one accurate, concise commit message
+following Conventional Commits 1.0.0.
+Rules
+
+    Determine the primary purpose and use the appropriate type: feat, fix, refactor,
+    perf, docs, test, style, build, ci, or chore.
+    Add an optional scope when relevant.
+    Write the description in English, using imperative mood, lowercase where
+    appropriate, and a specific summary.
+    Use ! and/or a BREAKING CHANGE: footer only when a breaking change is supported by
+    evidence.
+    Include a body or footer only when essential and supported by the changes.
+    Never invent functionality, intent, issue references, or metadata.
+    If changes are unavailable or insufficient, output only a concise request for the
+    missing diff or code.
+    Do not execute Git commands that create, amend, or apply commits. Do not modify
+    files or the repository.
+
+Strict Output Requirements
+
+    Output only the final commit message or the minimal request for missing changes.
+    Never output analysis, reasoning, status updates, progress messages,
+    acknowledgments, introductions, explanations, or statements about inspecting the
+    repository.
+    Never describe what you are doing or what you need to do before producing the
+    result.
+    Never include phrases such as "I need to inspect the current changes in the repo to
+    generate the appropriate Conventional Commit message."
+    Do not include multiple alternatives, Markdown code fences, or surrounding quotation
+    marks.
+    Do not generate a commit; suggest the message only.
+
+Format
+
+<type>[optional scope][optional !]: <description>
+
+Optionally add a meaningful body and/or justified footer.
+
+Return the commit message directly, with no preceding or trailing text.
+"""

commit_me-0.5.1.dist-info/METADATA

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: commit-me
+Version: 0.5.1
+Summary: Generate Conventional Commit messages for your staged changes with opencode and commit them in one step.
+Author-email: Gamaliel Garcia <46827955+EGAMAGZ@users.noreply.github.com>
+Maintainer-email: Gamaliel Garcia <46827955+EGAMAGZ@users.noreply.github.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/EGAMAGZ/commit-me
+Project-URL: Repository, https://github.com/EGAMAGZ/commit-me
+Keywords: ai,cli,commit,commit-message,conventional-commits,git,llm,opencode
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.5.0
+Requires-Dist: opencode-py>=0.8.0
+Requires-Dist: rich>=15.0.0
+Requires-Dist: rich-click>=1.9.9
+Dynamic: license-file
+
+# commit-me
+
+[![PyPI version](https://img.shields.io/pypi/v/commit-me.svg)](https://pypi.org/project/commit-me/)
+[![PyPI - Python versions](https://img.shields.io/pypi/pyversions/commit-me.svg)](https://pypi.org/project/commit-me/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/commit-me.svg)](https://pypi.org/project/commit-me/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![CI](https://github.com/EGAMAGZ/commit-me/actions/workflows/ci.yml/badge.svg)](https://github.com/EGAMAGZ/commit-me/actions/workflows/ci.yml)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+Generate [Conventional Commit](https://www.conventionalcommits.org/en/v1.0.0/) messages for your staged changes with [opencode](https://opencode.ai) and commit them in one step.
+
+`commit-me` inspects the staged diff of a Git repository, asks an opencode session for a single accurate commit message, and creates the commit. It never invents metadata and will not modify files or history.
+
+## Requirements
+
+- Python 3.12+
+- [Git](https://git-scm.com/) on your `PATH`
+- [opencode](https://opencode.ai) on your `PATH`
+
+## Install
+
+With [uv](https://docs.astral.sh/uv/):
+
+```sh
+uv tool install commit-me
+```
+
+With [pipx](https://pipx.pypa.io/):
+
+```sh
+pipx install commit-me
+```
+
+With pip:
+
+```sh
+pip install commit-me
+```
+
+## Usage
+
+Stage your changes, then run:
+
+```sh
+python -m commit_me.cli
+```
+
+Options:
+
+| Option | Description |
+| --- | --- |
+| `-p`, `--preview` | Show the proposed message and ask for confirmation before committing. |
+| `-m`, `--model` | opencode model to use (default: `opencode/big-pickle`). |
+| `DIRECTORY` | Path to the Git repository (default: current directory). |
+
+Preview a message without committing:
+
+```sh
+python -m commit_me.cli --preview
+```
+
+## Development
+
+```sh
+uv sync --group dev
+uv run ty check
+uv run ruff check .
+uv run ruff format --check .
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

commit_me-0.5.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+commit_me/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+commit_me/ai.py,sha256=wep8Prcxs1JHyoBNsXFaN1UjYKXxj4nh3hhgzxnVmxo,5589
+commit_me/cli.py,sha256=QeQ8MW9fDLazl36yRnGPHgNF-Kr1h7WTAeCH-FNfUwA,1948
+commit_me/exceptions.py,sha256=dxOlrjn5BxzpEFD9KKrjOetdGm8SFthRLU-bWYC_BUI,1826
+commit_me/util/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+commit_me/util/command.py,sha256=zNGY9niPQgdm7aB1IUPn8j1uqqDYT-BLcB0ZBEaT2FQ,2606
+commit_me/util/constants.py,sha256=VXOnXSdwt3K-7QUL1V0AGv55r51rg4MauUpbvbPbvoE,2015
+commit_me-0.5.1.dist-info/licenses/LICENSE,sha256=ujS4dTZtnoe3nwvkve8kF0dVU3jXpOWvYJH29DNC5j0,1072
+commit_me-0.5.1.dist-info/METADATA,sha256=DOnwgYrUqLK4PbWadMLN5K5CekJSD0VY-Clo4VL8_n4,3260
+commit_me-0.5.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+commit_me-0.5.1.dist-info/entry_points.txt,sha256=I2iTJdgwEchvxmhZEJCPNFQ9EQNfCtTxd4OZ3_wEsaQ,58
+commit_me-0.5.1.dist-info/top_level.txt,sha256=Mgq7LmSrDzwZO9dFBRNZ9Te6qVnS9Hkl7PZSh4cSlj4,10
+commit_me-0.5.1.dist-info/RECORD,,

commit_me-0.5.1.dist-info/WHEEL

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

commit_me-0.5.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+commit-me = commit_me.cli:commit_me_cli

commit_me-0.5.1.dist-info/licenses/LICENSE

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

commit_me-0.5.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+commit_me