ai_git 0.2.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc3e320bc55f08d7665a8a6ae9123b6b032a4b4a3861cf439b5ff018f14b415a
-  data.tar.gz: 055a7bd2bc06b4d0e18aacb318a6aa6725e1632f0bb1b5c4c3ad2ca5930013ab
+  metadata.gz: 2fb023f0a7a794ab912a9502ce5155883ecad2171832690124534e4ded1ce551
+  data.tar.gz: bb16265d754dffabf9718b410d38d8f71e00cfc249e2a97ed41cc82cfefcca2c
 SHA512:
-  metadata.gz: d90a349b399361d0c52fcaec15fec584bb4251197a8a282a7632b5e1078ec571753f8085c6edddf51edffd0f3d6c10ef24b7922afdd6c69df700b564f1f446e1
-  data.tar.gz: 603b003ec1cefdae26db68cc026ac1d2950ebd00421e9e1c0fe56c663dc8ae202458a8334bfeef1cd6f1e8cfc9a1d29893578e3e1c34c41b239c8245a11dc744
+  metadata.gz: beb8cf739a17dc85da3e07bcd75dca5108e30f1aaef7249ac663435322440b0b4ada1768607e97faf15aab35cc629a01b58bacaddd491a3e71171838258ce1a0
+  data.tar.gz: 8a9e339b686103ecc350e3844f594f1b0bf0e7297e8305da1754399cfa71955c56eca197742781847213f71beb9b74e333276ca32c39b2edf81a1d5247d24155

data/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Kaíque Kandy Koga
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,8 @@
+# AI Git
+
+AI-powered Git commit messages using a local LLM
+
+## Documentation
+
+- [Usage](doc/USAGE.md) — requirements, install, configuration, flags, and privacy
+- [Release](doc/RELEASE.md) — how a version is tagged and published to RubyGems

data/bin/ai_git

@@ -1,6 +1,25 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
+# bin/ai_git
+#
+# @purpose      Executable entry point for the ai_git CLI: load the library and
+#               hand ARGV to AIGit.start.
+# @exports      ai_git: the `config` subcommand and the -n/--dry-run, --no-push,
+#               -y/--yes, -f/--force, -h/--help, -v/--version flags.
+# @dependencies lib/ai_git: supplies AIGit.start and AIGit::UI.error.
+# @sideEffects  Runs the whole CLI; exits 130 on interrupt and 1 on any other
+#               error, after printing the message to stderr.
+# @notes        Catches StandardError only, so the string messages the library
+#               raises surface as one clean line instead of a backtrace.
 
 require_relative "../lib/ai_git"
 
-AIGit.start(ARGV)
+begin
+  AIGit.start(ARGV)
+rescue Interrupt
+  warn "\nAborted."
+  exit 130
+rescue StandardError => e
+  AIGit::UI.error("ai_git: #{e.message}")
+  exit 1
+end

data/doc/RELEASE.md

