commitron 1.0.0rc4__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. commitron-1.0.0rc4/.github/workflows/ci.yml +44 -0
  2. commitron-1.0.0rc4/AUDIT_REPORT.md +69 -0
  3. commitron-1.0.0rc4/CHANGELOG.md +111 -0
  4. commitron-1.0.0rc4/CONTRIBUTING.md +9 -0
  5. commitron-1.0.0rc4/LICENSE +21 -0
  6. commitron-1.0.0rc4/MANIFEST.in +4 -0
  7. commitron-1.0.0rc4/PKG-INFO +393 -0
  8. commitron-1.0.0rc4/README.md +361 -0
  9. commitron-1.0.0rc4/RELEASE_CHECKLIST.md +36 -0
  10. commitron-1.0.0rc4/pyproject.toml +54 -0
  11. commitron-1.0.0rc4/setup.cfg +4 -0
  12. commitron-1.0.0rc4/setup.py +4 -0
  13. commitron-1.0.0rc4/smart_commit.py +14 -0
  14. commitron-1.0.0rc4/src/commitron/__init__.py +1 -0
  15. commitron-1.0.0rc4/src/commitron/__main__.py +3 -0
  16. commitron-1.0.0rc4/src/commitron/ai.py +407 -0
  17. commitron-1.0.0rc4/src/commitron/cli.py +617 -0
  18. commitron-1.0.0rc4/src/commitron/config.py +289 -0
  19. commitron-1.0.0rc4/src/commitron/credentials.py +124 -0
  20. commitron-1.0.0rc4/src/commitron/git_ops.py +175 -0
  21. commitron-1.0.0rc4/src/commitron/providers.py +337 -0
  22. commitron-1.0.0rc4/src/commitron/safety.py +28 -0
  23. commitron-1.0.0rc4/src/commitron.egg-info/PKG-INFO +393 -0
  24. commitron-1.0.0rc4/src/commitron.egg-info/SOURCES.txt +34 -0
  25. commitron-1.0.0rc4/src/commitron.egg-info/dependency_links.txt +1 -0
  26. commitron-1.0.0rc4/src/commitron.egg-info/entry_points.txt +3 -0
  27. commitron-1.0.0rc4/src/commitron.egg-info/requires.txt +9 -0
  28. commitron-1.0.0rc4/src/commitron.egg-info/top_level.txt +1 -0
  29. commitron-1.0.0rc4/tests/test_ai.py +347 -0
  30. commitron-1.0.0rc4/tests/test_cli.py +462 -0
  31. commitron-1.0.0rc4/tests/test_config.py +149 -0
  32. commitron-1.0.0rc4/tests/test_credentials.py +120 -0
  33. commitron-1.0.0rc4/tests/test_git_ops.py +145 -0
  34. commitron-1.0.0rc4/tests/test_providers.py +272 -0
  35. commitron-1.0.0rc4/tests/test_safety.py +21 -0
