ai_git 1.0.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2fb023f0a7a794ab912a9502ce5155883ecad2171832690124534e4ded1ce551
-  data.tar.gz: bb16265d754dffabf9718b410d38d8f71e00cfc249e2a97ed41cc82cfefcca2c
+  metadata.gz: 31071defb6673e900e4ff0701b7299dec4d17a3eb0cdf6674c4c115a70bfa242
+  data.tar.gz: f0e0c388832e033b9b09fdc77bac62a14a8984491c3b8074eda84c221de1af7d
 SHA512:
-  metadata.gz: beb8cf739a17dc85da3e07bcd75dca5108e30f1aaef7249ac663435322440b0b4ada1768607e97faf15aab35cc629a01b58bacaddd491a3e71171838258ce1a0
-  data.tar.gz: 8a9e339b686103ecc350e3844f594f1b0bf0e7297e8305da1754399cfa71955c56eca197742781847213f71beb9b74e333276ca32c39b2edf81a1d5247d24155
+  metadata.gz: b585195bd070425d3530f455ffe1d73f05e6352af264ce5342e27890afca8e30004d8ac8328da5440a3d3fe83bbc7633aa7cf8527267930ab254a91e0b3db4f9
+  data.tar.gz: dd56c54bfd0512f03bd30eadb5533c4d63644e2c5701bf415b14a27b863c1ecbf6cddc898249872c49cba95bcc4c70a25609b870f7f95b312503d40a16b2a7e6

data/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog
+
+All notable changes to `ai_git` are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [2.0.0] - 2026-09-11
+
+### Added
+
+- `ai_git help [subcommand]` documents every subcommand and flag.
+- Dependabot watches Bundler and GitHub Actions weekly.
+- `CHANGELOG.md`, `.ruby-version`, `spec.email`, `required_ruby_version`, and
+  the `homepage_uri` / `documentation_uri` / `changelog_uri` gem metadata.
+
+### Changed
+
+- **Breaking:** every action is now named. `ai_git commit` is the only path
+  that writes, and a bare `ai_git` does nothing; scripts that relied on the
+  implicit commit must call `ai_git commit`.
+- `required_ruby_version` is `>= 3.1`, and CI runs the suite on 3.1, 3.2, 3.3,
+  3.4 and 4.0 across Ubuntu and macOS.
+- Command handling moved into dedicated `AIGit::Commands` modules.
+- `.gitignore` replaced the inherited C/CMake rules with Ruby ones.
+- `Gemfile.lock` is no longer tracked; the gem resolves fresh on every install.
+
+### Fixed
+
+- Real commit titles and non-UTF-8 diffs are no longer dropped.
+- The stricter RuboCop configuration and the offenses it surfaced.
+
+## [1.0.1] - 2026-08-29
+
+### Added
+
+- `~/.ai_git/config.yml` holds `model_name`, `base_url`, and `no_color`.
+- Release automation: pushing a `lib/ai_git/version.rb` bump to `master` tags
+  the release and publishes to RubyGems via trusted publishing (OIDC).
+- `doc/USAGE.md` and file headers across the source tree.
+
+### Changed
+
+- Configuration moved from environment variables to the YAML config file.
+
+### Removed
+
+- The `NO_COLOR` environment variable, superseded by the config file.
+
+## 1.0.0 - 2026-08-29
+
+### Added
+
+- Brakes on the write path: a confirmation prompt plus `--dry-run`,
+  `--no-push`, `--yes`, and `--force`.
+- Staged-secret scanning that blocks the run when a `.env`, private key, or
+  token-shaped string is staged.
+
+### Fixed
+
+- Correctness bugs in git reads, which are now checked, and in empty model
+  responses, which now fail loudly.
+
+Releases before 1.0.0 predate this changelog; see the git history for them.
+
+[Unreleased]: https://github.com/kaiquekandykoga/ai_git/compare/v2.0.0...HEAD
+[2.0.0]: https://github.com/kaiquekandykoga/ai_git/compare/v1.0.1...v2.0.0
+[1.0.1]: https://github.com/kaiquekandykoga/ai_git/releases/tag/v1.0.1

