Metadata-Version: 2.4
Name: gitpr-cli
Version: 0.0.25
Summary: Automação de PRs, Commits e Code Review com IA (Gemini e DeepSeek)
Author-email: Natan Fiuza <contato@natanfiuza.dev.br>
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0.0
Requires-Dist: google-genai
Requires-Dist: openai
Requires-Dist: python-dotenv
Requires-Dist: cryptography
Requires-Dist: pyyaml
Requires-Dist: textual
Requires-Dist: requests
Dynamic: license-file

# **GitPR CLI 🚀**

GitPR CLI is a command-line automation tool that uses **Google Gemini** and **DeepSeek** artificial intelligence to analyze your code changes (git diff) or entire files. The tool automatically generates commit messages in the *Conventional Commits* standard, detailed Pull Request descriptions, and deep Code Reviews aimed at reducing technical debt.

## **🛠️ Technologies and Libraries Used**

This project was developed in Python and uses the following main libraries:

* [**Click**](https://click.palletsprojects.com/): To create a robust and user-friendly command-line interface (CLI).
* [**Google GenAI**](https://pypi.org/project/google-genai/): Official SDK for direct integration with the Gemini API.
* [**OpenAI**](https://pypi.org/project/openai/): Library used due to its full compatibility with the powerful **DeepSeek** API.
* [**Python-dotenv**](https://pypi.org/project/python-dotenv/): For secure environment variable management.
* [**Pytest**](https://docs.pytest.org/): For running unit tests in a simple, colorful, and readable way in the console.
* [**Cryptography**](https://cryptography.io/): To ensure your `GEMINI_API_KEY` is stored encrypted and securely on disk.
* [**PyYAML**](https://pyyaml.org/): Used to read and process the custom static analysis rules from the `.gitpr.linter.yml` file.
* [**Textual**](https://textual.textualize.io/): Powerful library for creating Terminal Graphical Interfaces (TUI), used in the interactive issue generation and editing panel.
* [**Requests**](https://pypi.org/project/requests/): Elegant and robust library for HTTP requests, used to communicate with the GitHub REST API.

----

## 📦 How to Compile the Executable Locally

If you want to generate your own binary from the source code, we use **PyInstaller**. Make sure you are in the project root directory with the virtual environment configured.

1. Install development dependencies (if you haven't already):
   ```bash
   pipenv install --dev
   ```

2. Run the build command pointing to our entry point (`run.py`):
   ```bash
   pipenv run pyinstaller --noconfirm --onefile --icon=icon.ico --name gitpr run.py
   ```
> **Technical note:** The `--onefile` flag ensures all Python, libraries, and dependencies are compressed into a single binary, while `--paths src` helps the compiler find our `core.py` and `config.py` files. 🛠️

After running this command, PyInstaller will create some folders (`build` and `dist`).
Your final ready-to-use file will be inside the **`dist/`** folder named `gitpr` (or `gitpr.exe` on Windows).


----

## 🧪 Running Tests

To ensure the Git capture logic and AI integration are working correctly, we use unit tests.

1. Install test dependencies (if you haven't already):
   ```bash
   pipenv install --dev pytest
   ```

2. Run the tests with the command:
   ```bash
   pipenv run pytest -v
   ```
Pytest will automatically detect files inside the `tests/` folder and display a detailed execution report.

----
## **⚙️ Installation and Configuration**

### **Using the Executable (Recommended)**

1. Download the gitpr executable file from the "Releases" tab on GitHub.
2. Move the executable to a folder that is in your PATH (e.g.: /usr/local/bin on Linux/Mac or your user folder on Windows).
3. On the first run, the wizard will guide you:
   ```bash
   $ gitpr
   ```
```bash
🚀 Intelligent PR Automation with AI

🔧 First run detected! Let's configure GitPR CLI.

🔑 Enter your GEMINI_API_KEY:

📄 Default output filename pattern [{branch}_{datetime}_PR_DESC.md]:
```
*Note: Your configuration will be securely saved in the `~/.gitpr/.env` file.*

> **🔒 Security Note:** GitPR CLI uses symmetric encryption (Fernet). Your API key is stored as a hash in the `.env` file, and the master key for decryption is automatically generated in `~/.gitpr/secret.key`. **Never share your secret.key file.**

### From Source Code

1. Clone the repository: `git clone https://github.com/natanfiuza/gitpr.git`

2. Enter the folder: `cd gitpr`

3. Set up the environment:
```bash
pipenv install google-genai openai python-dotenv click cryptography
```
4. Run: pipenv run python src/main.py

## **💻 How to Use**

GitPR has a powerful default behavior and several advanced options to assist you in your day-to-day as a developer.

### **Default Behavior (Pull Request)**
Simply run the bare command in your terminal:
```bash
gitpr
```
The tool will sync with the remote (`git fetch`), compare your changes with the remote main branch (e.g.: `origin/main`), and generate a Markdown file (e.g.: `feature-login_20260421110134_PR_DESC.md`) at the root of your project with the complete suggestion for your Pull Request.

### **Advanced Options and Commands**
You can pass the following *flags* for specific actions:

* `-c` or `--commit`: Runs a local `git diff` and displays **only the suggested commit message**.
* `-r` or `--review`: Performs a detailed **Code Review** of local changes.
* `-f` or `--fullreview`: Performs a **Full Code Review** analyzing all changes since the remote branch.
* `-i <file>` or `--input <file>`: **Full File Audit.** Must be used together with `-r` or `-f`; it ignores git history and does a Code Review of the entire file. Excellent for acting as a consultant on legacy code refactoring.
* `--provider <gemini|deepseek>`: Forces the use of a specific AI only for this execution, ignoring your default saved in `.env`.
* `-l` or `--linter`: Runs **only the local static linter** (no AI calls). Ideal for use in CI/CD pipelines to block non-compliant code.
* `-ih` or `--installhooks`: Automatically installs **local Git Hooks** (`pre-commit` and `prepare-commit-msg`) in your repository.
* `-s` or `--skill`: Creates the AI context template files (`.gitpr.commit.md`, `.gitpr.pr.md`, `.gitpr.review.md`, `.gitpr.filereview.md`, `.gitpr.issue.md`, `.gitpr.blame.md`) and the Linter (`.gitpr.linter.yml`) at the project root.
* `-is` or `--issue`: Automatically generates a draft of a **standardized Issue** and opens an interactive interface (TUI) for editing or direct submission via REST API. This feature has **3 context engines** depending on the command combination:
  * **New Code Issue (`gitpr -is`):** Reads the current `git diff`. **Why use:** Ideal for quickly documenting the task you just finished programming, before committing.
  * **Epic/Release Issue (`gitpr -is -ht`):** Reads the full history of the current branch (Git Log + PR Cache). **Why use:** Ideal for generating consolidated documentation of an entire release or a large *feature* that took several days/commits to complete.
  * **Archaeological/Technical Debt Issue (`gitpr -is -b file:lines`):** Reads the timeline of a specific business rule. **Why use:** Ideal for documenting technical debt, explaining how a legacy code block evolved and why it needs to be refactored.
* `-h` or `--help`: Shows the general help with all options. Use together with another flag for **contextual help** (e.g.: `gitpr -h --issue`, `gitpr -h --linter`) with a direct link to the detailed documentation of each feature.
* `-u` or `--update`: Checks and installs the latest version of GitPR (Auto-Updater).

> **⚙️ Technical Note (--hook):** GitPR has a hidden flag `--hook <file>` that is triggered exclusively by the Git Hooks system in the background. It allows the AI to inject the suggested message directly into Git's temporary file, without cluttering your terminal.

## 🛡️ Local Linter (Static Analysis)

GitPR CLI allows you to define strict rules that will be validated instantly during `--review` or `--fullreview`, without depending on AI. This is ideal for preventing common errors (like `console.log` or test IPs) from reaching the repository.

### How to configure `.gitpr.linter.yml`:
When running `gitpr --skill`, a template will be generated. You can configure rules using Regular Expressions (Regex):

```yaml
rules:
  - name: "check-localhost"
    extensions: ["js", "php"] # Extensions to be validated
    regex: 'http(s)?://(localhost|127\.0\.0\.1)' # What to look for
    message: "🚨 Localhost usage detected in file {file_name}"
    ignore_comments: true # Ignores if the line is commented
    ignore_paths: # Folders or files ignored (accepts *)
      - "vendor/*"
      - "node_modules/*"
```

The Linter analyzes only the **added lines** in your `git diff`, ensuring a focused and extremely fast execution. If there are violations, they will appear highlighted at the top of your review file.

## 🧠 Multi-Model Architecture (AI-Agnostic)

GitPR is not tied to a single Artificial Intelligence. During initial setup, the user can choose their default engine. We currently support:
* **Google Gemini** (Default: `gemini-2.5-flash`)
* **DeepSeek** (Default: `deepseek-chat`)

You can dynamically switch models by configuring the `GEMINI_API_MODEL` or `DEEPSEEK_API_MODEL` variables in your `~/.gitpr/.env` file, or switch in real-time using the `--provider` flag.

## 🎯 Customizable "Skills" System (Prompt Engineering)

Instead of hiding AI instructions in the source code, GitPR uses local Markdown files that act as *System Instructions*. When running `gitpr -s`, the following files are generated at the root of your project to customize the AI's "persona" according to your company's business rules:

* `.gitpr.commit.md`: Rules for generating short commit messages.
* `.gitpr.pr.md`: Required topic structure for the Pull Request description.
* `.gitpr.review.md`: Defines the architectural focus (e.g.: SOLID, Clean Code) for diff analysis.
* `.gitpr.filereview.md`: Defines strict cohesion and coupling rules for full file auditing (used with `--input`).
* `.gitpr.issue.md`: Defines the structure and level of detail required for generating standardized Issues (used with `--issue`).
* `.gitpr.blame.md`: Defines the focus of archaeological analysis for legacy code tracing (used with `--blame`).

## 🌐 Internationalization (i18n)

GitPR automatically detects your system language and displays messages in your native language. The i18n system is inspired by **Laravel's `__()` helper**:

* **Auto-detection:** On first run, GitPR detects your OS language and saves it to `~/.gitpr/.env` (`GITPR_LANG`).
* **Translation files:** Language packs are downloaded automatically from the official repository to `~/.gitpr/langs/`.
* **English fallback:** If a translation is missing, the English text is displayed directly.
* **Developer API:** Use `from src.i18n import __` and wrap all user-facing strings with `__("Your text here")`.
* **Placeholders:** Supports named parameters — `__("Downloading {file}...", file="template.md")`.

To force a specific language, set `GITPR_LANG=pt_br` or `GITPR_LANG=en` in `~/.gitpr/.env`.

> 📖 **Full developer guide:** [docs/i18n_explanation.md](docs/i18n_explanation.md) — architecture, usage patterns, circular import precautions, and how to add new languages.

## 📚 Technical Documentation and Advanced Guides

To keep this README concise, we detail the most advanced **DevOps** and **Continuous Integration** focused implementations in separate documents.

If you want to implement GitPR as an automated quality barrier in your team, check out the guides below:

* [**Local Git Hooks (Shift-Left)**](docs/git-hooks-locais.md): How to use `gitpr --installhooks` to create guardrails on the developer's machine and use AI to automatically write commit messages.
* [**Customizable Static Linter**](docs/linter-regras-customizadas.md): How to create validation rules in `.gitpr.linter.yml` for CI/CD and pre-commit hooks.
* [**Issue Generation and TUI Interface**](docs/issue-tui-help.md): How to use the terminal graphical interface (TUI) and the 3 context engines to manage structured Issues.
* [**AI Code Review**](docs/code-review-ia.md): Guide to review modes (`--review`, `--fullreview`) and file auditing (`--input`).
* [**AI Commit Messages**](docs/commit-message-ia.md): How to generate messages in the Conventional Commits standard and integrate with Git Hooks.
* [**Code Archaeologist (Git Blame)**](docs/blame-arqueologo.md): How to trace the origin of business rules with `git blame` and AI.
* [**Skills and Templates System**](docs/skill-template.md): How to customize AI behavior with `.gitpr.*.md` files.
* [**Auto-Updater**](docs/auto-update.md): How GitPR's automatic update (hot-swap) works.
* [**AI Providers**](docs/providers-ia.md): Configuration and selection between Google Gemini and DeepSeek.
* [**Pull Request (Default Mode)**](docs/pr-descricao-padrao.md): Complete flow for generating PR descriptions without flags.
* [**CI/CD Integration (GitHub Actions)**](docs/github-ci-linter.md): How to run GitPR in the pipeline to block "Merge" of PRs with violations.
* [**GitHub Token (PAT) Integration and Security**](docs/github-pat-integration.md): Understand how GitPR creates issues directly in the repository with authentication.

## ⚡ Local Cache System (Quota Savings)

GitPR has an intelligent **MD5**-based cache engine. Whenever you run a command (`--review`, `--commit`, etc.), the tool generates an exact hash of your current code (diff) and instructions.
If you run the same command again without changing the code, GitPR intercepts the request and returns the result instantly (in milliseconds) from the `~/.gitpr/cache/prompts/` folder, saving you time and your Gemini API quotas!

## 🔄 Auto-Updater (Over-The-Air Update)

Never worry about manually downloading new versions again. GitPR has a Connection Guardian and a built-in updater:
* It checks network availability before starting so it doesn't block your offline workflow.
* On each execution, it silently checks if there is a new official release on the GitHub API.
* You can force the check and installation by running `gitpr --update` or `gitpr -u`.
* The tool uses the *Hot-Swap* technique, downloading the new `.exe` and transparently replacing the old version.

## Publishing to PyPI

```bash
pipenv run python -m build
pipenv run twine upload dist/*
```
## **🤝 How to Contribute**

Contributions are very welcome! To contribute:

1. Fork the project.
2. Create a branch for your *feature* (git checkout -b feature/NewFeature).
3. Commit your changes (git commit -m 'feat: add new feature'). Tip: Use GitPR itself to generate this message! 😄
4. Push to the branch (git push origin feature/NewFeature).
5. Open a Pull Request.

## **✨ Acknowledgments and Authorship**

Project conceived and developed by:

**Natan Fiuza** - [contato@natanfiuza.dev.br](mailto:contato@natanfiuza.dev.br)

## **📄 License**

This project is licensed under the **GNU Lesser General Public License v2.1 (LGPL-2.1)**. See the LICENSE file for more details.
