ai-commit-message 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ef95bc52d9e0600b53c10e093a2d3c057e61f8746d59495f16e0f29c68699995
-  data.tar.gz: 531a062526261dd27b1927660b817509aaa0fd79490f82ca3d16883aeab4c736
+  metadata.gz: cf7ae3da6684c33dd9b0518bda5c3d0f85398132e1089a51a442bf88892e4b7d
+  data.tar.gz: d3d27482ca167d55bffb77c25ebd0553eea74fc93fdf5554bd6a434e80926aeb
 SHA512:
-  metadata.gz: e8306cabe049db41c31b8cf9568c8cb52771041e5d9c26671984de3bd9c3b16957a6de1178a5aebd6af35990faa0b634e7f888c61cbcc95aa3a4d49d6342c332
-  data.tar.gz: 6348572010d2362c88ec3e7a5bd53fa94233663b0887ab3f9201dc20803aabe11e434c9fb7ebbfa1c59ecc3afb195e18f6f8e6fbb9c035795b2675edd82c357e
+  metadata.gz: 07d58b95afcdde4e24d7f85e15354d4d437cecbb92ddfc16b68e8a8d13bf2a10a576674b43000e163b0465021947cc6c5a8210894a5583bdb00e278e7600e641
+  data.tar.gz: b22d685bb2687103cb3b414f6fc0b002dd92007b377b76ee9a89a7d99e50a052184d641277ac636d46e56780cc8265282350cd40dbb5e3515ba8418a0f8aaca1

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Afonso Neto
+
+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.

data/README.md