data/README.md

@@ -2,6 +2,51 @@
 
 AI-powered Git commit messages using a local LLM
 
+`ai_git` is a Ruby command-line tool that writes your commit messages for you.
+Stage your changes, run `ai_git commit`, and it reads the staged diff, asks a
+local [llama.cpp](https://github.com/ggml-org/llama.cpp) server for a commit
+message, shows it to you, and — once you accept — commits and pushes to
+`origin`.
+
+Every action is named: a bare `ai_git` does nothing, and `ai_git help` lists
+what it can do.
+
+The generated message follows the conventional shape of a good commit: a short
+imperative title under 72 characters, a blank line, then plain prose explaining
+why the change was necessary and what problem it solves, rather than restating
+the diff.
+
+## Why a local model
+
+The full staged diff goes to whatever `base_url` you configure, and the default
+is your own machine (`http://127.0.0.1:8080`), so nothing leaves it and no API
+key is needed. Point it at another host and ai_git warns before every run; plain
+`http://` to a non-loopback host is refused outright. Before generating, it also
+screens the staged change for credentials — `.env` files, private keys,
+AWS/GitHub/Slack-shaped tokens — and refuses to send them without `--force`.
+
+## Quick start
+
+```bash
+gem install ai_git
+
+./llama-server --port 8080   # any OpenAI-compatible local server
+git add <files>
+ai_git commit
+```
+
+```
+Commit this message? [A]ccept / [e]dit / [r]egenerate / [q]uit:
+```
+
+Accept it, open it in `$EDITOR`, ask for another one, or quit. The prompt only
+appears on a terminal, so piped and scripted runs stay unattended. Use
+`--dry-run` to see the message without committing, or `--no-push` to commit
+locally.
+
+Run `ai_git help` for every subcommand, or `ai_git help commit` for what one
+of them does and the flags it takes.
+
 ## Documentation
 
 - [Usage](doc/USAGE.md) — requirements, install, configuration, flags, and privacy

data/bin/ai_git

@@ -4,8 +4,8 @@
 #
 # @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.
+# @exports      ai_git: the `commit`, `config` and `help` subcommands and the
+#               -h/--help and -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.

data/doc/USAGE.md

@@ -43,7 +43,7 @@ ai_git talks to a local [llama.cpp](https://github.com/ggml-org/llama.cpp) serve
 ```bash
 # Start llama.cpp's server, then run ai_git with defaults
 ./llama-server --port 8080
-ai_git
+ai_git commit
 
 # Or point at a custom model/port
 mkdir -p ~/.ai_git
@@ -55,13 +55,16 @@ YAML
 
 ## Run
 
+Every action is named by a subcommand. A bare `ai_git` does nothing and changes
+nothing; it only points you at `ai_git help`.
+
 ```bash
 git add <files>
-ai_git
+ai_git commit
 ```
 
-`ai_git` generates a commit message from your staged changes, then asks what to
-do with it:
+`ai_git commit` 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:
@@ -72,16 +75,19 @@ terminal — piped or scripted runs stay unattended, as does `--yes`.
 
 ## Flags
 
+These belong to `ai_git commit`:
+
 | 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 |
+| `-h`, `--help` | Describe the subcommand and its flags |
 
 ```bash
-ai_git --dry-run     # see what it would write, commit nothing
-ai_git --no-push     # commit locally, publish later yourself
+ai_git commit --dry-run     # see what it would write, commit nothing
+ai_git commit --no-push     # commit locally, publish later yourself
 ```
 
 ## Privacy
@@ -101,7 +107,20 @@ stage.
 
 | Subcommand | Description |
 |------------|-------------|
-| `ai_git` | Generate a commit message, commit, and push staged files |
+| `ai_git commit` | Generate a commit message, commit, and push staged files |
 | `ai_git config` | Show the resolved provider configuration |
-| `ai_git --help` | Show usage |
+| `ai_git help` | List every subcommand and the top-level options |
+| `ai_git help <subcommand>` | Describe one subcommand and the flags it takes |
+| `ai_git --help` | Same overview as `ai_git help` |
 | `ai_git --version` | Print version |
+
+`ai_git` on its own is not one of them: with no subcommand it prints where to
+look and exits without touching the repository. Naming an unknown subcommand,
+or a flag where a subcommand belongs, prints the usage and exits `1`.
+
+Each subcommand also answers `--help` for itself:
+
+```bash
+ai_git help commit     # or: ai_git commit --help
+ai_git help config     # or: ai_git config --help
+```

data/lib/ai_git/ai_client.rb

@@ -6,7 +6,8 @@
 #               the reply.
 # @exports      AIGit::AIClient: READ_TIMEOUT_SECONDS, OPEN_TIMEOUT_SECONDS,
 #               MAX_ATTEMPTS, RETRY_BASE_DELAY, TRANSIENT_STATUSES,
-#               RETRYABLE_ERRORS, .complete, .sanitize.
+#               RETRYABLE_ERRORS, LABELLED_PREAMBLE, BARE_LANGUAGE_TAG,
+#               ANNOUNCING_PREAMBLE, .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;
@@ -16,7 +17,9 @@
 # @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.
+#               literal backslash-n, which some models emit, and only drops
+#               a leading line that is a whole preamble sentence, so a title
+#               opening with "Output" or "The changes" is left alone.
 
 require "json"
 require "net/http"
@@ -39,10 +42,20 @@ module AIGit
       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
+    # A preamble is a whole announcing sentence, never a bare leading word: an
+    # ordinary title such as "Output the resolved settings" must survive.
+    LABELLED_PREAMBLE = /\A(here|output|generated|result|response|note)\s*:/i
+    BARE_LANGUAGE_TAG = /\A(json|markdown|text|plaintext)\z/i
+    ANNOUNCING_PREAMBLE = /
+      \A(
+          (here(\s+is|'s|\s+are)?|below\s+is)\b.*\b(commit\s+message|message)\b
+        | based\s+on\s+the\s+(changes|diff|staged\s+\w+)\b.*:\s*\z
+        | the\s+(commit\s+message|review)\s+is\b
+        | (generated|suggested|proposed)\s+commit\s+message\b
+      )
+    /ix
+    CODE_FENCE = /\A`{3,}/
+    ESCAPED_MESSAGE = /\A[^\n]*\\n\\n[^\n]*\z/
 
     def complete(prompt:, model_name:, temperature:)
       sanitize(openai_complete(prompt, model_name, temperature))
@@ -117,7 +130,7 @@ module AIGit
       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}"}"
+        "#{"\n#{body}" unless body.empty?}"
     end
 
     def connection_error_message(error)
@@ -139,7 +152,7 @@ module AIGit
     def unescape_newlines(text)
       return text unless text.match?(ESCAPED_MESSAGE)
 
-      text.gsub(/\\n/, "\n")
+      text.gsub("\\n", "\n")
     end
 
     def strip_code_fences(lines)
@@ -155,11 +168,18 @@ module AIGit
     end
 
     def strip_preamble(lines)
-      lines.drop_while { |line| line.strip.empty? || preamble?(line) }
+      stripped = lines.drop_while { |line| line.strip.empty? || preamble?(line) }
+
+      # Never let the preamble rule eat the entire reply: a message that looks
+      # like nothing but preamble is more likely a title we misread.
+      stripped.any? { |line| !line.strip.empty? } ? stripped : lines
     end
 
     def preamble?(line)
-      line.strip.match?(PREAMBLE_PREFIXES)
+      text = line.strip
+      text.match?(LABELLED_PREAMBLE) ||
+        text.match?(BARE_LANGUAGE_TAG) ||
+        text.match?(ANNOUNCING_PREAMBLE)
     end
   end
 end

data/lib/ai_git/commands/{default.rb → commit.rb}

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
-# lib/ai_git/commands/default.rb
+# lib/ai_git/commands/commit.rb
 #
-# @purpose      Implement the default subcommand end to end: guard the staged
+# @purpose      Implement the `commit` subcommand end to end: guard the staged
 #               diff, generate a commit message, confirm it, then commit and
 #               push.
-# @exports      AIGit::Commands::Default: .call, .run, .generate_commit_message,
+# @exports      AIGit::Commands::Commit: .call, .run, .generate_commit_message,
 #               .normalize_message, .build_prompt.
 # @dependencies ai_git/options: parses the flags .call receives;
 #               ai_git/git: reads the staged tree, commits, and pushes;
@@ -12,6 +12,7 @@
 #               ai_git/config: supplies the model name and base-URL checks;
 #               ai_git/ai_client: generates the message;
 #               ai_git/prompt: runs the interactive confirmation and editor;
+#               ai_git/commands/help: supplies the text --help prints;
 #               ai_git/ui: prints the header, the message, and the outcome.
 # @sideEffects  Reads the repository, commits, pushes to origin, makes network
 #               requests, spawns the editor, and writes to stdout and stderr;
@@ -27,10 +28,11 @@ require_relative "../options"
 require_relative "../prompt"
 require_relative "../secrets"
 require_relative "../ui"
+require_relative "help"
 
 module AIGit
   module Commands
-    module Default
+    module Commit
       module_function
 
       def generate_commit_message(diff, model_name, temperature: 0.3)
@@ -64,7 +66,7 @@ module AIGit
 
       def call(argv = [])
         options = AIGit::Options.parse(argv)
-        return puts(AIGit::USAGE) if options.help?
+        return puts(AIGit::Commands::Help.topic("commit")) if options.help?
 
         staged = AIGit::Git.staged_files
         raise "No staged files. Use `git add` first." if staged.strip.empty?

data/lib/ai_git/commands/config.rb

@@ -8,9 +8,11 @@
 # @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/commands/help: supplies the text --help prints;
 #               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.
+# @sideEffects  Writes the resolved configuration or the help topic to stdout;
+#               raises a string on an unknown argument or 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.
@@ -18,13 +20,18 @@
 require_relative "../ai_client"
 require_relative "../config"
 require_relative "../ui"
+require_relative "help"
 
 module AIGit
   module Commands
     module Config
       module_function
 
-      def call(_argv = [])
+      def call(argv = [])
+        argument = argv.to_a.first
+        return puts(AIGit::Commands::Help.topic("config")) if AIGit::HELP_FLAGS.include?(argument)
+        raise "Unknown option: #{argument}. Run `ai_git help config` for usage." unless argument.nil?
+
         rows = resolved_rows(AIGit::Config)
 
         AIGit::UI.heading("ai_git configuration")

data/lib/ai_git/commands/help.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+# lib/ai_git/commands/help.rb
+#
+# @purpose      Implement the `help` subcommand and own every line of help
+#               text: list what ai_git can do, or describe one subcommand.
+# @exports      AIGit::Commands::Help: USAGE, NO_SUBCOMMAND, COMMIT_TOPIC,
+#               CONFIG_TOPIC, HELP_TOPIC, TOPICS, ALIASES, .call, .topic.
+# @sideEffects  Writes the usage or one topic to stdout; raises a string when
+#               the named topic is unknown.
+# @notes        The router, the bare invocation and a subcommand's own --help
+#               all read from here, so the help a user sees has one source.
+
+module AIGit
+  module Commands
+    module Help
+      module_function
+
+      USAGE = <<~USAGE
+        Usage: ai_git <subcommand> [options]
+
+        Subcommands:
+          commit    Generate a commit message, commit, and push staged files
+          config    Show the resolved provider configuration
+          help      Describe a subcommand, or list them all
+
+        Options:
+          -h, --help     Show this message
+          -v, --version  Print version
+
+        Run `ai_git help <subcommand>` for what it does and which flags it
+        takes, for example `ai_git help commit`.
+
+        Configuration (~/.ai_git/config.yml, or config.yaml):
+          model_name: ggml-org/gemma-4-E4B-it-GGUF:Q8_0   Model to prompt
+          base_url: http://127.0.0.1:8080                 llama.cpp server
+          no_color: true                                  Disable colored output
+
+        Run `ai_git config` to see the resolved settings and the file they
+        come from.
+      USAGE
+
+      NO_SUBCOMMAND = "Nothing to do: ai_git takes a subcommand. " \
+                      "Run `ai_git help` to see what it can do."
+
+      COMMIT_TOPIC = <<~TOPIC
+        Usage: ai_git commit [options]
+
+        Generate a commit message from the staged diff, then commit and push.
+
+        ai_git reads the staged files and their diff, asks the configured
+        llama.cpp server for a message, and prints what comes back: a short
+        imperative title, a blank line, then prose explaining why the change
+        was necessary rather than restating the diff.
+
+        On a terminal it then asks what to do with that message:
+
+          Commit this message? [A]ccept / [e]dit / [r]egenerate / [q]uit:
+
+        Accepting commits and pushes to origin. Piped or scripted runs skip
+        the question and commit unattended, as does --yes.
+
+        Options:
+          -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
+          -h, --help     Show this message
+
+        Before the diff leaves the machine, ai_git refuses to send it
+        unencrypted to a non-loopback host, and refuses to send likely
+        secrets — .env files, private keys, AWS/GitHub/Slack-shaped tokens.
+        Pass --force to override either refusal.
+
+        Requires staged changes: run `git add` first.
+      TOPIC
+
+      CONFIG_TOPIC = <<~TOPIC
+        Usage: ai_git config
+
+        Show the resolved provider configuration: the provider, model name,
+        base URL, endpoint and read timeout ai_git will use, and the path of
+        the file those settings came from.
+
+        Settings live in ~/.ai_git/config.yml (config.yaml is read too). The
+        file is optional — without it every setting falls back to its
+        default. An unknown key or a malformed value fails the run with an
+        error naming the file.
+
+        This subcommand takes no options and only reads: nothing is
+        committed, pushed, or sent to the model server.
+      TOPIC
+
+      HELP_TOPIC = <<~TOPIC
+        Usage: ai_git help [subcommand]
+
+        With no argument, list every subcommand, the top-level options and
+        the configuration file ai_git reads.
+
+        Name a subcommand to see what it does and which flags it takes:
+
+          ai_git help commit
+          ai_git help config
+
+        `ai_git -h` and `ai_git --help` print the same overview as a bare
+        `ai_git help`, and every subcommand accepts --help for its own.
+      TOPIC
+
+      TOPICS = {
+        "commit" => COMMIT_TOPIC,
+        "config" => CONFIG_TOPIC,
+        "help" => HELP_TOPIC
+      }.freeze
+
+      ALIASES = { "-h" => "help", "--help" => "help" }.freeze
+
+      def call(argv = [])
+        name = argv.to_a.first
+        return puts(USAGE) if name.nil?
+
+        puts(topic(name))
+      end
+
+      def topic(name)
+        key = name.to_s
+        TOPICS.fetch(ALIASES.fetch(key, key)) { raise unknown_topic_error(key) }
+      end
+
+      def unknown_topic_error(name)
+        "Unknown help topic: #{name}. Known topics: #{TOPICS.keys.join(", ")}."
+      end
+    end
+  end
+end

data/lib/ai_git/config.rb

@@ -30,7 +30,7 @@ module AIGit
     DEFAULT_MODEL = "ggml-org/gemma-4-E4B-it-GGUF:Q8_0"
     DEFAULT_BASE_URL = "http://127.0.0.1:8080"
     ENDPOINT = "/v1/chat/completions"
-    LOOPBACK_HOST = /\A(localhost|127(\.\d{1,3}){3}|::1|0:0:0:0:0:0:0:1)\z/i.freeze
+    LOOPBACK_HOST = /\A(localhost|127(\.\d{1,3}){3}|::1|0:0:0:0:0:0:0:1)\z/i
     CONFIG_DIR_NAME = ".ai_git"
     CONFIG_FILENAMES = %w[config.yml config.yaml].freeze
     SETTING_KEYS = %w[model_name base_url no_color].freeze
@@ -85,8 +85,8 @@ module AIGit
       unknown = data.keys - SETTING_KEYS
       return data if unknown.empty?
 
-      raise "Unknown setting#{'s' if unknown.length > 1} in #{path}: #{unknown.join(', ')}. " \
-            "Known settings: #{SETTING_KEYS.join(', ')}."
+      raise "Unknown setting#{"s" if unknown.length > 1} in #{path}: #{unknown.join(", ")}. " \
+            "Known settings: #{SETTING_KEYS.join(", ")}."
     end
 
     def string_setting(key, default)

data/lib/ai_git/git.rb

@@ -3,15 +3,18 @@
 #
 # @purpose      Wrap the git porcelain this tool drives: inspect the staged
 #               tree, then commit and push on the user's behalf.
-# @exports      AIGit::Git: NOT_A_REPOSITORY, MAX_ERROR_DETAIL, .repository?,
-#               .ensure_repository!, .staged_files, .diff, .current_branch,
-#               .detached_head?, .commit_with_message, .push_current_branch.
+# @exports      AIGit::Git: NOT_A_REPOSITORY, MAX_ERROR_DETAIL, REPLACEMENT,
+#               .repository?, .ensure_repository!, .staged_files, .diff,
+#               .current_branch, .detached_head?, .scrub,
+#               .commit_with_message, .push_current_branch.
 # @dependencies git: every operation shells out to the binary;
 #               open3: captures stdout, stderr, and exit status together;
 #               tempfile: holds the commit message passed to `git commit -F`.
 # @sideEffects  Spawns git subprocesses; writes a tempfile; mutates the
 #               repository and the remote on commit and push.
 # @notes        Raises a bare string message; bin/ai_git renders it and exits 1.
+#               Captured output is scrubbed to valid UTF-8 so a diff of a
+#               non-UTF-8 file cannot break JSON encoding downstream.
 
 require "open3"
 require "tempfile"
@@ -22,6 +25,7 @@ module AIGit
 
     NOT_A_REPOSITORY = "Not a git repository (or any of the parent directories)."
     MAX_ERROR_DETAIL = 500
+    REPLACEMENT = "\uFFFD"
 
     def repository?
       _stdout, _stderr, status = Open3.capture3("git", "rev-parse", "--git-dir")
@@ -57,11 +61,20 @@ module AIGit
 
     def capture(*argv)
       stdout, stderr, status = Open3.capture3(*argv)
-      return stdout if status.success?
+      return scrub(stdout) if status.success?
 
       raise command_error(argv, stderr, status)
     end
 
+    # git hands back the bytes it stored, whatever they are. A Latin-1 file
+    # makes the diff invalid UTF-8, which the JSON encoder in the HTTP client
+    # refuses; replace the offending bytes here, at the source.
+    def scrub(text)
+      string = text.to_s
+      string = string.dup.force_encoding(Encoding::UTF_8) unless string.encoding == Encoding::UTF_8
+      string.valid_encoding? ? string : string.scrub(REPLACEMENT)
+    end
+
     def run_command(cmd, *args)
       argv = [cmd, *args.map(&:to_s)]
       _stdout, stderr, status = Open3.capture3(*argv)
@@ -74,7 +87,7 @@ module AIGit
     def command_error(argv, stderr, status)
       detail = stderr.to_s.strip
       detail = "#{detail[0, MAX_ERROR_DETAIL]}…" if detail.length > MAX_ERROR_DETAIL
-      header = "Command failed: #{argv.join(' ')} (exit #{status.exitstatus})"
+      header = "Command failed: #{argv.join(" ")} (exit #{status.exitstatus})"
 
       detail.empty? ? header : "#{header}\n#{detail}"
     end

data/lib/ai_git/prompt.rb

@@ -51,7 +51,7 @@ module AIGit
     end
 
     def edit(message)
-      editor = ENV["VISUAL"] || ENV["EDITOR"]
+      editor = ENV["VISUAL"] || ENV.fetch("EDITOR", nil)
       raise "Cannot edit: set $EDITOR or $VISUAL first." if editor.to_s.strip.empty?
 
       Tempfile.create(["ai_git_commit_msg", ".txt"]) do |file|

data/lib/ai_git/secrets.rb

@@ -34,7 +34,7 @@ module AIGit
     SUSPICIOUS_ASSIGNMENT = /
       \b(api[_-]?key|secret|password|passwd|token|access[_-]?key)\b
       \s*[:=]\s*["'][^"']{8,}["']
-    /ix.freeze
+    /ix
 
     def scan(staged_files, diff)
       { blocking: blocking_findings(staged_files, diff), warnings: warning_findings(diff) }

data/lib/ai_git/ui.rb

@@ -41,7 +41,7 @@ module AIGit
       codes = styles.map { |style| CODES[style] }.compact
       return text.to_s if codes.empty?
 
-      "\e[#{codes.join(';')}m#{text}\e[0m"
+      "\e[#{codes.join(";")}m#{text}\e[0m"
     end
 
     def bold(text)

data/lib/ai_git/version.rb

@@ -7,5 +7,5 @@
 # @sideEffects  None.
 
 module AIGit
-  VERSION = "1.0.1"
+  VERSION = "2.0.0"
 end

data/lib/ai_git.rb

@@ -2,80 +2,57 @@
 # lib/ai_git.rb
 #
 # @purpose      Library entry point and CLI router: load every component, then
-#               dispatch the argument vector to the matching subcommand.
-# @exports      AIGit: SUBCOMMANDS, HELP_FLAGS, VERSION_FLAGS, USAGE, .start.
+#               dispatch the argument vector to the named subcommand.
+# @exports      AIGit: SUBCOMMANDS, HELP_FLAGS, VERSION_FLAGS, .start.
 # @dependencies ai_git/version, ai_git/config, ai_git/ui, ai_git/ai_client,
 #               ai_git/git: the components the subcommands build on;
-#               ai_git/commands/default, ai_git/commands/config: the two
-#               subcommands .start dispatches to.
-# @sideEffects  Prints usage or the version to stdout; warns and exits 1 on an
-#               unknown subcommand; .start runs the selected subcommand.
-# @notes        A first argument starting with "-" is left in place for the
-#               default command's parser, so bare flags need no subcommand.
+#               ai_git/commands/commit, ai_git/commands/config,
+#               ai_git/commands/help: the subcommands .start dispatches to.
+# @sideEffects  Prints the usage, the version or a hint to stdout; warns and
+#               exits 1 on an unknown subcommand or option; .start runs the
+#               selected subcommand.
+# @notes        Every action needs its subcommand named: an empty vector
+#               prints where to look and changes nothing, so a bare `ai_git`
+#               can no longer commit by accident.
 
 require_relative "ai_git/version"
 require_relative "ai_git/config"
 require_relative "ai_git/ui"
 require_relative "ai_git/ai_client"
 require_relative "ai_git/git"
-require_relative "ai_git/commands/default"
+require_relative "ai_git/commands/commit"
 require_relative "ai_git/commands/config"
+require_relative "ai_git/commands/help"
 
 module AIGit
   module_function
 
   SUBCOMMANDS = {
+    "commit" => AIGit::Commands::Commit,
     "config" => AIGit::Commands::Config,
-    "default" => AIGit::Commands::Default
+    "help" => AIGit::Commands::Help
   }.freeze
 
-  HELP_FLAGS    = %w[-h --help help].freeze
+  HELP_FLAGS    = %w[-h --help].freeze
   VERSION_FLAGS = %w[-v --version].freeze
 
-  USAGE = <<~USAGE
-    Usage: ai_git [subcommand] [options]
-
-    Subcommands:
-      (none)    Generate a commit message, commit, and push staged files
-      config    Show the resolved provider configuration
-
-    Options:
-      -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
-      -h, --help     Show this message
-      -v, --version  Print version
-
-    On a terminal ai_git asks before committing: accept, edit, regenerate or
-    quit. Piped or scripted runs commit and push unattended.
-
-    Configuration (~/.ai_git/config.yml, or config.yaml):
-      model_name: ggml-org/gemma-4-E4B-it-GGUF:Q8_0   Model to prompt
-      base_url: http://127.0.0.1:8080                 llama.cpp server
-      no_color: true                                  Disable colored output
-
-    Run `ai_git config` to see the resolved settings and the file they
-    come from.
-  USAGE
-
   def start(args)
     args = args.dup
     first = args.first
 
-    return puts(USAGE) if first && HELP_FLAGS.include?(first)
-    return puts(VERSION) if first && VERSION_FLAGS.include?(first)
+    return puts(AIGit::Commands::Help::NO_SUBCOMMAND) if first.nil?
+    return AIGit::Commands::Help.call([]) if HELP_FLAGS.include?(first)
+    return puts(VERSION) if VERSION_FLAGS.include?(first)
 
-    command = "default"
-    if first && !first.start_with?("-")
-      unless SUBCOMMANDS.key?(first)
-        warn "Unknown subcommand: #{first}"
-        warn USAGE
-        exit 1
-      end
-      command = args.shift
-    end
+    unknown_argument!(first) unless SUBCOMMANDS.key?(first)
+
+    SUBCOMMANDS[args.shift].call(args)
+  end
 
-    SUBCOMMANDS[command].call(args)
+  def unknown_argument!(argument)
+    label = argument.start_with?("-") ? "option" : "subcommand"
+    warn "Unknown #{label}: #{argument}"
+    warn AIGit::Commands::Help::USAGE
+    exit 1
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ai_git
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 2.0.0
 platform: ruby
 authors:
 - Kaíque Kandy Koga
@@ -11,11 +11,13 @@ date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: Generate Git commit messages from staged changes via a local llama.cpp
   server, then commit and push.
+email: kaiquekandykoga@gmail.com
 executables:
 - ai_git
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE
 - README.md
 - bin/ai_git
@@ -23,8 +25,9 @@ files:
 - doc/USAGE.md
 - lib/ai_git.rb
 - lib/ai_git/ai_client.rb
+- lib/ai_git/commands/commit.rb
 - lib/ai_git/commands/config.rb
-- lib/ai_git/commands/default.rb
+- lib/ai_git/commands/help.rb
 - lib/ai_git/config.rb
 - lib/ai_git/git.rb
 - lib/ai_git/options.rb
@@ -36,7 +39,10 @@ homepage: https://github.com/kaiquekandykoga/ai_git
 licenses:
 - BSD-3-Clause
 metadata:
-  source_code_uri: https://github.com/kaiquekandykoga/ai_git
+  homepage_uri: https://github.com/kaiquekandykoga/ai_git
+  source_code_uri: https://github.com/kaiquekandykoga/ai_git/tree/master
+  documentation_uri: https://github.com/kaiquekandykoga/ai_git/blob/master/doc/USAGE.md
+  changelog_uri: https://github.com/kaiquekandykoga/ai_git/blob/master/CHANGELOG.md
   bug_tracker_uri: https://github.com/kaiquekandykoga/ai_git/issues
   rubygems_mfa_required: 'true'
 rdoc_options: []
@@ -46,7 +52,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="