@@ -0,0 +1,44 @@
1
+ name: CI
2
+ on:
3
+ push:
4
+ pull_request:
5
+ workflow_dispatch:
6
+ permissions:
7
+ contents: read
8
+ jobs:
9
+ test:
10
+ strategy:
11
+ fail-fast: false
12
+ matrix:
13
+ os: [ubuntu-latest, windows-latest, macos-latest]
14
+ python-version: ['3.11', '3.12', '3.13', '3.14', '3.15']
15
+ runs-on: ${{ matrix.os }}
16
+ steps:
17
+ - uses: actions/checkout@v6
18
+ - uses: actions/setup-python@v6
19
+ with:
20
+ python-version: ${{ matrix.python-version }}
21
+ - name: Install package, test tools, and optional credential backend
22
+ run: |
23
+ python -m pip install --upgrade pip setuptools wheel
24
+ python -m pip install -e ".[test,secure-store]"
25
+ - name: Lint
26
+ run: ruff check src tests
27
+ - name: Test and measure coverage
28
+ run: |
29
+ coverage run -m pytest
30
+ coverage report --fail-under=80
31
+ - name: Build wheel and source distribution
32
+ run: |
33
+ python -m pip install build twine
34
+ python -m build
35
+ python -c "import glob, subprocess, sys; subprocess.check_call([sys.executable, '-m', 'twine', 'check', *glob.glob('dist/*')])"
36
+ - name: Install wheel and smoke-test CLI
37
+ run: |
38
+ python -c "import glob, subprocess, sys; subprocess.check_call([sys.executable, '-m', 'pip', 'install', '--no-deps', glob.glob('dist/*.whl')[0]])"
39
+ commitron --version
40
+ commitron --help
41
+ - name: Audit installed dependencies
42
+ run: |
43
+ python -m pip install pip-audit
44
+ pip-audit
@@ -0,0 +1,69 @@
1
+ # Commitron repository audit and release-candidate reconciliation
2
+
3
+ Audit date: 2026-11-07
4
+
5
+ ## Scope and evidence
6
+
7
+ This report separates the public `main` branch observed on GitHub from the locally built release-candidate source tree. The public repository was not modified.
8
+
9
+ Public repository: https://github.com/Error404-uv/commitron
10
+
11
+ Observed public `main` at audit time:
12
+
13
+ | Public file | Finding |
14
+ |---|---|
15
+ | `.gitignore` | Ignores virtual environments, bytecode, `.env`, egg-info, build, and dist. It does not yet ignore common test/coverage/linter caches. |
16
+ | `LICENSE` | MIT License is present with 2026 Error404-uv copyright. |
17
+ | `README.md` | Still presents the project as a Gemini-only commit-message generator, documents the old `smart-commit` command, and states Python 3.9+. |
18
+ | `requirements.txt` | Contains `google-generativeai` and `rich` without version constraints. |
19
+ | `setup.py` | Declares version `0.2.0`, Python `>=3.9`, those two dependencies, and only the `smart-commit` console entry point. |
20
+ | `smart_commit.py` | Uses `git add .` after a broad confirmation, truncates diffs to 3,000 characters, and does not check the return code of its diff subprocess helper. Its Gemini request loop catches broad exceptions and retries without an explicit request timeout. |
21
+
22
+ The public repository page showed one commit and no visible test, CI, or release files at audit time.
23
+
24
+ Sources:
25
+
26
+ - Repository listing and README: https://github.com/Error404-uv/commitron
27
+ - Original implementation: https://github.com/Error404-uv/commitron/blob/main/smart_commit.py
28
+ - Original packaging: https://github.com/Error404-uv/commitron/blob/main/setup.py
29
+ - Original dependencies: https://github.com/Error404-uv/commitron/blob/main/requirements.txt
30
+
31
+ ## Reconciliation in this release candidate
32
+
33
+ The six-file public baseline has now been reviewed file by file. The v1.0.0rc3 working copy contains a modern `src/commitron` package, `pyproject.toml`, a `commitron` console command, test and optional secure-store extras, CI configuration, a test suite, documentation, and the MIT license. The old root `smart_commit.py` has been replaced with a compatibility shim that delegates to the maintained CLI. This prevents the legacy entry point from retaining its separate bulk-staging behavior.
34
+
35
+ ## Additional fixes in rc2
36
+
37
+ - Branch creation and switching now validate names with Git before executing the command. This rejects option-like names before they can be interpreted as Git flags.
38
+ - Custom API base URLs reject whitespace, control characters, query strings, fragments, and invalid ports.
39
+ - Provider HTTP redirects are disabled so credentials are not forwarded through an unexpected redirect chain.
40
+ - Provider response bodies are limited to 2 MB.
41
+ - Mixed OpenAI text/non-text content blocks are parsed without type errors.
42
+ - Existing project configuration must be a JSON object before an update is attempted.
43
+
44
+ ## Additional fixes in rc3
45
+
46
+ - API credentials from environment variables and the optional OS keychain are validated before provider use. Control characters and line breaks are rejected, and credential values are limited to 4,096 characters.
47
+ - Keychain values that are not text are rejected rather than passed into HTTP authorization headers.
48
+ - README's current Python CI matrix now matches the workflow configuration.
49
+
50
+ ## Verification completed in this environment
51
+
52
+ - Automated tests: 98 tests pass locally.
53
+ - Coverage: 86% line coverage; exceeds the configured 80% threshold.
54
+ - Python compilation: passed.
55
+ - Wheel build: passed.
56
+ - Local sdist build: see release output.
57
+ - Ruff could not be run because it is not installed and this environment has no package-index network access.
58
+
59
+ ## Still requiring external verification
60
+
61
+ - Hosted GitHub Actions matrix on Windows, Linux, and macOS.
62
+ - Ruff run in a network-enabled environment.
63
+ - `pip-audit` results in CI against current package advisories.
64
+ - Live Gemini/OpenAI requests and an Ollama server integration test.
65
+ - Native Windows Credential Manager, macOS Keychain, and Linux Secret Service tests.
66
+ - Final dependency license compatibility review before publishing.
67
+ - Explicit owner approval before any push to GitHub or PyPI publication.
68
+
69
+ A release candidate is not a stable release until those checks have passed. This archive does not modify the user's GitHub repository or local machine.
@@ -0,0 +1,111 @@
1
+ # Changelog
2
+
3
+ ## 1.0.0rc4 — Multi-provider extensibility, retry logic, and debug output
4
+
5
+ - Extend AI provider support: **Gemini, OpenAI, Ollama** plus new built-ins **Anthropic, Groq, DeepSeek, OpenRouter**. All are configurable via `commitron config set provider <name>`; their keys are read from environment variables or the OS keychain (`commitron auth set <name>`). Ollama needs no API key.
6
+ - Make the provider layer extensible via `register_provider(name, provider_class, key_env, default_model, default_url)`: new providers can be added without touching core validation.
7
+ - Add automatic retry on transient AI errors (HTTP 429 rate limits, 5xx server errors, timeouts) using exponential backoff, configurable via `COMMITRON_RETRY_COUNT` (default 3) and `COMMITRON_RETRY_DELAY` (default 1.0s). Local providers (Ollama on localhost) default to 1 retry.
8
+ - Add `--verbose` / `-v` to print provider, model, and request size when generating messages (now on `commit`, `explain`, `branch suggest`, `split`, `history --analyze`, `git-help`). Verbose mode also reports retry progress ("attempt N/M").
9
+ - Add `commitron doctor` to diagnose environment health: Python version, Git availability, repository detection, config validity, credential status, and provider network reachability with a pass/fail summary.
10
+ - Add `commitron config path` to print the configuration file location.
11
+ - Clarify `auth set`: API-key storage now supported for Gemini, OpenAI, Anthropic, Groq, DeepSeek, and OpenRouter; `auth status` lists every provider.
12
+ - Document cross-platform support (Windows, macOS, and all mainstream Linux distros) and the universal `py3-none-any` wheel.
13
+
14
+
15
+
16
+ ## 1.0.0rc2 — Safety and release-candidate fixes
17
+
18
+ - Replaced the legacy root `smart_commit.py` implementation (which could offer `git add .`) with a compatibility shim that delegates to the maintained CLI.
19
+ - Validate branch names with Git before create/switch operations, preventing option-like names from being interpreted as Git flags.
20
+ - Reject malformed custom API URLs containing query strings, fragments, invalid ports, whitespace, or control characters.
21
+ - Block HTTP redirects for provider requests so API credentials are not forwarded through unexpected redirect chains.
22
+ - Bound provider response bodies to 2 MB and handle non-text OpenAI content blocks safely.
23
+ - Reject non-object existing `.commitron.json` files before attempting to update them.
24
+ - Expanded regression tests for branch argument safety, endpoint validation, provider response limits, and legacy entry-point behavior.
25
+ - Added CI dependency-audit and package-metadata validation steps.
26
+
27
+ ## 1.0.0rc1 — Release candidate and verification hardening
28
+
29
+ - Reproducible test configuration now includes coverage measurement and an 80% minimum line-coverage gate in CI.
30
+ - CI now runs linting, tests, coverage enforcement, and source/wheel builds on the configured Windows, Linux, and macOS Python matrix.
31
+ - Interactive terminal input now handles end-of-input cleanly and exits without continuing an operation.
32
+ - Versioned as a release candidate, not a stable 1.0 release: live provider and native keychain tests plus actual hosted CI runs are still required.
33
+
34
+ ## 0.9.0 — Interactive staging and credential storage
35
+
36
+ - Added `commitron stage` to review changed paths and stage only explicitly selected files.
37
+ - Used NUL-delimited Git status output and literal Git pathspecs to handle spaces and pathspec-like filenames safely.
38
+ - Added optional OS credential-manager integration through the `secure-store` extra; environment variables retain precedence and credentials remain outside config/profile files.
39
+ - Added `auth set`, `auth status`, and `auth delete` commands without displaying secret values.
40
+ - Rejected known plaintext/fail/null keyring backends rather than silently storing credentials insecurely.
41
+ - Fixed root-level pytest discovery for the `src/` package layout.
42
+ - Added tests for selective staging, cancellation, unusual filenames, credential precedence, and keyring behavior.
43
+
44
+
45
+ ## 0.8.0 — Interactive profile management
46
+
47
+ - Replaced the misleading profile-list menu shortcut with a complete interactive profile manager.
48
+ - Added menu workflows to list, save, apply, and delete profiles.
49
+ - Added an overwrite confirmation before replacing an existing profile from the interactive menu.
50
+ - Added tests for profile-menu CRUD flows, overwrite confirmation, empty-profile states, and malformed configuration handling.
51
+ - Configuration updates now reject malformed existing setting types instead of silently dropping them and potentially resetting user settings.
52
+
53
+
54
+ ## 0.7.0 — Interactive terminal and configuration profiles
55
+
56
+ - Added `commitron menu`, a guided terminal menu for common Git workflows and settings.
57
+ - Added `commitron config wizard` for interactive provider/model/endpoint configuration.
58
+ - Added named AI configuration profiles: `config profile save|list|use|delete`.
59
+ - Profiles store provider, model, and base URL only; API credentials are supplied through environment variables or the optional OS keychain.
60
+ - Profile files are written atomically with restrictive POSIX permissions where supported.
61
+ - Added validation for profile names, provider values, and endpoint security.
62
+ - Menu actions delegate to existing CLI commands; they do not bypass existing confirmation and privacy gates.
63
+
64
+ ## 0.6.0 — 2026-11-07
65
+
66
+ - Added `git-help` to explain user-supplied Git errors with safe, non-executing diagnostic guidance after explicit data-sharing confirmation.
67
+ - Added `history --analyze` to summarize recent commit metadata after explicit data-sharing confirmation.
68
+ - Added bounded structured history retrieval and validation for AI analysis inputs and outputs.
69
+ - Added tests for history metadata parsing, prompt-injection boundaries, input limits, CLI parsing, and confirmation gates.
70
+ - Documented the privacy implications and limitations of metadata-only history analysis.
71
+
72
+
73
+ ## 0.5.0 — 2026-11-07
74
+
75
+ - Added AI branch-name suggestions with explicit data-sharing confirmation, strict lowercase prefix/name checks, Git-native branch-name validation, and duplicate-branch rejection; suggestions never create branches automatically.
76
+ - Added file-level logical commit grouping from staged changes with strict JSON validation and exact changed-file coverage. The command is advisory and never modifies the index or commits.
77
+ - Added repository-specific commit-message conventions stored in `.commitron.json`, with `show`, `set`, and `clear` commands. Symlinked project config files are rejected on read and write.
78
+ - Applied project conventions to AI-generated commit-message candidates.
79
+ - Added tests for branch suggestions, logical grouping validation, repository conventions, and non-mutating CLI behavior.
80
+ - Updated CI to current checkout/setup-python action majors and Python 3.11–3.15 across Windows, macOS, and Linux.
81
+ - Documented the limits of file-level grouping and the privacy implications of project convention text.
82
+
83
+
84
+ ## 0.4.1 — 2026-11-07
85
+
86
+ - Validate AI commit-message format, uniqueness, 72-character subject length, and requested candidate count.
87
+ - Move Gemini, OpenAI, and Ollama into separate adapters behind a shared provider contract.
88
+ - Replace silent diff truncation with lossless chunk processing and an explicit maximum-size guard.
89
+ - Expand heuristic secret detection patterns.
90
+ - Render untrusted Git and AI text as literal Rich `Text` objects.
91
+ - Raise the supported Python baseline to 3.11 and update the CI matrix to Python 3.11–3.13.
92
+
93
+
94
+ ## 0.4.0
95
+
96
+ - Added provider-neutral AI generation for Gemini, OpenAI Chat Completions, and Ollama.
97
+ - Added `commitron explain` for staged and unstaged tracked-file diffs.
98
+ - Added per-user configuration commands with environment-variable overrides.
99
+ - Kept API keys out of the config file and rejected remote non-HTTPS custom endpoints.
100
+ - Added tracked changed-file listing and staged/unstaged diff summaries.
101
+ - Expanded tests for configuration, provider response parsing, prompts, and CLI parsing.
102
+
103
+ ## 0.3.0
104
+
105
+ - Reorganized the application into an installable `src/` package.
106
+ - Added `commitron` CLI and retained `smart-commit` plus the legacy script launcher.
107
+ - Added status, staged diff, history, and branch commands.
108
+ - Removed automatic `git add .`; commits now use only the existing index.
109
+ - Added staged-diff privacy warnings, bounded diff submission, API timeout, and clearer errors.
110
+ - Replaced the legacy Gemini SDK dependency with a standard-library REST adapter.
111
+ - Added pytest coverage and a Windows/macOS/Linux CI matrix.
@@ -0,0 +1,9 @@
1
+ # Contributing
2
+
3
+ 1. Open an issue describing the bug or proposed change.
4
+ 2. Create a focused branch and keep changes small.
5
+ 3. Install development dependencies with `python -m pip install -e ".[test]"`.
6
+ 4. Run `pytest` and `ruff check src tests` before opening a pull request.
7
+ 5. Never include API keys, credentials, private diffs, or personal data in tests or issue reports.
8
+
9
+ Please include the operating system, Python version, Git version, reproduction steps, and sanitized logs.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Error404-uv
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,4 @@
1
+ include README.md LICENSE CHANGELOG.md CONTRIBUTING.md RELEASE_CHECKLIST.md AUDIT_REPORT.md
2
+ include smart_commit.py
3
+ recursive-include .github *.yml
4
+ recursive-include tests *.py
@@ -0,0 +1,393 @@
1
+ Metadata-Version: 2.4
2
+ Name: commitron
3
+ Version: 1.0.0rc4
4
+ Summary: A safer AI-powered Git assistant for the command line
5
+ Author: Error404-uv
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/Error404-uv/commitron
8
+ Project-URL: Repository, https://github.com/Error404-uv/commitron
9
+ Project-URL: Issues, https://github.com/Error404-uv/commitron/issues
10
+ Classifier: Programming Language :: Python :: 3
11
+ Classifier: Programming Language :: Python :: 3.11
12
+ Classifier: Programming Language :: Python :: 3.12
13
+ Classifier: Programming Language :: Python :: 3.13
14
+ Classifier: Programming Language :: Python :: 3.14
15
+ Classifier: Programming Language :: Python :: 3.15
16
+ Classifier: Programming Language :: Python :: 3.14
17
+ Classifier: Programming Language :: Python :: 3.15
18
+ Classifier: Operating System :: OS Independent
19
+ Classifier: Environment :: Console
20
+ Classifier: Topic :: Software Development :: Version Control :: Git
21
+ Requires-Python: >=3.11
22
+ Description-Content-Type: text/markdown
23
+ License-File: LICENSE
24
+ Requires-Dist: rich<15,>=13.7
25
+ Provides-Extra: test
26
+ Requires-Dist: pytest<10,>=8; extra == "test"
27
+ Requires-Dist: coverage<8,>=7; extra == "test"
28
+ Requires-Dist: ruff<1,>=0.6; extra == "test"
29
+ Provides-Extra: secure-store
30
+ Requires-Dist: keyring<27,>=25; extra == "secure-store"
31
+ Dynamic: license-file
32
+
33
+ <div align="center">
34
+
35
+ # ⚡ Commitron
36
+
37
+ ### A safer, multi-provider AI Git assistant for your terminal
38
+
39
+ [![Python](https://img.shields.io/badge/Python-3.11%2B-blue)](https://www.python.org/)
40
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
41
+ [![Windows](https://img.shields.io/badge/Windows-tested-success)](https://github.com/Error404-uv/commitron/actions)
42
+ [![Linux/macOS](https://img.shields.io/badge/Linux%20%2F%20macOS-pyproject-wheel-success)](https://pypi.org/project/commitron/)
43
+
44
+ </div>
45
+
46
+ Commitron assists with everyday Git workflows and uses an AI provider you choose to draft commit messages or explain changes. It works from staged or unstaged diffs; it can stage only paths you explicitly select with `commitron stage`, and it never silently stages files. It does not push, pull, reset, stash, or rewrite history.
47
+
48
+ ## What's new in 1.0.0rc4
49
+
50
+ - Extend AI provider support: **Gemini, OpenAI, Ollama** plus new built-ins **Anthropic, Groq, DeepSeek, OpenRouter**. All are configurable via `commitron config set provider <name>`; their API keys are read from env vars or the OS keychain (`commitron auth set <name>`). Ollama needs no API key.
51
+ - Make the provider registry extensible: new providers can be added via `register_provider(name, provider_class, key_env, default_model, default_url)` without editing core validation logic.
52
+ - Add automatic retry on transient AI errors (HTTP 429 rate limits, 5xx server errors, timeouts). Retries use exponential backoff; configurable via `COMMITRON_RETRY_COUNT` (default 3) and `COMMITRON_RETRY_DELAY` (default 1.0s).
53
+ - Add `--verbose` / `-v` to print provider, model, and request size when generating messages (now on `commit`, `explain`, `branch suggest`, `split`, `history --analyze`, `git-help`). In verbose mode, retries also print "attempt N/M" progress.
54
+ - Add `commitron doctor` to diagnose the environment: Python version, Git availability, repository detection, config validity, credential status, and provider network reachability — with a pass/fail summary.
55
+ - Add `commitron config path` to print the configuration file location.
56
+ - Retry count now defaults to 1 for local providers (Ollama on localhost) and 3 for remote providers; override with `COMMITRON_RETRY_COUNT`.
57
+ - Clarify `auth set`: Gemini, OpenAI, Anthropic, Groq, DeepSeek, and OpenRouter keys can be stored; Ollama needs no key.
58
+ - Document cross-platform support (Windows, macOS, and all mainstream Linux distros) and universal `py3-none-any` wheel.
59
+
60
+ ## What's new in 1.0.0rc2
61
+
62
+ - Replaced the old root `smart_commit.py` implementation with a compatibility shim to the maintained CLI; the legacy `git add .` behavior is no longer present in that entry point.
63
+ - Validate Git branch names before creating or switching branches.
64
+ - Harden custom API URL validation and block provider HTTP redirects to avoid forwarding credentials unexpectedly.
65
+ - Limit provider responses to 2 MB and handle mixed text/non-text OpenAI response blocks safely.
66
+ - Reject malformed project configuration files before overwriting them.
67
+ - This is still a release candidate, not a stable 1.0 release. Hosted CI, live AI-provider, and native OS keychain verification are still outstanding.
68
+
69
+ ## What's new in 1.0.0rc1
70
+
71
+ - Release-candidate build with reproducible coverage reporting and an 80% CI coverage threshold.
72
+ - CI runs Ruff, pytest, coverage enforcement, and package builds across the configured Windows, Linux, and macOS matrix.
73
+ - Interactive commands exit cleanly if terminal input closes unexpectedly.
74
+
75
+ ## What's new in 0.9.0
76
+
77
+ - Added `commitron stage` for interactive whole-file staging of explicitly selected changed paths, including untracked files.
78
+ - Added optional OS credential-manager support through `commitron[secure-store]` and `commitron auth`; environment variables take precedence and credentials are not stored in JSON.
79
+ - Refuse known plaintext/fail/null keyring backends.
80
+ - Fixed root-level pytest discovery for the `src/` layout.
81
+
82
+ ## What's new in 0.8.0
83
+
84
+ - The interactive `commitron menu` now includes a real AI-profile manager: list, save, apply, and delete profiles without leaving the menu.
85
+ - Replacing an existing profile through the menu requires confirmation.
86
+ - Added automated tests for interactive profile-management flows, overwrite confirmation, empty-profile handling, and malformed configuration handling.
87
+ - Configuration updates reject malformed existing setting types rather than silently dropping them.
88
+
89
+ ## What's new in 0.7.0
90
+
91
+ - `commitron menu` opens a guided terminal menu for status, diff review, smart commit, change explanation, history, settings, and profile management. Menu actions call the same command handlers and retain their safety confirmations.
92
+ - `commitron config wizard` interactively configures provider, model, and custom endpoint.
93
+ - Named provider profiles can be saved, listed, applied, and deleted with `commitron config profile`. Profiles contain no API keys; credentials are read from environment variables or the optional OS credential manager.
94
+
95
+ ## What's new in 0.6.0
96
+
97
+ - Added `commitron git-help --error "..."` to explain a pasted Git error and suggest safe diagnostic steps. The error and optional context are sent to the configured AI provider only after explicit confirmation; the assistant is instructed not to recommend destructive commands as routine fixes and does not execute commands.
98
+ - Added `commitron history --analyze` to summarize recent commit subjects and bodies, identify recurring work areas, and distinguish observations from cautious inferences. Commit metadata is sent only after explicit confirmation.
99
+ - Added structured Git history retrieval with bounded limits and tests for metadata parsing, prompt-injection handling, input limits, and confirmation gates.
100
+
101
+ ## What's new in 0.5.0
102
+
103
+ - `commitron branch suggest --description "..."` asks the configured AI provider for a branch name, checks it with Git's branch-name validator, and refuses names that already exist. It only prints a suggestion; it never creates a branch.
104
+ - `commitron split` analyzes staged tracked-file changes and suggests file-level logical commit groups with a message and rationale for each group. Every staged changed path must appear exactly once in a valid response. It never stages, unstages, or commits files.
105
+ - `commitron convention set "..."` saves repository-specific commit-message guidance in `.commitron.json`; `show` displays it and `clear` removes it. Commit-message generation uses this guidance when present.
106
+ - Added tests for AI branch-name validation, complete logical-group coverage, project conventions, and non-mutating CLI behavior.
107
+
108
+ ## What's new in 0.4.1
109
+
110
+ - Validate AI-generated commit messages for the selected style, uniqueness, single-line format, 72-character subject length, and response count.
111
+ - Separate Gemini, OpenAI, and Ollama implementations behind one provider adapter contract.
112
+ - Process large diffs in ordered, lossless chunks instead of silently truncating them; refuse oversized diffs before sending any content.
113
+ - Expand heuristic credential warnings for GitHub, GitLab, Slack, Stripe, npm, AWS, Google, private keys, and JWT-like values.
114
+ - Render repository-controlled text and AI output as literal terminal text to prevent Rich markup interpretation.
115
+ - The original CI matrix at that milestone targeted Python 3.11–3.13; the current workflow is documented under Requirements and Development.
116
+
117
+ ## What's new in 0.4.0
118
+
119
+ - Provider adapters for **Google Gemini**, **OpenAI Chat Completions**, and **Ollama** local models.
120
+ - `commitron explain` for a concise explanation of staged or unstaged tracked-file changes.
121
+ - `commitron config` for per-user provider/model/base URL settings.
122
+ - API keys can be read from environment variables or the optional OS credential manager; they are never written to config or profile files.
123
+ - HTTPS is required for remote custom endpoints; plain HTTP is accepted only for local endpoints.
124
+ - `files` and richer `diff` commands for reviewing staged or unstaged tracked-file changes.
125
+ - Secret-pattern checks before sending diffs to an AI provider.
126
+
127
+ ## Requirements
128
+
129
+ - Python 3.11 or newer (CI targets 3.11–3.15)
130
+ - Git available on `PATH`
131
+ - An API key for Gemini or OpenAI, or a running local Ollama server
132
+
133
+ Commitron works out of the box on Windows 10/11, macOS (Intel + Apple Silicon), and all mainstream Linux distributions — Ubuntu, Debian, Fedora, Arch, Kali, Parrot OS, Mint, etc. Because the wheel is `py3-none-any` (pure Python), there is no per-platform build; the same installed package runs on every OS.
134
+
135
+ ## Install
136
+
137
+ Commitron ships a universal wheel (`py3-none-any`) — the same package works on Windows, Linux (Ubuntu, Debian, Fedora, Arch, Kali, Parrot, etc.), and macOS:
138
+
139
+ ```bash
140
+ # Any Linux/macOS
141
+ python3 -m pip install commitron
142
+
143
+ # Windows PowerShell
144
+ python -m pip install commitron
145
+
146
+ # Windows Command Prompt
147
+ python -m pip install commitron
148
+ ```
149
+
150
+ Need it for a project? Install from source:
151
+
152
+ ```bash
153
+ git clone https://github.com/Error404-uv/commitron.git
154
+ cd commitron
155
+ pip install -e .
156
+ ```
157
+
158
+ For development and tests:
159
+
160
+ ```bash
161
+ python -m pip install -e ".[test]"
162
+ pytest
163
+ ruff check src tests
164
+ ```
165
+
166
+ The legacy source-checkout command `python smart_commit.py` remains available as a compatibility shim and invokes the maintained `commitron` CLI. It no longer contains a separate implementation.
167
+
168
+ ## AI providers
169
+
170
+ Commitron works with any AI provider you choose. Built-in providers (all configurable via `commitron config set provider <name>`):
171
+
172
+ - **Gemini** (Google) — env `GEMINI_API_KEY`, free tier (default; `gemini-2.5-flash`)
173
+ - **OpenAI** — env `OPENAI_API_KEY`, paid (`gpt-4.1-mini`)
174
+ - **Ollama** — no API key, local models (`ollama pull qwen2.5-coder:7b`)
175
+ - **Anthropic** — env `ANTHROPIC_API_KEY`, Claude 3 Haiku
176
+ - **Groq** — env `GROQ_API_KEY`, free tier, fast open-weight models
177
+ - **DeepSeek** — env `DEEPSEEK_API_KEY`, free tier, DeepSeek-Coder
178
+ - **OpenRouter** — env `OPENROUTER_API_KEY`, gateway to many models
179
+
180
+ Any of these can be set via environment variable, saved in the OS keychain (`commitron auth set <provider>`), or configured interactively with `commitron config wizard`. Ollama needs no API key.
181
+
182
+ ## Choose an AI provider
183
+
184
+ The default provider remains Gemini for compatibility:
185
+
186
+ ```bash
187
+ commitron config set provider gemini
188
+ ```
189
+
190
+ **Gemini** — set `GEMINI_API_KEY` in your environment. Default model: `gemini-2.5-flash`.
191
+
192
+ **OpenAI** — set `OPENAI_API_KEY` in your environment, then:
193
+
194
+ ```bash
195
+ commitron config set provider openai
196
+ commitron config set model gpt-4.1-mini
197
+ ```
198
+
199
+ **Ollama** — start Ollama locally, pull a model, then configure it:
200
+
201
+ ```bash
202
+ ollama pull qwen2.5-coder:7b
203
+ commitron config set provider ollama
204
+ commitron config set model qwen2.5-coder:7b
205
+ ```
206
+
207
+ View or interactively configure the effective settings:
208
+
209
+ ```bash
210
+ commitron config show
211
+ commitron config wizard
212
+ ```
213
+
214
+ Store API credentials in the operating-system credential manager (optional):
215
+
216
+ ```bash
217
+ python -m pip install "commitron[secure-store]"
218
+ commitron auth set gemini
219
+ commitron auth set openai
220
+ commitron auth status
221
+ commitron auth delete openai
222
+ ```
223
+
224
+ The optional keyring integration uses an available OS-backed credential backend and refuses known plaintext/fallback backends. Environment variables (`GEMINI_API_KEY`, `OPENAI_API_KEY`) take precedence. If a secure OS backend is unavailable, use environment variables instead. Credentials are never written to Commitron's JSON configuration or profile files.
225
+
226
+ Save and switch between named provider configurations (API keys are never included):
227
+
228
+ ```bash
229
+ commitron config profile save work
230
+ commitron config profile save local
231
+ commitron config profile list
232
+ commitron config profile use local
233
+ commitron config profile delete work
234
+ ```
235
+
236
+ Open the interactive terminal menu:
237
+
238
+ ```bash
239
+ commitron menu
240
+ ```
241
+
242
+ Settings are stored in a per-user `config.json` location: `%APPDATA%\\commitron` on Windows, `~/Library/Application Support/commitron` on macOS, or `$XDG_CONFIG_HOME/commitron` (default `~/.config/commitron`) on Linux. Environment variables override saved settings:
243
+
244
+ - `COMMITRON_PROVIDER`
245
+ - `COMMITRON_MODEL`
246
+ - `COMMITRON_BASE_URL`
247
+ - `GEMINI_API_KEY` / `OPENAI_API_KEY`
248
+
249
+ Provider-specific model overrides are also supported through `COMMITRON_GEMINI_MODEL`, `COMMITRON_OPENAI_MODEL`, and `COMMITRON_OLLAMA_MODEL`.
250
+
251
+ Set the relevant key in the current terminal session:
252
+
253
+ ```powershell
254
+ # Windows PowerShell
255
+ $env:GEMINI_API_KEY = "your-key"
256
+ $env:OPENAI_API_KEY = "your-key"
257
+ ```
258
+
259
+ ```bat
260
+ :: Windows Command Prompt
261
+ set GEMINI_API_KEY=your-key
262
+ set OPENAI_API_KEY=your-key
263
+ ```
264
+
265
+ ```bash
266
+ # macOS / Linux
267
+ export GEMINI_API_KEY="your-key"
268
+ export OPENAI_API_KEY="your-key"
269
+ ```
270
+
271
+ For OpenAI-compatible gateways, set `base_url` to the API root (for example `https://your-host.example/v1`). Do not put credentials in the URL. Remote HTTP endpoints are rejected to avoid sending API credentials over an unencrypted connection.
272
+
273
+ ## Git workflows
274
+
275
+ Run commands inside a Git repository:
276
+
277
+ ```bash
278
+ commitron status
279
+ commitron stage # interactively select exact paths to stage
280
+ commitron files # staged tracked files
281
+ commitron files --unstaged # unstaged tracked files
282
+ commitron diff # staged diff
283
+ commitron diff --unstaged # unstaged diff
284
+ commitron diff --stat # staged summary
285
+ commitron history --limit 15
286
+ commitron history --analyze --limit 20
287
+ commitron branch
288
+ commitron branch create feature/my-change
289
+ commitron branch switch main
290
+ commitron branch suggest --description "Add OAuth login"
291
+ ```
292
+
293
+ The AI branch suggestion sends the task description and current branch names to your configured AI provider after an explicit confirmation. Possible credential patterns trigger an additional warning. The suggested name is checked against Git's ref-format rules and existing branches; no branch is created automatically. Review the suggestion before creating it.
294
+
295
+ Suggest logical file-level commits from the current staged diff:
296
+
297
+ ```bash
298
+ commitron split
299
+ commitron split --style gitmoji
300
+ ```
301
+
302
+ `split` requires at least two staged tracked files. It groups whole files, not individual hunks within one file. Treat the output as a review aid: the grouping is AI-generated and may be wrong. Commitron does not change the Git index or create commits.
303
+
304
+ Set repository-specific commit-message guidance:
305
+
306
+ ```bash
307
+ commitron convention set "Use feat(scope): summary; scopes are lowercase; include a ticket ID when one is present."
308
+ commitron convention show
309
+ commitron convention clear
310
+ ```
311
+
312
+ This writes `.commitron.json` at the Git repository root. It contains guidance only, not API credentials. You can commit it to share conventions with teammates, or add it to `.gitignore` for local-only preferences. Keep the text focused on formatting rules; it is passed to the configured AI provider as prompt guidance.
313
+
314
+
315
+ Stage only the files you intend to include, then draft a commit message. You can use `commitron stage` to select exact changed paths interactively, or use Git directly:
316
+
317
+ ```bash
318
+ git add path/to/file.py
319
+ commitron commit --dry-run
320
+ commitron commit
321
+ ```
322
+
323
+ Other options:
324
+
325
+ ```bash
326
+ commitron commit --style gitmoji --count 5
327
+ commitron commit --style plain
328
+ commitron commit --yes
329
+ ```
330
+
331
+ `--yes` selects the first generated suggestion and skips the final commit confirmation. It does not skip the secret warning. `--dry-run` never creates a commit. Commitron never runs `git add .` automatically.
332
+
333
+ Explain a pasted Git error using the selected provider:
334
+
335
+ ```bash
336
+ commitron git-help --error "fatal: not a git repository (or any of the parent directories): .git"
337
+ commitron git-help --error "fatal: refusing to merge unrelated histories" --context "running git pull"
338
+ ```
339
+
340
+ Commitron asks before sending the error and optional context. It provides explanations and diagnostic suggestions only; it does not run suggested commands. Review AI advice before acting, especially if it involves changing repository state.
341
+
342
+ Analyze recent commit history:
343
+
344
+ ```bash
345
+ commitron history --analyze --limit 20
346
+ ```
347
+
348
+ This sends recent commit hashes, dates, subjects and bodies to the configured AI provider after confirmation. Commit messages can contain sensitive information; review your history and any heuristic secret warnings before approving. The analysis is a summary of commit metadata, not a code-level audit and not proof that a feature is correct or complete.
349
+
350
+ Explain changes using the selected provider:
351
+
352
+ ```bash
353
+ commitron explain # staged changes
354
+ commitron explain --unstaged # unstaged tracked-file changes
355
+ ```
356
+
357
+ ## Privacy and safety
358
+
359
+ - Commitron sends the selected diff to the configured AI provider when you run `commit`, `explain`, or `split`. `branch suggest` sends the task description and current branch names only after an explicit confirmation. Review all content first; code, project convention text, task details, and accidentally staged secrets may be disclosed to that provider.
360
+ - The local secret detector checks a small set of patterns only. It can miss secrets and produce false positives; it is not a complete secret scanner.
361
+ - API credentials are rejected if they contain control characters or exceed 4,096 characters before being stored or sent in provider headers. This is input hardening, not a substitute for keeping keys private.
362
+ - Large diffs are split into ordered chunks and summarized before final generation. All chunks are included; Commitron refuses diffs beyond its safe chunk limit rather than silently omitting content. Multi-chunk analysis uses multiple AI requests and may consume more quota.
363
+ - `--allow-secrets` disables the heuristic warning for diff and repository convention content in `commit` and `split`. Use it only after reviewing that content and deciding disclosure is acceptable.
364
+ - API keys can be read from environment variables or an optional OS credential manager; they are never stored in Commitron's config or profile files.
365
+ - Ollama runs locally by default, but a custom endpoint may send code elsewhere. Verify the endpoint you configure.
366
+ - `files` and `diff` list tracked changes; `commitron stage` includes untracked files in its interactive selection. The staging command selects whole files, not individual hunks.
367
+ - `history --analyze` sends recent commit metadata only after explicit confirmation. `git-help` sends the supplied error and context only after explicit confirmation. Neither command executes Git operations.
368
+ - Branch creation and switching are explicit commands. AI branch suggestions do not create branches.
369
+ - Logical commit grouping is file-level and advisory only; it cannot separate unrelated hunks inside one file and never changes the Git index.
370
+ - Repository-specific convention text in `.commitron.json` is included in AI prompts. Review it before sharing the repository or sending diffs to a provider.
371
+ - Commitron does not push, pull, reset, stash, or rewrite history.
372
+
373
+ ## Troubleshooting
374
+
375
+ - **Not a Git repository:** change into your repository directory. `commitron config show` works outside a repository.
376
+ - **No staged changes:** run `git status`, then use `commitron stage` to select intended whole files, or stage a path directly with `git add <path>`.
377
+ - **Missing API key:** set the provider's environment variable in the same terminal session.
378
+ - **Ollama connection refused:** ensure the Ollama service is running and the configured model is available.
379
+ - **API error:** check key validity, network access, model availability, provider quota, and configured base URL.
380
+
381
+ ## Development
382
+
383
+ ```bash
384
+ python -m pip install -e ".[test]"
385
+ pytest
386
+ ruff check src tests
387
+ ```
388
+
389
+ CI is configured to run the test suite on Windows, macOS, and Linux with Python 3.11, 3.12, 3.13, 3.14, and 3.15. Provider network calls are mocked/not required by the unit test suite; test a provider separately with your own key or local model.
390
+
391
+ ## License
392
+
393
+ MIT. See [LICENSE](LICENSE).