comit-cli 1.0.0__tar.gz

comit_cli-1.0.0/PKG-INFO

@@ -0,0 +1,524 @@
+Metadata-Version: 2.4
+Name: comit-cli
+Version: 1.0.0
+Summary: An AI-powered Git commit assistant that understands your repository's commit style
+Author: Comit Team
+License-Expression: MIT
+Keywords: git,commit,ai,cli,groq,developer-tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: typer>=0.9.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: groq>=0.9.0
+Requires-Dist: prompt-toolkit>=3.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == "test"
+Provides-Extra: tests
+Requires-Dist: pytest>=7.0.0; extra == "tests"
+Provides-Extra: gemini
+Requires-Dist: google-genai>=0.1.0; extra == "gemini"
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == "openai"
+Provides-Extra: ollama
+Requires-Dist: ollama>=0.3.0; extra == "ollama"
+Provides-Extra: all
+Requires-Dist: groq>=0.9.0; extra == "all"
+Requires-Dist: google-genai>=0.1.0; extra == "all"
+Requires-Dist: openai>=1.0.0; extra == "all"
+Requires-Dist: ollama>=0.3.0; extra == "all"
+
+# Comit
+
+> AI-powered Git commit messages that understand your project's commit style.
+
+Comit is a lightweight developer CLI for Git. It analyzes your staged changes and recent commit history, learns your repository's commit conventions, and generates concise, accurate commit messages using your choice of AI provider.
+
+## Features
+
+- **Multi-Provider Support** — Use Groq, Google Gemini, OpenAI, or local models with Ollama.
+- **Context-aware** — Analyzes your staged diff and recent commit history to match your repository's style.
+- **Commit message validation** — Deterministically validates generated commit messages against staged files to catch mismatches before committing.
+- **Developer in control** — Review, edit, regenerate, or cancel a suggested commit message before committing.
+- **Push Integration** — Optional safe remote pushing after creating a commit.
+- **Fast-track mode** — Use `-y` to automatically commit the generated message without confirmation.
+- **Settings management** — Configure your provider, model, API keys, and endpoints interactively or via CLI commands.
+- **Safe and non-destructive** — Only analyzes staged changes with `git diff --cached`. Comit never stages files or modifies unstaged changes.
+
+## Supported Providers
+
+| Provider | Default Model | Authentication | Setup / Env Variable |
+| :--- | :--- | :--- | :--- |
+| **Groq** *(Default)* | `qwen/qwen3.8-27b` | API Key | `GROQ_API_KEY` |
+| **Google Gemini** | `gemini-2.5-flash` | API Key | `GEMINI_API_KEY` |
+| **OpenAI** | `gpt-4o-mini` | API Key | `OPENAI_API_KEY` |
+| **Ollama** | `llama3.2` | None (Local) | `OLLAMA_HOST` (default: `http://localhost:11434`) |
+
+## Installation
+
+### Requirements
+
+- Python 3.11+
+- Git
+
+### Installing from Source (Current Development)
+
+Clone the repository and install Comit into your environment:
+
+```bash
+git clone https://github.com/blackin4k/comit.git
+cd comit
+pip install .
+```
+
+For editable development mode:
+
+```bash
+pip install -e .
+```
+
+To install with additional provider SDKs and testing dependencies:
+
+```bash
+# Google Gemini SDK
+pip install -e ".[gemini]"
+
+# OpenAI SDK
+pip install -e ".[openai]"
+
+# Ollama SDK
+pip install -e ".[ollama]"
+
+# All providers and testing tools
+pip install -e ".[all,test]"
+```
+
+### Installing from PyPI (After Release)
+
+Once published to PyPI, Comit can be installed directly:
+
+```bash
+pip install comit-cli
+```
+
+With optional provider extras:
+
+```bash
+pip install "comit-cli[all]"
+```
+
+Note: The PyPI package distribution name is `comit-cli`, while the Python import package remains `comit`, providing both the `comit` and `git ai` CLI entry points.
+
+### Windows PATH Note
+
+When installing Python packages with CLI scripts, pip places executables (like `git-ai.exe`) into your Python Scripts directory.
+
+Make sure your Python Scripts directory is on your system or user `PATH` so Git discovers the `git ai` extension from any terminal session.
+
+Common Python Scripts locations on Windows:
+- System Python: `C:\Users\<Username>\AppData\Local\Programs\Python\Python313\Scripts`
+- Virtual Environment: `<venv_path>\Scripts`
+
+## Quick Start
+
+### 1. Verify Installation
+
+```powershell
+git ai --version
+```
+
+### 2. Configure Your Provider & API Key
+
+Open the interactive settings menu:
+
+```powershell
+git ai settings
+```
+
+Or configure via CLI:
+
+```powershell
+# Select provider (groq, gemini, openai, ollama)
+git ai settings set-provider groq
+
+# Set API key for the active provider
+git ai settings set-key
+
+# Or specify the provider directly
+git ai settings set-key --provider gemini
+```
+
+### 3. Generate Commit Messages
+
+Stage your files:
+
+```bash
+git add <files>
+```
+
+Run Comit:
+
+```bash
+git ai commit
+```
+
+---
+
+## Configuration & Settings
+
+Comit provides an interactive configuration interface as well as non-interactive subcommands.
+
+### Interactive Settings Menu
+
+```powershell
+git ai settings
+```
+
+Options:
+1. View configuration
+2. Select AI provider
+3. Configure API key / host
+4. Configure model
+5. Reset configuration
+6. Exit
+
+### Settings Commands
+
+- **View configuration:**
+  ```powershell
+  git ai settings show
+  ```
+
+- **Set AI provider:**
+  ```powershell
+  git ai settings set-provider gemini
+  ```
+
+- **Set API key (masked prompt):**
+  ```powershell
+  git ai settings set-key
+  git ai settings set-key --provider openai
+  ```
+
+- **Set model:**
+  ```powershell
+  git ai settings set-model qwen/qwen3.8-27b
+  git ai settings set-model gpt-4o --provider openai
+  ```
+
+- **Set Ollama host URL:**
+  ```powershell
+  git ai settings set-host http://localhost:11434
+  ```
+
+- **Reset user configuration:**
+  ```powershell
+  git ai settings reset
+  ```
+
+### Configuration Precedence
+
+Comit resolves settings in the following order:
+
+1. **Environment variables**:
+   - Provider: `COMIT_PROVIDER`
+   - Model: `COMIT_MODEL`, `GROQ_MODEL`, `GEMINI_MODEL`, `OPENAI_MODEL`, `OLLAMA_MODEL`
+   - API Keys / Endpoints: `GROQ_API_KEY`, `GEMINI_API_KEY`, `OPENAI_API_KEY`, `OLLAMA_HOST`
+2. **User configuration** (`config.json` stored in `%APPDATA%\comit` on Windows or `~/.config/comit` on Linux/macOS)
+3. **Application defaults** (Provider: `groq`, Model: `qwen/qwen3.8-27b`)
+
+---
+
+## Usage
+
+### Interactive Mode
+
+First, stage your changes:
+
+```bash
+git add <files>
+```
+
+Then run:
+
+```bash
+git ai commit
+```
+
+Comit performs a deterministic safety review of your staged changes, generates a commit suggestion, and validates the message against staged files:
+
+```text
+No issues detected.
+
+Generated:
+
+  feat: add JWT refresh token support
+
+> Accept
+  Edit
+  Regenerate
+  Cancel
+```
+
+Navigate with **Up/Down arrow keys** or **k/j**, and press **Enter** to select.
+
+If safety issues or sensitive files are detected during review, Comit displays the findings and requests confirmation before proceeding to AI generation:
+
+```text
+Review findings:
+
+WARNING
+Sensitive environment or credential file staged
+.env
+
+Continue to commit? [y/N]
+```
+
+Choosing `No` stops the commit flow safely without calling the AI or modifying files.
+
+### Actions
+
+- **Accept (`a` or `1`)** — Creates the commit using the generated message. After the local commit succeeds, you are asked whether to push to the remote (`[y/N]`, default No).
+- **Edit (`e` or `2`)** — Opens an interactive inline editor with the generated message pre-populated. Press **Enter** to save your changes, or **Esc** / **Ctrl+C** to cancel and keep the original generated message.
+- **Regenerate (`r` or `3`)** — Requests an alternative commit message from the AI provider while avoiding previous attempts.
+- **Cancel (`c`, `q`, or `4`)** — Exits cleanly without creating a commit or modifying staged changes.
+
+---
+
+### Commit Message Validation
+
+Before you accept a generated commit message, Comit deterministically validates the message against your staged changes:
+- **Syntax and structure** — Checks Conventional Commit format (`feat`, `fix`, `docs`, `refactor`, `test`, etc.), scopes, and breaking-change notation.
+- **Context matching** — Detects high-confidence mismatches, such as claiming a feature when only documentation or test files are staged, or referencing files absent from staged changes.
+
+If a mismatch is detected, Comit displays a warning:
+
+```text
+Generated:
+
+  feat: add authentication endpoints
+
+Validation warning:
+
+  Commit message type 'feat' does not match documentation-only staged changes.
+  All 1 staged file(s) are documentation files.
+
+> Accept
+  Edit
+  Regenerate
+  Cancel
+```
+
+You remain in full control to:
+- **Accept anyway** if the generated message accurately reflects your intent.
+- **Edit** the message directly.
+- **Regenerate** a new message from the AI provider.
+- **Cancel** without creating a commit.
+
+> **Note:** Commit validation is a deterministic consistency check to catch obvious mismatches before committing. It does not guarantee semantic correctness or full intent understanding of arbitrary code.
+
+---
+
+### Change Review & Safety Analysis
+
+Analyze staged changes for potential security and configuration issues before committing:
+
+```bash
+git ai review
+```
+
+Comit performs deterministic, local analysis on your staged changes to detect common problematic files and accidental additions:
+- **Sensitive files** — `.env`, `.env.*`, `credentials.json`, `secrets.yaml`, private keys (ignoring `.env.example` templates).
+- **Hardcoded secrets** — AWS keys, OpenAI/Groq/Google API keys, GitHub tokens, and literal credential assignments in added lines.
+- **Private keys** — PEM format RSA, EC, DSA, and OpenSSH private keys.
+- **Database files** — Binary databases (`.db`, `.sqlite`, `.sqlite3`, `.rdb`).
+- **Large files** — Staged files exceeding 5 MB.
+- **Generated artifacts** — `__pycache__`, `.pyc`, `dist/`, `build/`, `node_modules/`, test caches.
+- **Git internal files** — `.git-credentials`, `.gitconfig`, or staged internal `.git/` files.
+
+Example output:
+
+```text
+Review findings:
+
+HIGH
+Possible hardcoded secret or API key detected
+src/config.py
+  Detected pattern: Groq API Key (gsk...xyz)
+
+WARNING
+Sensitive environment or credential file staged
+.env
+```
+
+If no issues are found:
+
+```text
+No issues detected.
+```
+
+> **Note:** `git ai review` is a deterministic helper to assist developers before committing; it is not a full security scanner and does not guarantee security. It does not modify files, stage/unstage files, or create commits.
+
+---
+
+### Pushing Commits
+
+Pushing is strictly opt-in and safe.
+
+#### 1. Interactive commit with push confirmation
+
+```bash
+git ai commit
+```
+
+After accepting the commit, Comit asks:
+
+```text
+Commit created successfully.
+
+  feat: add JWT refresh token support
+
+Push this commit to the remote? [y/N]
+```
+
+Choosing `N` leaves the commit local:
+
+```text
+Commit created locally. Nothing was pushed.
+```
+
+#### 2. Automatic push after commit
+
+```bash
+git ai commit --push
+```
+
+Reviews the commit message interactively, and pushes automatically to `origin/<branch>` upon acceptance without a secondary prompt.
+
+#### 3. Fast mode without push
+
+```bash
+git ai commit -y
+```
+
+Automatically accepts the generated commit message. Does **not** push to the remote.
+
+#### 4. Fast mode with automatic push
+
+```bash
+git ai commit -y --push
+```
+
+Automatically accepts the generated message, creates the commit, and pushes to `origin/<branch>`.
+
+---
+
+## Safety Guarantees
+
+Comit only reads staged changes:
+
+```bash
+git diff --cached
+```
+
+Comit does NOT:
+- Automatically run `git add`
+- Modify unstaged files
+- Modify working tree files
+- Create a commit without approval (unless `-y` is explicitly passed)
+- Push to a remote without explicit confirmation or `--push`
+- Force push (`git push --force` is never executed)
+- Write API keys or credentials into repository files
+
+If no changes are staged, Comit exits without calling the AI provider.
+If no Git remote is configured, Comit reports that no remote exists and leaves your commit local.
+
+---
+
+## Testing & Quality Assurance
+
+### Running Tests
+
+Run the complete test suite:
+
+```bash
+pytest
+```
+
+Run tests with verbose output:
+
+```bash
+pytest -v
+```
+
+### Building and Verifying Distributions
+
+Build the source distribution and wheel:
+
+```bash
+python -m build
+```
+
+Validate package metadata with twine:
+
+```bash
+twine check --strict dist/*
+```
+
+---
+
+## Continuous Integration & Release
+
+### Continuous Integration (CI)
+
+The GitHub Actions CI workflow runs automatically on all pushes and pull requests to `main`. It:
+- Tests on both `ubuntu-latest` and `windows-latest`.
+- Validates against supported Python versions (3.11, 3.12, 3.13).
+- Runs the complete automated test suite.
+- Builds source distributions (`.tar.gz`) and binary wheels (`.whl`).
+- Validates distribution metadata with `twine check --strict`.
+
+### Release Process & PyPI Publishing
+
+Releases use PyPI Trusted Publishing via OpenID Connect (OIDC). No long-lived API tokens or credentials are stored in repository secrets.
+
+#### Release Workflow
+
+1. Update the version in `pyproject.toml` and `src/comit/__init__.py`.
+2. Push a version tag matching `v*` (for example, `v0.2.0`):
+   ```bash
+   git tag v0.2.0
+   git push origin v0.2.0
+   ```
+3. The release workflow automatically:
+   - Builds the wheel and source distribution.
+   - Validates package metadata.
+   - Publishes verified artifacts to PyPI via OIDC.
+
+#### PyPI Trusted Publisher Configuration
+
+To configure PyPI Trusted Publishing for this repository:
+1. Navigate to your PyPI account settings and go to **Publishing**.
+2. Add a new **GitHub Publisher**:
+   - **PyPI Project Name**: `comit-cli`
+   - **Owner**: `blackin4k`
+   - **Repository Name**: `comit`
+   - **Workflow name**: `release.yml`
+   - **Environment name**: `pypi`
+3. In GitHub repository settings, create the `pypi` environment under **Settings > Environments**.
+
+---
+
+## License
+
+MIT License.