@@ -1,2 +1,145 @@
-# ai-commit-message
-Git commit message suggested by AI
+# AI git commit message
+
+A Ruby gem that automatically generates concise and meaningful git commit messages using a local LLM via [Ollama](https://github.com/ollama/ollama), LM Studio, llama.cpp `llama-server`, or any other OpenAI-compatible API.
+
+![Terminal demo](docs/demo.gif)
+
+## Installation
+
+Install the gem using:
+
+```bash
+gem install ai-commit-message
+```
+
+Or add it to your Gemfile:
+
+```ruby
+gem 'ai-commit-message'
+```
+
+And then run:
+
+```bash
+bundle install
+```
+
+## Requirements
+
+- Ruby 3.0 or newer
+- Git repository
+- A local LLM server: [Ollama](https://github.com/ollama/ollama), [LM Studio](https://lmstudio.ai/), [llama.cpp `llama-server`](https://github.com/ggml-org/llama.cpp), or any other OpenAI-compatible endpoint
+
+## Usage
+
+### Basic Usage
+
+Generate a commit message for your staged changes and commit with it after a confirmation:
+
+```bash
+ai-commit-message commit
+```
+
+This will:
+1. Analyze your staged changes (`git diff --cached`)
+2. Review your recent commit history for style consistency
+3. Consider your current branch name
+4. Generate an appropriate commit message
+5. Ask for confirmation and create the commit (answering "no" keeps the printed message so you can edit or copy it)
+
+### Message only
+
+If you just want the suggested message without the confirmation prompt — e.g. to pipe it somewhere or review it yourself — use `--message-only`:
+
+```bash
+ai-commit-message commit --message-only
+```
+
+### Conventional Commits
+
+Ask the model to follow the [Conventional Commits](https://www.conventionalcommits.org/) format (`feat:`, `fix:`, `chore:`, ...):
+
+```bash
+ai-commit-message commit --conventional
+```
+
+### Configuration
+
+Configure the API URL and model interactively:
+
+```bash
+ai-commit-message config
+```
+
+If your server is reachable, the model prompt becomes a picker populated with the models available on that server.
+
+List the models available on your server:
+
+```bash
+ai-commit-message models
+```
+
+### Command Line Options
+
+Override configuration settings directly:
+
+```bash
+ai-commit-message commit --url=http://your-api-endpoint --model=your-model-name
+```
+
+All options:
+
+| Option | Description | Default |
+| --- | --- | --- |
+| `--url` | Base URL of the OpenAI-compatible API | `http://localhost:11434` |
+| `--model` | Model name | `qwen3:8b` |
+| `--length` | Maximum message length in characters | `72` |
+| `--conventional` | Use Conventional Commits format | off |
+| `--message-only` | Print the message without the commit confirmation prompt | off |
+
+## How It Works
+
+The gem:
+1. Collects your staged changes using `git diff --cached` (capped at 12,000 characters so large diffs don't overwhelm a local model's context)
+2. Retrieves your recent commit history for context
+3. Identifies your current branch name
+4. Sends a chat request to `{url}/v1/chat/completions` — the standard OpenAI-compatible endpoint
+5. Cleans the model output (strips code fences, quotes and reasoning blocks) and prints a single-line commit message (limited to 72 characters by default)
+
+The URL accepts base addresses with or without a trailing `/v1` and `/`, so `http://localhost:11434` (Ollama), `http://localhost:1234/v1` (LM Studio) and `http://localhost:8080` (llama.cpp `llama-server`) all work as-is.
+
+## Configuration File
+
+The gem stores your configuration in `~/.ai-commit-message.conf`. You can manually edit this file if needed. Example:
+
+```bash
+url=http://localhost:11434
+model=qwen3:8b
+```
+
+## Models
+
+The default configuration uses Ollama with the `qwen3:8b` model, but you can use any model available through your API endpoint.
+
+### Recommended Models
+
+- **qwen3:8b**: Good balance of quality and speed (default). Note that it is a thinking model, so expect a few seconds of reasoning before the message appears
+- **qwen2.5-coder:7b**: Faster, non-thinking coding model
+- **qwen3.5:4b**: Current-generation small model for modest hardware
+- **gemma4:e4b**: Compact general-purpose option
+- **llama3.1:8b**: Solid general-purpose choice
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch: `git checkout -b my-new-feature`
+3. Install dependencies: `bundle install`
+4. Run the tests: `bundle exec rake test`
+5. Make your changes and add tests if applicable
+6. Commit your changes: `git commit -m 'Add some feature'`
+7. Push to the branch: `git push origin my-new-feature`
+8. Submit a pull request
+
+## License
+
+This gem is available as open source under the terms of the [MIT License](LICENSE).

data/lib/ai-commit-message/cli.rb

@@ -5,36 +5,95 @@ require_relative 'config_manager'
 
 module AiCommitMessage
   class CLI < Thor
-    desc "commit", "Generate git commit message"
-    method_option :url, type: :string, default: 'http://localhost:11434/api/generate'
-    method_option :model, type: :string, default: 'qwen2.5-coder:7b'
+    def self.exit_on_failure?
+      true
+    end
+
+    DEFAULT_URL = 'http://localhost:11434'
+    DEFAULT_MODEL_NAME = 'qwen3:8b'
+    MAX_DIFF_LENGTH = 12_000
 
-    def commit(options = {})
+    desc "commit", "Generate a commit message and commit with it after confirmation"
+    method_option :url, type: :string
+    method_option :model, type: :string
+    method_option :length, type: :numeric, default: Suggester::DEFAULT_LENGTH
+    method_option :conventional, type: :boolean, default: false
+    method_option :message_only, type: :boolean, default: false
+
+    def commit
       git_diff_output = `git diff --cached --no-color`
+      if git_diff_output.strip.empty?
+        warn 'Nothing is staged. Stage your changes with `git add` first.'
+        exit 1
+      end
+
       git_log_output = `git log --format=%s -n 30`
       git_current_branch = `git branch --show-current`
 
-      url = options[:url] || ConfigManager.get_url || 'http://localhost:11434/api/generate'
-      model = options[:model] || ConfigManager.get_model || 'qwen2.5-coder:7b'
-
-      suggester = AiCommitMessage::Suggester.new(git_diff_output, git_log_output, git_current_branch)
-      commit_message = suggester.generate_commit_message(url:, model:)
+      suggester = AiCommitMessage::Suggester.new(git_diff_output[0, MAX_DIFF_LENGTH], git_log_output, git_current_branch)
+      commit_message = suggester.generate_commit_message(
+        url: url_to_be_used(options[:url]),
+        model: model_to_be_used(options[:model]),
+        length: options[:length],
+        conventional: options[:conventional]
+      )
 
       puts commit_message
+      return if options[:message_only]
+
+      prompt = TTY::Prompt.new
+      begin
+        # tty-prompt takes the default on EOF, which would silently commit
+        # in non-interactive runs; treat a closed stdin as "no".
+        confirmed = !$stdin.eof? && prompt.yes?("Commit with this message?", default: true)
+      rescue TTY::Reader::InputInterrupt
+        confirmed = false
+      end
+      return unless confirmed
+
+      system('git', 'commit', '-m', commit_message)
+    rescue AiCommitMessage::Suggester::Error => e
+      warn e.message
+      exit 1
+    end
+
+    desc "models", "List models available on the configured API URL"
+    method_option :url, type: :string
+
+    def models
+      puts AiCommitMessage::Suggester.list_models(url_to_be_used(options[:url]))
+    rescue AiCommitMessage::Suggester::Error => e
+      warn e.message
+      exit 1
     end
 
     desc "config", "Set global configs. API URL and Model name"
     def config
       prompt = TTY::Prompt.new
 
-      url = prompt.ask("API URL:", default: ConfigManager.get_url || 'http://localhost:11434/api/generate')
-      model = prompt.ask("Model name:", default: ConfigManager.get_model || 'qwen2.5-coder:7b')
+      url = prompt.ask("API URL:", default: ConfigManager.get_url || DEFAULT_URL)
+      available_models = AiCommitMessage::Suggester.list_models(url) rescue nil
+      model = if available_models && !available_models.empty?
+        prompt.select("Model name:", available_models)
+      else
+        prompt.ask("Model name:", default: ConfigManager.get_model || DEFAULT_MODEL_NAME)
+      end
 
       ConfigManager.set_url(url)
       ConfigManager.set_model(model)
 
       puts "Configuration updated successfully!"
     end
+
+    private
+
+    def url_to_be_used(options_url)
+      options_url || ConfigManager.get_url || DEFAULT_URL
+    end
+
+    def model_to_be_used(options_model)
+      options_model || ConfigManager.get_model || DEFAULT_MODEL_NAME
+    end
   end
 end
 

data/lib/ai-commit-message/config_manager.rb

@@ -3,17 +3,17 @@ require 'fileutils'
 class ConfigManager
   CONFIG_FILE = File.expand_path('~/.ai-commit-message.conf')
 
-  def self.get_url = config['url']
+  def self.get_url = config[:url]
 
   def self.set_url(url)
-    config['url'] = url
+    config[:url] = url
     save_config
   end
 
-  def self.get_model = config['model']
+  def self.get_model = config[:model]
 
   def self.set_model(model)
-    config['model'] = model
+    config[:model] = model
     save_config
   end
 
@@ -34,5 +34,8 @@ class ConfigManager
     @config
   end
 
-  def self.save_config = File.write(CONFIG_FILE, config.map { |key, value| "#{key}=#{value}" }.join("\n"))
+  def self.save_config
+    File.write(CONFIG_FILE, config.map { |key, value| "#{key}=#{value}" }.join("\n"))
+    FileUtils.chmod(0600, CONFIG_FILE)
+  end
 end

data/lib/ai-commit-message/suggester.rb

@@ -1,41 +1,144 @@
 require 'net/http'
 require 'uri'
 require 'json'
+require 'openssl'
 
 module AiCommitMessage
   class Suggester
+    class Error < StandardError; end
+    class ConnectionError < Error; end
+    class ApiError < Error; end
+
+    OPEN_TIMEOUT = 5
+    READ_TIMEOUT = 120
+    DEFAULT_LENGTH = 72
+    # Thinking models (qwen3 and friends) spend tokens reasoning before the
+    # answer; the budget must leave room for both or content comes back empty.
+    MAX_TOKENS = 2048
+
+    def self.list_models(url)
+      uri = URI("#{normalized_base(url)}/v1/models")
+      http = build_http(uri)
+
+      begin
+        response = http.request(Net::HTTP::Get.new(uri))
+      rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH, SocketError
+        raise ConnectionError,
+              "Could not connect to #{uri.host}:#{uri.port}. Is your local LLM server running?"
+      end
+
+      parse_response(response).fetch('data', []).map { |m| m['id'] }.compact.sort
+    end
+
+    def self.parse_response(response)
+      unless response.is_a?(Net::HTTPSuccess)
+        raise ApiError, "API returned HTTP #{response.code}: #{response.body.to_s[0, 200]}"
+      end
+
+      JSON.parse(response.body)
+    rescue JSON::ParserError
+      raise ApiError, 'API response was not valid JSON'
+    end
+
+    def self.build_http(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == 'https'
+      http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+      http.open_timeout = OPEN_TIMEOUT
+      http.read_timeout = READ_TIMEOUT
+      http
+    end
+
+    def self.normalized_base(url)
+      url.chomp('/').sub(%r{/v1$}, '')
+    end
+
     def initialize(git_diff_output, git_log_output, git_current_branch)
       @git_diff_output = git_diff_output
       @git_log_output = git_log_output
       @git_current_branch = git_current_branch
     end
 
-    def generate_commit_message(url:, model:)
-      url = URI(url)
-      body = {
+    def generate_commit_message(url:, model:, length: DEFAULT_LENGTH, conventional: false)
+      response = post_json(chat_completions_uri(url), request_body(model, length, conventional))
+      json = self.class.parse_response(response)
+      message = clean_commit_message(json.dig('choices', 0, 'message', 'content'), length)
+      return message unless message.empty?
+
+      raise ApiError,
+            'Model returned no commit message content. Try a non-thinking model or a different model.'
+    end
+
+    private
+
+    def request_body(model, length, conventional)
+      {
         model: model,
-        prompt: "Create a concise git commit message with no more than 250 characters. Exclude anything unnecessary such as translation, backticks characters or multiple suggestions, since your entire response will be passed directly into git commit. Consider the following messages as example to follow: #{@git_log_output}.
-            The First [#XXX] option is the branch name. The current branch name is: #{@git_current_branch}. Now Do it for the following git diff: #{@git_diff_output}",
-        stream: false,
-        options: { temperature: 0.8 }
+        messages: [
+          { role: 'system', content: system_prompt(conventional) },
+          { role: 'user', content: user_prompt(length) }
+        ],
+        temperature: 0.3,
+        max_tokens: MAX_TOKENS,
+        stream: false
       }
-      json_body = body.to_json
-      headers = { 'Content-Type' => 'application/json' }
+    end
+
+    def system_prompt(conventional)
+      prompt = 'You write git commit messages. Respond with a single line containing ' \
+               'only the commit message: no quotes, no backticks, no markdown, no explanations.'
+      prompt += ' Use the Conventional Commits format (type: description).' if conventional
+      prompt
+    end
 
-      http = Net::HTTP.new(url.host, url.port)
-      request = Net::HTTP::Post.new(url)
-      request.body = json_body
-      headers.each { |key, value| request[key] = value }
-      response = http.request(request)
+    def user_prompt(length)
+      <<~PROMPT
+        Write a concise git commit message with no more than #{length} characters for the staged changes below.
+        Follow the style of these recent commit messages: #{@git_log_output}
+        #{branch_line}
+        Git diff:
+        #{@git_diff_output}
+      PROMPT
+    end
+
+    # git branch --show-current returns nothing on a detached HEAD
+    def branch_line
+      @git_current_branch.strip.empty? ? '' : "The current branch name is: #{@git_current_branch.strip}"
+    end
+    # Models tend to wrap answers in code fences or quotes, inline their
+    # reasoning in <think> blocks, or offer alternatives; reduce everything to
+    # a single clean subject line. Control characters are stripped so that a
+    # prompt-injected model cannot smuggle terminal escapes into git history.
+    def clean_commit_message(raw, length)
+      line = raw.to_s
+        .gsub(%r{<think>.*?</think>}m, '')
+        .gsub(/\e\][^\x07\e]*(?:\x07|\e\\)/, '')
+        .gsub(/\e\[[0-9;:]*[A-Za-z]/, '')
+        .gsub(/[\e\a\b\v\f\r]/, '')
+        .gsub('`', '')
+        .each_line.map(&:strip).reject(&:empty?).first.to_s
+      line = line.sub(/\A["'](.*)["']\z/, '\1')
+      line.gsub(/\s+/, ' ')[0, length].to_s.strip
+    end
+
+    # Accepts base URLs with or without a trailing /v1 and with or without a
+    # trailing slash, e.g. http://localhost:11434, http://localhost:1234/v1/
+    def chat_completions_uri(url)
+      URI("#{self.class.normalized_base(url)}/v1/chat/completions")
+    end
+
+    def post_json(uri, body)
+      http = self.class.build_http(uri)
+      request = Net::HTTP::Post.new(uri)
+      request['Content-Type'] = 'application/json'
+      request.body = body.to_json
 
       begin
-        json = JSON.parse(response.body)
-        return json['response'] if json
-      rescue JSON::ParserError => e
-        puts "Failed to parse API response as JSON: #{e.message}"
+        http.request(request)
+      rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH, SocketError => e
+        raise ConnectionError,
+              "Could not connect to #{uri.host}:#{uri.port}. Is your local LLM server running?"
       end
-
-      nil
     end
   end
-end
+end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ai-commit-message
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Afonso Neto
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2025-03-16 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -39,13 +38,13 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: net-http
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-  type: :runtime
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
@@ -53,20 +52,21 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: json
+  name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-  type: :runtime
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Git commit messages suggested by AI
+description: Git commit messages suggested by AI using a local LLM via any OpenAI-compatible
+  API
 email:
 - afonso.pontesneto@gmail.com
 executables:
@@ -74,6 +74,7 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE
 - README.md
 - bin/ai-commit-message
 - lib/ai-commit-message/cli.rb
@@ -81,9 +82,9 @@ files:
 - lib/ai-commit-message/suggester.rb
 homepage: https://github.com/AfonsoNeto/ai-commit-message
 licenses:
-- 
-metadata: {}
-post_install_message: 
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -98,8 +99,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
-signing_key: 
+rubygems_version: 4.0.12
 specification_version: 4
 summary: Git commit messages suggested by AI
 test_files: []