commitar 1.0.0__py3-none-any.whl

commitar/__init__.py

@@ -0,0 +1,3 @@
+"""CLI Commitar."""
+
+__version__ = "0.1.0"

commitar/ai.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+import json
+import os
+import re
+from math import ceil
+from urllib.error import URLError
+from urllib.request import Request, urlopen
+
+from .config import Settings
+from .errors import AIProviderError, AITimeoutError, CommitarError, InvalidAIMessageError
+
+CONVENTIONAL = re.compile(
+    r"^(?:build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(?:\([^)\r\n]+\))?!?: .+\S$"
+)
+
+
+def prompt(diff: str, language: str) -> str:
+    return (
+        "Generate only one valid Conventional Commit message, without quotation marks, "
+        f"in {language}. Use one line in the type(optional scope): description format.\n\nDIFF:\n{diff}"
+    )
+
+
+def estimate_tokens(text: str) -> int:
+    """Conservatively estimate tokens without depending on a provider tokenizer."""
+    return ceil(len(text.encode("utf-8")) / 3)
+
+
+def _validate_input(body: str, settings: Settings) -> None:
+    estimated_tokens = estimate_tokens(body)
+    if estimated_tokens > settings.max_input_tokens:
+        raise CommitarError(
+            "AI input exceeds max_input_tokens "
+            f"({estimated_tokens} estimated tokens > {settings.max_input_tokens}). "
+            "Increase the limit or narrow the scope."
+        )
+    if estimated_tokens + settings.max_output_tokens > settings.context_window_tokens:
+        raise CommitarError(
+            "AI input and reserved output exceed context_window_tokens "
+            f"({estimated_tokens} + {settings.max_output_tokens} > "
+            f"{settings.context_window_tokens}). Increase the context window or narrow the scope."
+        )
+
+
+def _post(url: str, payload: dict, headers: dict[str, str], timeout_seconds: int) -> dict:
+    request = Request(url, data=json.dumps(payload).encode(), headers=headers, method="POST")
+    try:
+        with urlopen(request, timeout=timeout_seconds) as response:  # nosec B310 - configured endpoint
+            return json.loads(response.read())
+    except TimeoutError as exc:
+        raise AITimeoutError(f"Unable to contact the AI provider: {exc}") from exc
+    except URLError as exc:
+        if isinstance(exc.reason, TimeoutError):
+            raise AITimeoutError(f"Unable to contact the AI provider: {exc.reason}") from exc
+        raise AIProviderError(f"Unable to contact the AI provider: {exc}") from exc
+    except json.JSONDecodeError as exc:
+        raise AIProviderError(f"Unable to contact the AI provider: {exc}") from exc
+
+
+def generate(diff: str, settings: Settings) -> str:
+    body = prompt(diff, settings.language)
+    _validate_input(body, settings)
+    if settings.provider == "openai":
+        key = os.getenv("OPENAI_API_KEY")
+        if not key:
+            raise CommitarError("OPENAI_API_KEY is not configured.")
+        data = _post(
+            settings.endpoint or "https://api.openai.com/v1/chat/completions",
+            {
+                "model": settings.model,
+                "messages": [{"role": "user", "content": body}],
+                "max_tokens": settings.max_output_tokens,
+                "temperature": settings.temperature,
+            },
+            {"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
+            settings.timeout_seconds,
+        )
+        answer = data["choices"][0]["message"]["content"]
+    elif settings.provider == "gemini":
+        key = os.getenv("GEMINI_API_KEY")
+        if not key:
+            raise CommitarError("GEMINI_API_KEY is not configured.")
+        url = (
+            settings.endpoint
+            or f"https://generativelanguage.googleapis.com/v1beta/models/{settings.model}:generateContent?key={key}"
+        )
+        data = _post(
+            url,
+            {
+                "contents": [{"parts": [{"text": body}]}],
+                "generationConfig": {
+                    "maxOutputTokens": settings.max_output_tokens,
+                    "temperature": settings.temperature,
+                },
+            },
+            {"Content-Type": "application/json"},
+            settings.timeout_seconds,
+        )
+        answer = data["candidates"][0]["content"]["parts"][0]["text"]
+    else:
+        data = _post(
+            settings.endpoint or "http://localhost:11434/api/generate",
+            {
+                "model": settings.model,
+                "prompt": body,
+                "stream": False,
+                "options": {
+                    "temperature": settings.temperature,
+                    "num_ctx": settings.context_window_tokens,
+                    "num_predict": settings.max_output_tokens,
+                },
+            },
+            {"Content-Type": "application/json"},
+            settings.timeout_seconds,
+        )
+        answer = data["response"]
+    answer = answer.strip()
+    if not CONVENTIONAL.fullmatch(answer):
+        raise InvalidAIMessageError(
+            "The AI returned an invalid commit message; this commit was skipped."
+        )
+    return answer
+
+
+def message_for(diff: str, settings: Settings, supplied: str | None) -> str:
+    if supplied:
+        if not CONVENTIONAL.fullmatch(supplied):
+            raise CommitarError("`--message` must be a single-line Conventional Commit message.")
+        return supplied
+    encoded = diff.encode()
+    if (
+        len(encoded) <= settings.max_diff_bytes
+        and estimate_tokens(prompt(diff, settings.language)) <= settings.max_input_tokens
+    ):
+        return generate(diff, settings)
+    # Deterministic summary; oversized input is never silently truncated.
+    summary = "\n".join(
+        line for line in diff.splitlines() if line.startswith(("diff --git", "--- ", "+++ ", "@@"))
+    )
+    context = "Deterministic summary due to the diff limit:\n" + summary
+    context_bytes = len(context.encode())
+    context_tokens = estimate_tokens(prompt(context, settings.language))
+    if context_bytes > settings.max_diff_bytes or context_tokens > settings.max_input_tokens:
+        raise CommitarError(
+            "The deterministic diff summary still exceeds the configured AI input limits "
+            f"({context_bytes} bytes, {context_tokens} estimated tokens). "
+            "Increase max_diff_bytes/max_input_tokens or narrow the scope."
+        )
+    return generate(context, settings)

commitar/cli.py

@@ -0,0 +1,302 @@
+from __future__ import annotations
+
+import json
+import sys
+from contextlib import contextmanager
+from dataclasses import replace
+from pathlib import Path
+from threading import Event, Thread
+from time import perf_counter, sleep
+from typing import Optional
+
+import typer
+
+from .ai import message_for
+from .config import TEMPLATE, load
+from .errors import AIProviderError, AITimeoutError, CommitarError, InvalidAIMessageError
+from .git import GitRepo
+from .scope import Group, resolve
+
+app = typer.Typer(add_completion=False, no_args_is_help=False)
+config_app = typer.Typer(
+    help="Create and inspect Commitar configuration files.",
+    no_args_is_help=True,
+)
+MAX_AI_ATTEMPTS = 3
+
+
+@contextmanager
+def _loading(message: str):
+    """Show a spinner only when the CLI is attached to an interactive terminal."""
+    typer.echo(err=True)
+    if not sys.stderr.isatty():
+        typer.secho(message, fg=typer.colors.CYAN, err=True)
+        yield
+        return
+
+    stop = Event()
+
+    def spin() -> None:
+        for frame in "|/-\\":
+            if stop.is_set():
+                break
+            typer.secho(
+                f"\r{message} {frame}",
+                fg=typer.colors.CYAN,
+                nl=False,
+                err=True,
+            )
+            sleep(0.12)
+
+    def loop() -> None:
+        while not stop.is_set():
+            spin()
+
+    worker = Thread(target=loop, daemon=True)
+    worker.start()
+    try:
+        yield
+    finally:
+        stop.set()
+        worker.join(timeout=1)
+        typer.echo("\r" + " " * (len(message) + 2) + "\r", nl=False, err=True)
+
+
+def _show(
+    group: Group,
+    message: str,
+    position: int,
+    total: int,
+    generation_seconds: float | None,
+) -> None:
+    """Render a compact, readable preview for one commit group."""
+    typer.echo()
+    typer.secho(f"Commit preview {position}/{total}", fg=typer.colors.CYAN, bold=True)
+    typer.secho("─" * 52, fg=typer.colors.BRIGHT_BLACK)
+    typer.echo(f"Source: {group.source}")
+    typer.echo(f"Files ({len(group.files)}):")
+    for file in group.files:
+        typer.secho(f"  • {file}", fg=typer.colors.WHITE)
+    typer.echo("Message:")
+    typer.secho(f"  {message}", fg=typer.colors.GREEN, bold=True)
+    if generation_seconds is not None:
+        typer.secho(f"Generated in {generation_seconds:.2f}s", fg=typer.colors.BRIGHT_BLACK)
+
+
+def _show_skipped(group: Group, position: int, total: int, reason: str) -> None:
+    """Render a recoverable generation failure without stopping later groups."""
+    typer.echo()
+    typer.secho(f"Skipped commit {position}/{total}", fg=typer.colors.YELLOW, bold=True)
+    typer.secho("─" * 52, fg=typer.colors.BRIGHT_BLACK)
+    typer.echo(f"Reason: {reason}")
+    typer.echo(f"Files ({len(group.files)}):")
+    for file in group.files:
+        typer.echo(f"  • {file}")
+
+
+@app.command()
+def commitar(
+    path: Optional[Path] = typer.Argument(
+        None,
+        metavar="[PATH]",
+        help="A file or directory inside the repository. Without PATH, creates one group per modified file.",
+    ),
+    output: Optional[str] = typer.Option(
+        None, "--output", help="Operation mode: preview (no changes) or commit (creates commits)."
+    ),
+    dry_run: bool = typer.Option(
+        False, "--dry-run", help="Alias for --output preview; never changes the repository."
+    ),
+    yes: bool = typer.Option(
+        False, "--yes", "-y", help="Skip the confirmation prompt in commit mode."
+    ),
+    message: Optional[str] = typer.Option(
+        None, "--message", help="Use this Conventional Commit message instead of calling the AI."
+    ),
+    include_added: Optional[bool] = typer.Option(
+        None,
+        "--include-added/--no-include-added",
+        help="Include untracked files. Disabled by default.",
+    ),
+    provider: Optional[str] = typer.Option(
+        None, "--provider", help="AI provider: openai, gemini, or ollama."
+    ),
+    model: Optional[str] = typer.Option(
+        None, "--model", help="Model name for the selected AI provider."
+    ),
+    timeout_seconds: Optional[int] = typer.Option(
+        None, "--timeout-seconds", min=1, help="AI request timeout in seconds; defaults to 60."
+    ),
+    max_input_tokens: Optional[int] = typer.Option(
+        None,
+        "--max-input-tokens",
+        min=1,
+        help="Maximum estimated tokens sent to the AI, including prompt instructions.",
+    ),
+    context_window_tokens: Optional[int] = typer.Option(
+        None,
+        "--context-window-tokens",
+        min=1,
+        help="Model context window shared by input and reserved output tokens.",
+    ),
+    config: Optional[Path] = typer.Option(
+        None,
+        "--config",
+        help="Path to a TOML file that overrides repository and user configuration.",
+    ),
+) -> None:
+    """Suggest or create Conventional Commits while keeping staging isolated.
+
+    When staging already contains changes, run without PATH: Commitar uses only the
+    index and creates one commit. A PATH together with staged changes fails safely.
+    Without staging, PATH groups a file or directory into one commit; no PATH creates
+    one group per modified file. Use `commitar config --help` for configuration commands.
+    """
+    try:
+        repo = GitRepo()
+        settings = load(
+            repo.root,
+            config,
+            output="preview" if dry_run else output,
+            include_added=include_added,
+            provider=provider,
+            model=model,
+            timeout_seconds=timeout_seconds,
+            max_input_tokens=max_input_tokens,
+            context_window_tokens=context_window_tokens,
+        )
+        scope = resolve(repo, path, settings.include_added)
+        if any(len(group.files) > settings.max_files_per_request for group in scope.groups):
+            raise CommitarError(
+                "The scope exceeds max_files_per_request; narrow the path or increase the limit."
+            )
+        completed: list[str] = []
+        skipped: list[list[str]] = []
+        total_groups = len(scope.groups)
+        for position, group in enumerate(scope.groups, start=1):
+            diff = repo.staged_diff() if scope.staged else repo.working_diff(group.files)
+            generation_seconds: float | None = None
+            files_in_progress = ", ".join(group.files)
+            try:
+                if message:
+                    final_message = message_for(diff, settings, message)
+                else:
+                    started_at = perf_counter()
+                    model_candidates = settings.model_candidates
+                    for attempt in range(1, MAX_AI_ATTEMPTS + 1):
+                        model = model_candidates[min(attempt - 1, len(model_candidates) - 1)]
+                        attempt_settings = replace(settings, model=model, models=())
+                        try:
+                            with _loading(
+                                "Generating commit message for "
+                                f"[{files_in_progress}] with model [{model}]... "
+                                f"({attempt}/{MAX_AI_ATTEMPTS})"
+                            ):
+                                final_message = message_for(diff, attempt_settings, None)
+                            break
+                        except (InvalidAIMessageError, AITimeoutError) as exc:
+                            if attempt == MAX_AI_ATTEMPTS:
+                                raise
+                            next_model = model_candidates[min(attempt, len(model_candidates) - 1)]
+                            reason = (
+                                "AI request timed out"
+                                if isinstance(exc, AITimeoutError)
+                                else "Invalid AI message"
+                            )
+                            typer.secho(
+                                f"{reason} with model [{model}]. "
+                                f"Retrying with model [{next_model}] "
+                                f"({attempt + 1}/{MAX_AI_ATTEMPTS})...",
+                                fg=typer.colors.YELLOW,
+                            )
+                    generation_seconds = perf_counter() - started_at
+            except InvalidAIMessageError as exc:
+                skipped.append(group.files)
+                _show_skipped(group, position, total_groups, str(exc))
+                continue
+            except AIProviderError as exc:
+                raise AIProviderError(f"{exc}. Files in progress: [{files_in_progress}].") from exc
+            _show(group, final_message, position, total_groups, generation_seconds)
+            if settings.output == "preview":
+                continue
+            if not yes and settings.confirm:
+                if not sys.stdin.isatty():
+                    raise CommitarError(
+                        "Confirmation requires an interactive terminal; use --yes for automation."
+                    )
+                if not typer.confirm("Create commit?", default=False):
+                    typer.secho("Cancelled.", fg=typer.colors.YELLOW)
+                    return
+            if not scope.staged and repo.staged_files():
+                raise CommitarError(
+                    "The index changed during the operation; no new commit was created."
+                )
+            if scope.staged:
+                completed.append(repo.commit(final_message))
+            else:
+                repo.add(group.files)
+                try:
+                    completed.append(repo.commit(final_message))
+                except CommitarError:
+                    repo.unstage(group.files)
+                    raise
+        if completed:
+            typer.echo()
+            typer.secho("Commit completed", fg=typer.colors.GREEN, bold=True)
+            typer.secho("─" * 52, fg=typer.colors.BRIGHT_BLACK)
+            typer.echo("Created commits: " + ", ".join(completed))
+        if skipped:
+            typer.echo()
+            typer.secho(
+                f"Skipped commits: {len(skipped)}",
+                fg=typer.colors.YELLOW,
+                bold=True,
+            )
+    except CommitarError as exc:
+        _print_error(str(exc))
+        raise typer.Exit(code=1) from exc
+
+
+def _print_error(message: str) -> None:
+    typer.secho(f"Error: {message}", fg=typer.colors.RED, bold=True, err=True)
+
+
+@config_app.command("init")
+def config_init(
+    path: Path = typer.Option(
+        Path(".commitar.toml"), "--path", help="Destination for the configuration template."
+    ),
+) -> None:
+    """Create a configuration template."""
+    if path.exists():
+        typer.secho(f"Error: {path} already exists.", fg=typer.colors.RED, bold=True, err=True)
+        raise typer.Exit(1)
+    path.write_text(TEMPLATE, encoding="utf-8")
+    typer.secho(f"Configuration created at {path}.", fg=typer.colors.GREEN, bold=True)
+
+
+@config_app.command("show")
+def config_show(
+    config: Optional[Path] = typer.Option(
+        None, "--config", help="An additional TOML configuration file to apply."
+    ),
+) -> None:
+    """Print the effective configuration without credentials."""
+    try:
+        repo = GitRepo()
+        typer.echo(json.dumps(load(repo.root, config).__dict__, ensure_ascii=False, indent=2))
+    except CommitarError as exc:
+        typer.secho(f"Error: {exc}", fg=typer.colors.RED, bold=True, err=True)
+        raise typer.Exit(1) from exc
+
+
+def main() -> None:
+    """Dispatch config without making PATH ambiguous for Click."""
+    if len(sys.argv) > 1 and sys.argv[1] == "config":
+        config_app(args=sys.argv[2:], prog_name="commitar config")
+    else:
+        app()
+
+
+if __name__ == "__main__":
+    main()

commitar/config.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+
+from .errors import CommitarError
+
+
+@dataclass(frozen=True)
+class Settings:
+    provider: str = "openai"
+    model: str = "gpt-5-mini"
+    models: tuple[str, ...] = ()
+    max_input_tokens: int = 12000
+    context_window_tokens: int = 32768
+    max_output_tokens: int = 80
+    temperature: float = 0.2
+    timeout_seconds: int = 60
+    endpoint: str | None = None
+    language: str = "pt-BR"
+    format: str = "conventional"
+    include_added: bool = False
+    output: str = "preview"
+    confirm: bool = True
+    max_files_per_request: int = 50
+    max_diff_bytes: int = 100000
+
+    @property
+    def model_candidates(self) -> tuple[str, ...]:
+        """Return models in preference order, preserving legacy single-model config."""
+        return self.models or (self.model,)
+
+
+TEMPLATE = """[ai]
+provider = "ollama"
+models = ["gemma4:e4b", "qwen2.5-coder:14b"]
+endpoint = "http://localhost:11434/api/generate"
+max_input_tokens = 12000
+context_window_tokens = 32768
+max_output_tokens = 80
+temperature = 0.2
+timeout_seconds = 60
+
+[commit]
+language = "pt-BR"
+format = "conventional"
+include_added = true
+output = "commit"
+confirm = true
+
+[limits]
+max_files_per_request = 50
+max_diff_bytes = 100000
+"""
+
+
+def _read(path: Path) -> dict[str, Any]:
+    if not path.is_file():
+        return {}
+    try:
+        with path.open("rb") as file:
+            raw = tomllib.load(file)
+    except tomllib.TOMLDecodeError as exc:
+        raise CommitarError(f"Invalid TOML configuration in {path}: {exc}") from exc
+    return {**raw.get("ai", {}), **raw.get("commit", {}), **raw.get("limits", {})}
+
+
+def _env() -> dict[str, Any]:
+    mapping = {
+        "COMMITAR_PROVIDER": "provider",
+        "COMMITAR_MODEL": "model",
+        "COMMITAR_LANGUAGE": "language",
+        "COMMITAR_OUTPUT": "output",
+        "COMMITAR_ENDPOINT": "endpoint",
+        "COMMITAR_MAX_INPUT_TOKENS": "max_input_tokens",
+        "COMMITAR_CONTEXT_WINDOW_TOKENS": "context_window_tokens",
+        "COMMITAR_MAX_DIFF_BYTES": "max_diff_bytes",
+        "COMMITAR_TIMEOUT_SECONDS": "timeout_seconds",
+    }
+    return {key: os.environ[name] for name, key in mapping.items() if name in os.environ}
+
+
+def load(repo_root: Path, config_path: Path | None = None, **overrides: Any) -> Settings:
+    values: dict[str, Any] = asdict(Settings())
+
+    def apply_layer(layer: dict[str, Any]) -> None:
+        if "model" in layer and "models" not in layer:
+            values["models"] = ()
+        values.update(layer)
+
+    apply_layer(_read(Path.home() / ".config/commitar/config.toml"))
+    apply_layer(_read(repo_root / ".commitar.toml"))
+    apply_layer(_env())
+    if config_path:
+        apply_layer(_read(config_path))
+    apply_layer({key: value for key, value in overrides.items() if value is not None})
+
+    configured_models = values["models"]
+    if not isinstance(configured_models, (list, tuple)) or any(
+        not isinstance(candidate, str) or not candidate.strip() for candidate in configured_models
+    ):
+        raise CommitarError("`models` must be a list of non-empty model names.")
+    if len(configured_models) > 3:
+        raise CommitarError("`models` accepts at most three models, matching the retry limit.")
+    values["models"] = tuple(configured_models)
+    for key in (
+        "max_input_tokens",
+        "context_window_tokens",
+        "max_output_tokens",
+        "max_files_per_request",
+        "max_diff_bytes",
+        "timeout_seconds",
+    ):
+        if isinstance(values[key], str):
+            values[key] = int(values[key])
+    if isinstance(values["temperature"], str):
+        values["temperature"] = float(values["temperature"])
+    if values["output"] not in {"preview", "commit"}:
+        raise CommitarError("`output` must be `preview` or `commit`.")
+    if values["provider"] not in {"openai", "gemini", "ollama"}:
+        raise CommitarError("Provider must be openai, gemini, or ollama.")
+    if any(
+        values[key] <= 0
+        for key in (
+            "max_input_tokens",
+            "context_window_tokens",
+            "max_output_tokens",
+            "max_files_per_request",
+            "max_diff_bytes",
+            "timeout_seconds",
+        )
+    ):
+        raise CommitarError("Numeric limits and timeout_seconds must be positive.")
+    if values["max_input_tokens"] + values["max_output_tokens"] > values["context_window_tokens"]:
+        raise CommitarError(
+            "`max_input_tokens` + `max_output_tokens` must not exceed `context_window_tokens`."
+        )
+    return Settings(**values)

commitar/errors.py

@@ -0,0 +1,14 @@
+class CommitarError(Exception):
+    """Erro esperado, exibido ao usuário sem traceback."""
+
+
+class InvalidAIMessageError(CommitarError):
+    """The provider returned text that cannot be used as a commit message."""
+
+
+class AIProviderError(CommitarError):
+    """The CLI could not communicate with the configured AI provider."""
+
+
+class AITimeoutError(AIProviderError):
+    """The configured AI provider did not respond before the timeout."""

commitar/git.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from .errors import CommitarError
+
+
+class GitRepo:
+    def __init__(self, start: Path | None = None) -> None:
+        base = str(start or Path.cwd())
+        result = self._run("rev-parse", "--show-toplevel", cwd=base)
+        self.root = Path(result.stdout.strip()).resolve()
+
+    @staticmethod
+    def _run(
+        *args: str, cwd: str | None = None, check: bool = True
+    ) -> subprocess.CompletedProcess[str]:
+        result = subprocess.run(
+            ["git", *args], cwd=cwd, text=True, capture_output=True, check=False
+        )
+        if check and result.returncode:
+            detail = result.stderr.strip() or result.stdout.strip()
+            raise CommitarError(f"Git command failed: {detail}")
+        return result
+
+    def run(self, *args: str, check: bool = True) -> subprocess.CompletedProcess[str]:
+        return self._run(*args, cwd=str(self.root), check=check)
+
+    def staged_files(self) -> list[str]:
+        return [
+            part
+            for part in self.run("diff", "--cached", "--name-only", "-z").stdout.split("\0")
+            if part
+        ]
+
+    def staged_diff(self) -> str:
+        return self.run("diff", "--cached", "--binary").stdout
+
+    def relative_path(self, requested: Path) -> str:
+        try:
+            resolved = requested.resolve(strict=True)
+        except OSError as exc:
+            raise CommitarError(f"Invalid path: {requested}") from exc
+        try:
+            return resolved.relative_to(self.root).as_posix()
+        except ValueError as exc:
+            raise CommitarError("The path must be inside the Git worktree.") from exc
+
+    def working_files(self, pathspec: str, include_added: bool) -> list[str]:
+        changed = self.run("diff", "--name-only", "-z", "--", pathspec).stdout.split("\0")
+        files = [name for name in changed if name and (self.root / name).exists()]
+        if include_added:
+            files.extend(self.untracked_files(pathspec))
+        return sorted(set(files))
+
+    def untracked_files(self, pathspec: str) -> list[str]:
+        """Return non-ignored, untracked files inside a Git pathspec."""
+        output = self.run("ls-files", "--others", "--exclude-standard", "-z", "--", pathspec).stdout
+        return [name for name in output.split("\0") if name]
+
+    def working_diff(self, files: list[str]) -> str:
+        tracked = self.run("diff", "--binary", "--", *files).stdout if files else ""
+        untracked = []
+        tracked_set = (
+            set(self.run("ls-files", "-z", "--", *files).stdout.split("\0")) if files else set()
+        )
+        for name in files:
+            if name not in tracked_set:
+                file_path = self.root / name
+                if not file_path.is_file():
+                    continue
+                try:
+                    content = file_path.read_text(encoding="utf-8")
+                except UnicodeDecodeError:
+                    content = "[binary file]"
+                except IsADirectoryError:
+                    continue
+                untracked.append(f"--- /dev/null\n+++ b/{name}\n@@ new file @@\n{content}\n")
+        return tracked + "".join(untracked)
+
+    def add(self, files: list[str]) -> None:
+        self.run("add", "--", *files)
+
+    def unstage(self, files: list[str]) -> None:
+        self.run("reset", "--", *files)
+
+    def commit(self, message: str) -> str:
+        self.run("commit", "-m", message)
+        return self.run("rev-parse", "--short", "HEAD").stdout.strip()

commitar/scope.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from .errors import CommitarError
+from .git import GitRepo
+
+
+@dataclass(frozen=True)
+class Group:
+    files: list[str]
+    source: str
+
+
+@dataclass(frozen=True)
+class Scope:
+    staged: bool
+    groups: list[Group]
+
+
+def resolve(repo: GitRepo, requested: Path | None, include_added: bool) -> Scope:
+    staged = repo.staged_files()
+    if staged:
+        if requested is not None:
+            raise CommitarError(
+                "There are staged changes. Run `commitar` without a path to commit the current "
+                "staging, or commit/clear it before using a path."
+            )
+        return Scope(True, [Group(staged, "staged")])
+    path = requested or repo.root
+    relative = repo.relative_path(path)
+    files = repo.working_files(relative, include_added)
+    if not files:
+        untracked = repo.untracked_files(relative)
+        if untracked and not include_added:
+            preview = ", ".join(untracked[:3])
+            suffix = "..." if len(untracked) > 3 else ""
+            raise CommitarError(
+                f"No tracked file changes were found. Found {len(untracked)} untracked file(s) "
+                f"({preview}{suffix}), which are ignored by default. "
+                "Run `commitar --include-added` to include them."
+            )
+        raise CommitarError("There are no eligible changed files in this scope.")
+    if len(files) > 0 and requested is None:
+        return Scope(False, [Group([name], "working tree") for name in files])
+    return Scope(False, [Group(files, "working tree")])

commitar-1.0.0.dist-info/METADATA

@@ -0,0 +1,292 @@
+Metadata-Version: 2.4
+Name: commitar
+Version: 1.0.0
+Summary: Gerador seguro de mensagens e commits Git com IA
+License-Expression: MIT
+Project-URL: Repository, https://github.com/argolo/commitar
+Project-URL: Homepage, https://argolo.dev
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
+Requires-Dist: pip-audit>=2.7; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+# Commitar
+
+**Commitar** is a Python CLI that generates [Conventional Commits](https://www.conventionalcommits.org/) messages with AI and can optionally create Git commits. Its core principle is preserving the staging area: when the index already has changes, only those changes are considered.
+
+Portuguese documentation is available in [README-PT.md](README-PT.md).
+
+## Features
+
+- Safe preview by default: no changes are made without `--output commit`.
+- One-line Conventional Commit messages.
+- OpenAI, Gemini, and Ollama support.
+- File, directory, or whole-repository scope.
+- Staging isolation, including partially staged files.
+- TOML, environment-variable, and flag configuration.
+- Colored feedback, a generation spinner, and elapsed time per message.
+- Configurable AI timeout; the default is 60 seconds.
+
+## Requirements
+
+- Python 3.11 or later.
+- Git installed and a Git repository initialized.
+- A configured AI provider:
+  - OpenAI: `OPENAI_API_KEY`;
+  - Gemini: `GEMINI_API_KEY`;
+  - Ollama: a local service running with an installed model.
+
+## Installation
+
+```bash
+pip3 install commitar
+```
+
+For development, install the test dependencies too:
+
+```bash
+python -m pip install -e '.[dev]'
+commitar --help
+```
+
+## Quick start
+
+Configure your Git identity if necessary:
+
+```bash
+git config user.name "Your Name"
+git config user.email "you@example.com"
+```
+
+Preview tracked changes:
+
+```bash
+commitar
+```
+
+When there is no staging, Commitar generates a preview for each changed file. The preview lists the source, files, suggested message, and generation time.
+
+Untracked files are ignored for safety. Include them explicitly:
+
+```bash
+commitar --include-added
+```
+
+Create commits after a single confirmation:
+
+```bash
+commitar src/ --output commit
+```
+
+For automation, skip the interaction:
+
+```bash
+commitar src/ --output commit --yes
+```
+
+To create one commit from files explicitly selected with `git add`:
+
+```bash
+git add src/moon_service.py tests/test_moon_service.py
+commitar --output commit
+```
+
+With existing staging, Commitar exclusively uses `git diff --cached`, generates one message, and creates a commit containing exactly the files in the index.
+
+Use `--message` to skip the AI provider call. The value must be a valid one-line Conventional Commit:
+
+```bash
+commitar app.py --include-added \
+  --message "feat: add moon phase endpoint" \
+  --output commit --yes
+```
+
+## Staging safety
+
+The behavior is deliberately conservative.
+
+| Situation | Behavior |
+| --- | --- |
+| Staged files exist and `commitar` runs without a `PATH` | One message is generated from `git diff --cached`; the commit contains exactly the current index. |
+| Staged files exist and a `PATH` is supplied | The command fails without changing the repository. |
+| No staging and no `PATH` is supplied | One group is created for each changed file. |
+| No staging and a file/directory is supplied | One group contains that file or all eligible files in the directory. |
+| A file is partially staged | Only its index version is committed; remaining worktree changes stay intact. |
+
+In path mode, Commitar verifies that the index remains empty before each commit. If another process changes staging, the operation stops to prevent changes from being mixed.
+
+## Command reference
+
+```text
+commitar [OPTIONS] [PATH]
+commitar config init [OPTIONS]
+commitar config show [OPTIONS]
+```
+
+| Option | Description |
+| --- | --- |
+| `PATH` | A file or directory inside the worktree. With no value, one changed file is grouped at a time. |
+| `--output preview` | Displays the preview; this is the default. |
+| `--output commit` | Requests confirmation and creates commits. |
+| `--dry-run` | Alias for `--output preview`. |
+| `--yes`, `-y` | Does not request confirmation in `commit` mode. |
+| `--message TEXT` | Uses a manual message without calling the AI. |
+| `--include-added` | Includes untracked files. |
+| `--provider` | Selects `openai`, `gemini`, or `ollama`. |
+| `--model` | Sets the selected provider model. |
+| `--timeout-seconds` | Temporarily overrides the AI timeout. |
+| `--max-input-tokens` | Limits the estimated number of tokens in the full prompt sent to the AI. |
+| `--context-window-tokens` | Sets the shared input and reserved-output context window. |
+| `--config PATH` | Loads an additional TOML file, taking precedence over default files. |
+
+Use `commitar --help` and `commitar config --help` for current CLI details.
+
+## Configuration
+
+Create a configuration template in the repository root:
+
+```bash
+commitar config init
+```
+
+Example `.commitar.toml`:
+
+```toml
+[ai]
+provider = "ollama"
+models = ["gemma4:e4b", "qwen2.5-coder:14b"]
+endpoint = "http://localhost:11434/api/generate"
+max_input_tokens = 12000
+context_window_tokens = 32768
+max_output_tokens = 80
+temperature = 0.2
+timeout_seconds = 60
+
+[commit]
+language = "pt-BR"
+format = "conventional"
+include_added = false
+output = "preview"
+confirm = true
+
+[limits]
+max_files_per_request = 50
+max_diff_bytes = 100000
+```
+
+`models` accepts up to three models in preference order. If the AI returns an invalid message, Commitar tries the next model, for up to three attempts. `model = "name"` remains supported for a single model; `--model` takes precedence for the current run.
+
+The configuration precedence, from highest to lowest, is: CLI flags; the `--config` file; `COMMITAR_*` environment variables; `.commitar.toml` in the repository root; `~/.config/commitar/config.toml`; and built-in defaults.
+
+Supported variables are `COMMITAR_PROVIDER`, `COMMITAR_MODEL`, `COMMITAR_LANGUAGE`, `COMMITAR_OUTPUT`, `COMMITAR_ENDPOINT`, `COMMITAR_MAX_DIFF_BYTES`, and `COMMITAR_TIMEOUT_SECONDS`.
+
+Credentials are never read from TOML. Use `OPENAI_API_KEY` or `GEMINI_API_KEY`; Ollama normally does not need a key for local use.
+
+## AI providers
+
+### Ollama
+
+| Model | Recommended use |
+| --- | --- |
+| `gemma4:e4b` | A lighter option for general use and resource-constrained machines. |
+| `qwen2.5-coder:14b` | A code-focused option for machines with more memory and processing capacity. |
+
+```bash
+ollama pull gemma4:e4b
+ollama serve
+commitar --provider ollama --model gemma4:e4b
+```
+
+The default endpoint is `http://localhost:11434/api/generate`.
+
+### OpenAI
+
+```bash
+export OPENAI_API_KEY="..."
+commitar --provider openai --model gpt-5-mini
+```
+
+### Gemini
+
+```bash
+export GEMINI_API_KEY="..."
+commitar --provider gemini --model gemini-2.5-flash
+```
+
+## Context limits
+
+The context is controlled by four settings: `max_files_per_request` (maximum files per group), `max_diff_bytes` (maximum diff size), `max_input_tokens` (estimated full-prompt limit), and `context_window_tokens` (total input/output window).
+
+`max_input_tokens + max_output_tokens` cannot exceed `context_window_tokens`. Input counting is a conservative estimate independent of the provider tokenizer. In Ollama, the context window is sent as `num_ctx` and the output limit as `num_predict`. OpenAI and Gemini validate the window locally before sending the output limit.
+
+If the diff exceeds its byte or token limit, Commitar produces a deterministic summary of diff metadata. If that still exceeds a limit, the command fails explicitly; content is never silently truncated.
+
+## FastAPI example
+
+The [example/](example/) directory contains an asynchronous FastAPI API that returns the approximate Moon phase for an ISO date:
+
+```bash
+python -m pip install fastapi uvicorn
+uvicorn example.app:app --reload
+curl 'http://127.0.0.1:8000/moon-phase?date=2026-07-28'
+curl 'http://127.0.0.1:8000/next-moon-phase?phase=lua-cheia&from_date=2026-07-28'
+```
+
+`/next-moon-phase` accepts `lua-nova`, `crescente`, `quarto-crescente`, `gibosa-crescente`, `lua-cheia`, `gibosa-minguante`, `quarto-minguante`, and `minguante`. The calculation is an approximation based on the average synodic month.
+
+## Development and testing
+
+Use the `Makefile` to standardize local tasks:
+
+```bash
+make help
+```
+
+| Command | Purpose |
+| --- | --- |
+| `make venv` | Creates the local virtual environment in `.venv`. |
+| `make shell` | Opens a shell with the virtual environment enabled; run `exit` to leave it. |
+| `make install` | Installs Commitar in editable mode and all development dependencies. |
+| `make clear` | Deletes Git-ignored files with `git clean -Xdf`, including `.venv`, `.env`, caches, and builds. |
+| `make build` | Generates the wheel and source distribution in `dist/`. |
+| `make test` | Runs the pytest suite. |
+| `make coverage` | Runs tests and shows uncovered lines. |
+| `make lint` | Checks style, imports, and common issues with Ruff. |
+| `make format` | Formats code with Ruff. |
+| `make typecheck` | Runs static analysis with mypy. |
+| `make audit` | Checks dependencies for known vulnerabilities with pip-audit. |
+| `make check` | Runs linting, type checking, tests, and the audit. |
+
+```bash
+make venv
+make install
+make check
+make build
+```
+
+> **Warning:** `make clear` is destructive to ignored files. It also removes virtual environments and local files such as `.env`; back up needed local data.
+
+## Troubleshooting
+
+| Message / symptom | Recommended action |
+| --- | --- |
+| `No tracked file changes were found...` | Only new files exist. Run `commitar --include-added` to include them in the preview. |
+| `There are no eligible changed files in this scope.` | There are no changes in the supplied scope; modify a tracked file or provide another path. |
+| `There are staged changes...` | Run without a `PATH` to commit only the index, or clear/commit staging before supplying a path. |
+| Provider timeout | Commitar retries up to three times across configured models. Check the service and increase `timeout_seconds`. |
+| Credential error | Set `OPENAI_API_KEY` or `GEMINI_API_KEY` in the environment. |
+| Invalid AI response | After three invalid attempts, the current group is skipped and execution continues with the next files. |
+
+## License
+
+Distributed under the [MIT License](LICENSE). A project by André Argôlo ([argolo.dev](https://argolo.dev)).
+
+Repository: [github.com/argolo/commitar](https://github.com/argolo/commitar).

commitar-1.0.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+commitar/__init__.py,sha256=ZHFcxB3v8oJIY6wKYkxzzbMBkOY3xzwXDQil4mvr9lw,43
+commitar/ai.py,sha256=9nSFPsuLxTE7dXlWyTgk5-NlkOHvodTYrvFKlj-2TxM,6221
+commitar/cli.py,sha256=7mu2EgtPGxRCP01PKqTcAvERHCilLGOValDVMzukeyQ,11619
+commitar/config.py,sha256=MRA-IoxOS3eJPODN7M2rgRoZ_XeR8giEvmBgzmJOvKU,4664
+commitar/errors.py,sha256=bBkEkYF4kEmSCbDWkaQfEKJcyVxsyQUeojudvx35u-k,443
+commitar/git.py,sha256=8IjQK-3QlsWrI3zQQtLX0DjPmvAK-eBwchSyQxOWBbI,3544
+commitar/scope.py,sha256=4QaGiJdqsh1CNXfGLVm4BsKoVTz8sEpINf03avkwlTI,1632
+commitar-1.0.0.dist-info/licenses/LICENSE,sha256=vmqyc5Yy-tKx7me3iWqd6-xTGx8D69JcCd9WJcqrMu4,1084
+commitar-1.0.0.dist-info/METADATA,sha256=axNNNRXyuNA6nuFy9i5FShWywBMJ-aoO9VJh6ASIT_g,10704
+commitar-1.0.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+commitar-1.0.0.dist-info/entry_points.txt,sha256=WpOhDdS1FoHwoBwDg-53LF-0MRByUpDQggi42NgUEDQ,47
+commitar-1.0.0.dist-info/top_level.txt,sha256=ZliXiRp_sLVq71ZzgLshhvgIn1aEzJZkvUK8HESMiKc,9
+commitar-1.0.0.dist-info/RECORD,,

commitar-1.0.0.dist-info/WHEEL

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

commitar-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+commitar = commitar.cli:main

commitar-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 André Argôlo (argolo.dev)
+
+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.

commitar-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+commitar