@@ -0,0 +1,77 @@
+# Release
+
+`ai_git` is published to [RubyGems](https://rubygems.org/gems/ai_git) by
+`.github/workflows/release.yml`, which runs on every push to `master` that
+touches `lib/ai_git/version.rb`. The workflow authenticates with
+[trusted publishing](https://guides.rubygems.org/trusted-publishing/): GitHub
+mints a short-lived OIDC token, RubyGems exchanges it for a single-use API key
+scoped to this gem. No API key is stored in the repository, and the push
+satisfies the `rubygems_mfa_required` flag set in `ai_git.gemspec` without an
+interactive MFA prompt.
+
+## One-time setup
+
+1. **RubyGems** — profile → the `ai_git` gem → *Trusted publishers* → *Create*:
+
+   | Field | Value |
+   |-------|-------|
+   | Repository owner | `kaiquekandykoga` |
+   | Repository name | `ai_git` |
+   | Workflow filename | `release.yml` |
+   | Environment | `release` |
+
+2. **GitHub** — Settings → Environments → `release`. It is created on the first
+   workflow run; add required reviewers there to gate each publish behind a
+   manual approval.
+
+The values must match the workflow exactly. Renaming the workflow file or the
+environment invalidates the publisher and the push is rejected.
+
+## Cutting a release
+
+1. Bump `AIGit::VERSION` in `lib/ai_git/version.rb`.
+2. Commit the bump and push it to `master`.
+
+That is the whole procedure. The push starts the workflow, which tags and
+publishes on its own — there is no tag to create by hand.
+
+## What the workflow does
+
+1. Checks out `master` with its full history and tags, on Ruby 4.0.
+2. Reads `AIGit::VERSION` and looks for the matching `v<version>` tag. If the
+   tag already exists the version was not bumped — the change to `version.rb`
+   was a comment or a header edit — and every later step is skipped, so the
+   run is a no-op rather than a failure.
+3. Installs the bundle, then runs `rake test` and `rubocop`. A failure here
+   stops the run before anything is tagged or published.
+4. Creates the annotated `v<version>` tag and pushes it.
+5. Runs `rubygems/release-gem@v1`, which configures the OIDC credentials, runs
+   `bundle exec rake release` (build, `guard_clean`, `gem push`), attaches a
+   sigstore attestation, and waits for the version to appear on RubyGems. The
+   tag from step 4 already exists, so the release task skips tagging and goes
+   straight to the gem push.
+
+A failure before step 5 publishes nothing. If the run fails after the tag is
+pushed, delete the tag (`git push origin :refs/tags/v1.0.0`) and re-run the
+workflow from the Actions tab — `workflow_dispatch` is enabled for exactly
+that case.
+
+## Verifying
+
+The gem is live when the version shows up on
+[rubygems.org/gems/ai_git/versions](https://rubygems.org/gems/ai_git/versions),
+which the last step of the workflow waits for. Locally:
+
+```bash
+gem list -r ai_git --all
+```
+
+## Publishing by hand
+
+Only needed if the workflow is unavailable. This is the path that prompts for
+MFA:
+
+```bash
+gem build ai_git.gemspec
+gem push ai_git-1.0.0.gem
+```

data/doc/USAGE.md

@@ -0,0 +1,107 @@
+# Usage
+
+## Requirements
+
+- [llama.cpp](https://github.com/ggml-org/llama.cpp) running locally (e.g. `./llama-server --port 8080`)
+
+## Install
+
+```bash
+gem install ai_git
+```
+
+## Configuration
+
+Settings live in a YAML file at `~/.ai_git/config.yml` (`config.yaml` is read
+too). The file is optional — without it every setting falls back to its
+default.
+
+```yaml
+# ~/.ai_git/config.yml
+model_name: ggml-org/gemma-4-E4B-it-GGUF:Q8_0
+base_url: http://127.0.0.1:8080
+no_color: false
+```
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| `model_name` | Model name | `ggml-org/gemma-4-E4B-it-GGUF:Q8_0` |
+| `base_url` | Base URL of the llama.cpp server | `http://127.0.0.1:8080` |
+| `no_color` | Disable colored terminal output | `false` |
+
+An unknown key or a malformed value fails the run with an error naming the
+file, so a typo never silently leaves the default in place.
+
+Run `ai_git config` to see exactly which model, URL and endpoint are resolved,
+and which file they came from.
+
+ai_git talks to a local [llama.cpp](https://github.com/ggml-org/llama.cpp) server over its OpenAI-compatible
+`/v1/chat/completions` endpoint. No API key is needed.
+
+### Example
+
+```bash
+# Start llama.cpp's server, then run ai_git with defaults
+./llama-server --port 8080
+ai_git
+
+# Or point at a custom model/port
+mkdir -p ~/.ai_git
+cat > ~/.ai_git/config.yml <<'YAML'
+model_name: my-model
+base_url: http://127.0.0.1:8081
+YAML
+```
+
+## Run
+
+```bash
+git add <files>
+ai_git
+```
+
+`ai_git` generates a commit message from your staged changes, then asks what to
+do with it:
+
+```
+Commit this message? [A]ccept / [e]dit / [r]egenerate / [q]uit:
+```
+
+Accepting commits and pushes to `origin`. The prompt only appears on a
+terminal — piped or scripted runs stay unattended, as does `--yes`.
+
+## Flags
+
+| Flag | Description |
+|------|-------------|
+| `-n`, `--dry-run` | Print the generated message and change nothing |
+| `--no-push` | Commit locally without pushing |
+| `-y`, `--yes` | Skip the confirmation prompt (unattended) |
+| `-f`, `--force` | Proceed despite secret or remote-server warnings |
+
+```bash
+ai_git --dry-run     # see what it would write, commit nothing
+ai_git --no-push     # commit locally, publish later yourself
+```
+
+## Privacy
+
+The **full staged diff is sent to the configured `base_url`** as part of the
+prompt. The default is your own machine (`http://127.0.0.1:8080`), and nothing
+leaves it. Point `base_url` at another host and ai_git warns before every run;
+plain `http://` to a non-loopback host is refused outright unless you pass
+`--force`.
+
+Before generating, ai_git also checks the staged change for credentials —
+`.env` files, private keys, AWS/GitHub/Slack-shaped tokens — and refuses to
+send them without `--force`. It is a guard, not a guarantee: review what you
+stage.
+
+## Subcommands
+
+| Subcommand | Description |
+|------------|-------------|
+| `ai_git` | Generate a commit message, commit, and push staged files |
+| `ai_git config` | Show the resolved provider configuration |
+| `ai_git --help` | Show usage |
+| `ai_git --version` | Print version |

data/lib/ai_git/ai_client.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+# lib/ai_git/ai_client.rb
+#
+# @purpose      Talk to the OpenAI-compatible chat endpoint: post the prompt,
+#               retry transient failures, and strip the model's wrapping from
+#               the reply.
+# @exports      AIGit::AIClient: READ_TIMEOUT_SECONDS, OPEN_TIMEOUT_SECONDS,
+#               MAX_ATTEMPTS, RETRY_BASE_DELAY, TRANSIENT_STATUSES,
+#               RETRYABLE_ERRORS, .complete, .sanitize.
+# @dependencies ai_git/config: supplies the base URL, endpoint, and provider
+#               name used in requests and error messages;
+#               json: encodes the request body and parses the response;
+#               net/http, uri: perform the HTTP POST.
+# @sideEffects  Makes network requests to the configured base URL; sleeps
+#               between retries; raises a string message on failure.
+# @notes        Retries with exponential backoff on the listed connection
+#               errors and status codes only; any other status raises at once.
+#               Sanitizing also unescapes a reply whose only newlines are
+#               literal backslash-n, which some models emit.
+
+require "json"
+require "net/http"
+require "uri"
+
+require_relative "config"
+
+module AIGit
+  module AIClient
+    module_function
+
+    READ_TIMEOUT_SECONDS = 120
+    OPEN_TIMEOUT_SECONDS = 10
+
+    MAX_ATTEMPTS      = 3
+    RETRY_BASE_DELAY  = 0.5
+    TRANSIENT_STATUSES = [408, 425, 429, 500, 502, 503, 504].freeze
+    RETRYABLE_ERRORS = [
+      Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EPIPE,
+      Net::OpenTimeout, Net::ReadTimeout, SocketError, EOFError
+    ].freeze
+
+    PREAMBLE_PREFIXES = /\A(here|output|generated|based\son|the\schanges|
+                          the\s(commit\smessage|review)\sis|json|markdown)\b/ix.freeze
+    CODE_FENCE = /\A`{3,}/.freeze
+    ESCAPED_MESSAGE = /\A[^\n]*\\n\\n[^\n]*\z/.freeze
+
+    def complete(prompt:, model_name:, temperature:)
+      sanitize(openai_complete(prompt, model_name, temperature))
+    end
+
+    def openai_complete(prompt, model_name, temperature)
+      body = {
+        model: model_name,
+        messages: [{ role: "user", content: prompt }],
+        stream: false,
+        temperature: temperature
+      }
+
+      data = post_json(body)
+      data.dig("choices", 0, "message", "content").to_s
+    end
+
+    def transient_status?(code)
+      TRANSIENT_STATUSES.include?(code.to_i)
+    end
+
+    def retry_delay(attempt)
+      RETRY_BASE_DELAY * (2**(attempt - 1))
+    end
+
+    def post_json(body)
+      uri = URI("#{AIGit::Config.base_url}#{AIGit::Config.endpoint}")
+      attempt = 0
+
+      loop do
+        attempt += 1
+
+        begin
+          response = perform_request(uri, body)
+        rescue *RETRYABLE_ERRORS => e
+          raise connection_error_message(e) if attempt >= MAX_ATTEMPTS
+
+          sleep retry_delay(attempt)
+          next
+        end
+
+        return JSON.parse(response.body) if response.is_a?(Net::HTTPSuccess)
+
+        if transient_status?(response.code) && attempt < MAX_ATTEMPTS
+          sleep retry_delay(attempt)
+          next
+        end
+
+        raise http_error_message(uri, response)
+      end
+    end
+
+    def perform_request(uri, body)
+      request = Net::HTTP::Post.new(uri)
+      request["Content-Type"] = "application/json"
+      request.body = body.to_json
+
+      Net::HTTP.start(
+        uri.host,
+        uri.port,
+        use_ssl: uri.scheme == "https",
+        open_timeout: OPEN_TIMEOUT_SECONDS,
+        read_timeout: READ_TIMEOUT_SECONDS
+      ) { |http| http.request(request) }
+    end
+
+    def http_error_message(uri, response)
+      provider = AIGit::Config.provider
+      body = response.body.to_s.strip
+      body = "#{body[0, 500]}…" if body.length > 500
+
+      hint = response.code.to_i == 404 ? " Check the model name and base URL (see `ai_git config`)." : ""
+
+      "#{provider} returned HTTP #{response.code} at #{uri}.#{hint}" \
+        "#{body.empty? ? '' : "\n#{body}"}"
+    end
+
+    def connection_error_message(error)
+      provider = AIGit::Config.provider
+      base_url = AIGit::Config.base_url
+      hint = "Is the local server running? See `ai_git config`."
+
+      "Cannot reach #{provider} at #{base_url} after #{MAX_ATTEMPTS} attempts: #{error.message}. #{hint}"
+    end
+
+    def sanitize(text)
+      lines = unescape_newlines(text.to_s)
+              .lines
+              .map { |line| line.rstrip.sub(/\A>\s*/, "") }
+
+      strip_preamble(strip_code_fences(lines)).join("\n").strip
+    end
+
+    def unescape_newlines(text)
+      return text unless text.match?(ESCAPED_MESSAGE)
+
+      text.gsub(/\\n/, "\n")
+    end
+
+    def strip_code_fences(lines)
+      lines = lines.drop_while { |line| line.strip.empty? }
+
+      if lines.first&.match?(CODE_FENCE)
+        unfenced = lines.first.sub(CODE_FENCE, "").strip
+        unfenced.empty? ? lines.shift : lines[0] = unfenced
+      end
+
+      lines.pop while lines.last && (lines.last.strip.empty? || lines.last.strip.match?(CODE_FENCE))
+      lines
+    end
+
+    def strip_preamble(lines)
+      lines.drop_while { |line| line.strip.empty? || preamble?(line) }
+    end
+
+    def preamble?(line)
+      line.strip.match?(PREAMBLE_PREFIXES)
+    end
+  end
+end

data/lib/ai_git/commands/config.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+# lib/ai_git/commands/config.rb
+#
+# @purpose      Implement the `config` subcommand: print the resolved provider
+#               settings and the file they come from, so the user can see what
+#               the tool will talk to.
+# @exports      AIGit::Commands::Config: .call, .resolved_rows, .config_file.
+# @dependencies ai_git/config: supplies every value printed and the path of
+#               the config file;
+#               ai_git/ai_client: supplies the read timeout shown;
+#               ai_git/ui: formats the heading and the key/value lines.
+# @sideEffects  Writes the resolved configuration to stdout; raises a string
+#               when the config file cannot be resolved.
+# @notes        Every value is resolved before the first line is printed, so a
+#               broken config file reports its error instead of a half-printed
+#               listing.
+
+require_relative "../ai_client"
+require_relative "../config"
+require_relative "../ui"
+
+module AIGit
+  module Commands
+    module Config
+      module_function
+
+      def call(_argv = [])
+        rows = resolved_rows(AIGit::Config)
+
+        AIGit::UI.heading("ai_git configuration")
+        rows.each { |key, value| AIGit::UI.kv(key, value) }
+      end
+
+      def resolved_rows(cfg)
+        [
+          ["Provider", cfg.provider],
+          ["Model", cfg.model_name],
+          ["Base URL", cfg.base_url],
+          ["Endpoint", cfg.endpoint],
+          ["Read timeout", "#{AIGit::AIClient::READ_TIMEOUT_SECONDS}s"],
+          ["Config file", config_file(cfg)]
+        ]
+      end
+
+      def config_file(cfg)
+        return cfg.config_path if cfg.config_path
+
+        dir = cfg.config_dir
+        return "(no home directory)" if dir.nil?
+
+        "#{File.join(dir, AIGit::Config::CONFIG_FILENAMES.first)} (not found)"
+      end
+    end
+  end
+end