@rafaeelricco/commit-tools 0.1.2 → 0.1.4

package/README.md

@@ -1,110 +1,169 @@
 # commit-tools
 
-[![Version](https://img.shields.io/badge/version-0.1.0-blue.svg)](#)
-[![Built with Bun](https://img.shields.io/badge/Bun-%23000000.svg?logo=bun&logoColor=white)](#)
+[![Version](https://img.shields.io/badge/version-0.1.2-blue.svg)](#)
 
-![commit-tools Screenshot](./docs/assets/screenshot.png)
+Writing good commit messages _can_ have a high cognitive cost, especially when you make dozens of commits a day. That energy should be directed toward solving hard problems and shipping features, not summarizing them.
 
-commit-tools is an open-source AI assistant that brings the power of Gemini directly
-into your terminal to generate high-quality git commit messages. It provides
-lightweight access to Gemini, giving you the most direct path from your staged
-changes to a meaningful, well-formatted commit message.
+Because of this exhaustion, most commits end up lacking context or good names. This makes it incredibly painful to find out _why_ a change was made months later if you don't have a perfect memory.
 
-## Why commit-tools?
+While built-in IDE tools (like Cursor, VSCode, or Windsurf) offer basic AI commit generation, they are often inconsistent, lack deep customization, and lock you into their ecosystem.
 
-- **Interactive Refinement**: Generate, review, adjust, or regenerate commit messages interactively before committing.
-- **Flexible Conventions**: Choose between conventional commits (`feat:`, `fix:`), imperative style (`add`, `fix`), or create your own custom template.
-- **Multiple Authentication Options**: Sign in with your Google account via OAuth, or use a Gemini API key.
-- **Built-in System Checks**: Easily verify your installation, environment, and authentication token validity using the `doctor` command.
-- **Terminal-first**: Designed for developers who live in the command line and prefer rapid, keyboard-driven workflows.
+**commit-tools** is different. We built the only commit assistant that truly understands your workflow needs:
 
-## Installation
+- **Maximum control**: Fine-tune your commits. Demand detailed descriptions, specific formatting, or keep it perfectly brief.
+- **Provider freedom**: Bring your own API keys or use your existing subscriptions. We support exactly the LLM you want to use.
+- **Universal access**: Works seamlessly anywhere you use the terminal, regardless of what IDE you happen to be in.
+- **Crystal-clear history**: Never lose context again. A readable, well-documented commit tree makes it effortless to track down past decisions.
 
-### Install globally with bun
+## Quick Install
+
+**Prerequisites:** commit-tools requires the [Bun](https://bun.sh) runtime.
 
 ```bash
-# From the project directory
-bun link
+curl -fsSL https://bun.sh/install | bash
 ```
 
-## Authentication Options
+```bash
+bun install -g @rafaeelricco/commit-tools
+# or
+npm install -g @rafaeelricco/commit-tools
+```
 
-Choose the authentication method that best fits your needs:
+## Commit Convention Examples
 
-### Option 1: Login with Google (OAuth)
+**Conventional Commits**
 
-**Best for:** Individual developers.
+```
+feat: add model command for selecting AI model
+```
 
-**Benefits:**
+```
+refactor(config): decouple storage and auth logic
 
-- Free tier execution relying on Gemini APIs.
-- No API key management - just sign in with your Google account.
-- Automatic token refresh handled by the tool.
+- Separate authentication credentials from configuration storage.
+- Introduce `AuthCredentials` type to replace raw API key passing.
+- Update `loadConfig` and setup flow to accept a `Dependencies` object.
+```
 
-Run the tool and choose _Google OAuth (recommended)_ when prompted during setup:
+**Imperative Style**
 
-```bash
-commit-tools setup
+```
+Add fuzzy search to model selector
 ```
 
-### Option 2: Gemini API Key
+```
+Refactor commit flow into a class structure
 
-**Best for:** Developers who prefer API keys or have specific limits.
+- Extract `CommitFlow` class with dedicated methods for each step.
+- Move loading spinner logic to a separate module.
+- Update `interactionLoop` to use structured context.
+```
 
-Run the setup and choose _API Key_, then paste your Gemini API key from Google AI Studio:
+**Custom Template**
+
+Define your own format during `commit setup` to match your team's guidelines:
+
+_Template:_
+
+```
+[JIRA-<ticket_number>] <gitmoji> <type>(<scope>): <subject>
+
+<optional body>
+
+Co-authored-by: <team_name>
+```
+
+_Output:_
 
-```bash
-commit-tools setup
+```
+[JIRA-402] ✨ feat(ui): add model selection command
+
+- Implemented fuzzy search for easier discovery.
+- Added a fallback when no models are available.
+
+Co-authored-by: frontend-team
 ```
 
 ## Getting Started
 
-### Initial Setup
+### 1. Setup
 
-Configure your preferred authentication and commit convention:
+Configure your provider, authentication method, and commit convention:
 
 ```bash
-commit-tools setup
+commit setup
 ```
 
-### Basic Usage
+You will be prompted to choose:
+
+- **Auth method**: OAuth (sign in with your account) or BYOK (paste your own API key)
+- **Commit convention**: Conventional, Imperative, or Custom
 
-Stage your changes in your git repository:
+To re-authenticate at any time:
 
 ```bash
-git add <files>
+commit login
 ```
 
-Generate a commit message based on your staged changes:
+### 2. Select a Model
+
+After setup, you can switch AI models from your configured provider at any time:
 
 ```bash
-commit-tools generate
+commit model
 ```
 
-Or simply use the default command:
+### 3. Generate a Commit
+
+Stage your changes, then run:
 
 ```bash
-commit-tools
+git add <files> # soon: we will be able to add files using the tool
+commit
+```
+
+Or explicitly:
+
+```bash
+commit generate
 ```
 
 ### System Checks
 
-Check your installation, environment, and configuration status:
+Verify your installation, environment, and configuration:
 
 ```bash
-commit-tools doctor
+commit doctor
 ```
 
-## Contributing
+## Commands
+
+To see all available commands at any time, run:
 
-We welcome contributions! Feel free to report bugs, suggest features, or submit pull requests to help improve the tool.
+```bash
+commit --help
+```
 
-## Legal
+| Command                  | Description                              |
+| ------------------------ | ---------------------------------------- |
+| `commit`                 | Generate a commit message (default)      |
+| `commit generate`        | Generate a commit message                |
+| `commit setup`           | Configure authentication and conventions |
+| `commit login`           | Alias for setup — re-authenticate        |
+| `commit doctor`          | Check installation and environment       |
+| `commit model`           | Select a different AI model              |
+| `commit --version`, `-v` | Show version                             |
+| `commit --help`, `-h`    | Show help                                |
 
-- **License**: Open Source.
+## Providers
 
----
+Currently powered by **Google Gemini**. More providers are coming soon:
+
+- **OpenAI** (GPT-4o, o1, o3, etc.)
+- **Anthropic** (Claude)
+
+Contributions and feedback are welcome!
+
+## Contributing
 
-<p align="center">
-  Built by the open source community
-</p>
+We welcome contributions! Feel free to report bugs, suggest features, or submit pull requests.