kk-git 0.2.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 74daf125db0cf895ef3d9c7c6e0315f56a70a1e5de4cfff743ed0bb281d9c73c
-  data.tar.gz: 0dda4d4d4544b1249d3b95a019ea4da0f6d9d1469b3815b21c5069ea213a2ca6
+  metadata.gz: c7ea0b721958d0136a191c3bcbf41255988c8616b73f5aecc328a99f69d9a6dd
+  data.tar.gz: 026c9446f331443575102852cf42472e318b7f8af109fe63bcefe3e766a4e178
 SHA512:
-  metadata.gz: f9b644cfda470263d0bdef6073c8adf2fa9864d24388e8af13053ce684996c2ec62f2a90d131b82eb9d5daa7c6d073d8d061571ac21c63887d0e0454fe8fdfdf
-  data.tar.gz: 59a25a6ad4c915ebe7a48f128ad501585340f9ffc3f9ecccc47bb9303729ac2286783b1ea08e1e18128e075a4d2beb5ece410d59d8435ba09cf1cfb0690578d5
+  metadata.gz: 637502a892517a38a8f9b06f7fde4bd6106c60960ddbabd0138010755d6030428b1d97bb14624bc1734f27c19de4e98a3b3c0015589155ff584792705ab41d42
+  data.tar.gz: 6103f6ba218aafd344a145477185223a18eb896f70fcd7548ed42d063e40f592fc738f49158a8e15e09f0a9e247d8969430ac0b09ac79fca36208ff481be1bf0

data/exe/kk-git

@@ -15,7 +15,17 @@ def to_utf8(str)
 
   s = str.to_s.dup
   s.force_encoding(Encoding::UTF_8)
-  s.scrub('�')
+  s.scrub("\uFFFD")
+end
+
+def parse_repo_options!(argv)
+  options = { repo_dir: '.' }
+  parser = OptionParser.new do |opts|
+    opts.on('--repo DIR', 'Git repo directory (default: current dir)') { |v| options[:repo_dir] = v }
+    opts.on('-h', '--help', 'Show help') { |v| options[:help] = v }
+  end
+  parser.parse!(argv)
+  options
 end
 
 def run_commit_message!(argv)
@@ -81,15 +91,16 @@ def run_commit_message!(argv)
 end
 
 def run_status!(argv)
-  options = { format: :text }
+  options = { format: :text, repo_dir: '.' }
   parser = OptionParser.new do |opts|
     opts.banner = 'Usage: kk-git status [options]'
+    opts.on('--repo DIR', 'Git repo directory (default: current dir)') { |v| options[:repo_dir] = v }
     opts.on('--format FORMAT', 'Output format: text/json (default: text)') { |v| options[:format] = v.to_s.downcase.to_sym }
     opts.on('-h', '--help', 'Show help') { puts opts; exit 0 }
   end
   parser.parse!(argv)
 
-  hash = KKGit::GitOps.status_hash
+  hash = KKGit::GitOps.status_hash(repo_dir: options[:repo_dir])
   if options[:format] == :json
     puts JSON.pretty_generate(hash)
   else
@@ -102,31 +113,35 @@ def run_status!(argv)
 end
 
 def run_sync!(argv)
-  parser = OptionParser.new do |opts|
-    opts.banner = 'Usage: kk-git sync [options]'
-    opts.on('-h', '--help', 'Show help') { puts opts; exit 0 }
+  options = parse_repo_options!(argv)
+  if options[:help]
+    puts 'Usage: kk-git sync [--repo DIR]'
+    exit 0
   end
-  parser.parse!(argv)
 
+  repo_dir = options[:repo_dir]
   remote = KKGit::GitOps.remote
-  branch = KKGit::GitOps.branch
-  s = KKGit::GitOps.status(remote: remote, branch: branch)
+  branch = KKGit::GitOps.branch(repo_dir: repo_dir)
+  s = KKGit::GitOps.status(remote: remote, branch: branch, repo_dir: repo_dir)
 
   if s.needs_sync?
-    KKGit::GitOps.sync_with_remote!(remote, branch)
+    KKGit::GitOps.sync_with_remote!(remote, branch, repo_dir: repo_dir)
   else
     puts 'Already in sync with remote'
   end
 end
 
 def run_push!(argv)
-  parser = OptionParser.new do |opts|
-    opts.banner = 'Usage: kk-git push [options]'
-    opts.on('-h', '--help', 'Show help') { puts opts; exit 0 }
+  options = parse_repo_options!(argv)
+  if options[:help]
+    puts 'Usage: kk-git push [--repo DIR]'
+    exit 0
   end
-  parser.parse!(argv)
 
-  KKGit::GitOps.auto_commit_push!
+  KKGit::GitOps.auto_commit_push!(repo_dir: options[:repo_dir])
+rescue KKGit::GitOps::Error => e
+  warn e.message
+  exit 1
 end
 
 def main_help
@@ -149,6 +164,11 @@ def main_help
       KK_GIT_SKIP_PULL=1  skip pull step
       KK_GIT_SKIP_PUSH=1  skip push step
       KK_GIT_AMEND=1      amend last commit instead of creating new one
+      KK_GIT_CONFIRM=1    print message and require KK_GIT_YES=1
+      KK_GIT_ALLOW_SENSITIVE=1  allow committing .env/credentials paths
+      KK_GIT_DEFAULT_TYPE  default type for code edits (default: chore)
+      KK_GIT_PUSH_URL       push to explicit URL (bypass SSH remote)
+      KK_GIT_PULL_URL       pull from explicit URL (bypass SSH remote)
 
     Run `kk-git <command> --help` for command-specific options.
   HELP

data/lib/kk/git/commit_message.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require 'json'
-require 'open3'
+require_relative 'git_runner'
 
 module KKGit
   # Generate Conventional Commits messages from git changes.
@@ -211,14 +211,7 @@ module KKGit
     end
 
     def self.run_git(args, repo_dir:)
-      stdout, stderr, status = Open3.capture3('git', *args, chdir: repo_dir)
-      # Open3 stdout/stderr may be ASCII-8BIT (BINARY). Normalize to UTF-8 to avoid concat errors.
-      stdout = stdout.to_s.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: '�')
-      stderr = stderr.to_s.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: '�')
-
-      raise "git #{args.join(' ')} failed: #{stderr.strip}" unless status.success?
-
-      stdout
+      GitRunner.capture!(args, repo_dir: repo_dir)
     end
 
     # Infer type/scope/subject (with optional breaking detection)
@@ -238,17 +231,6 @@ module KKGit
       types.min_by { |t| TYPE_PRIORITY[t] || 999 } || 'chore'
     end
 
-    def self.pick_scope(scopes, fallback_scope:)
-      uniq = scopes.compact.uniq
-      return fallback_scope if uniq.empty?
-      return uniq.first if uniq.length == 1
-
-      # When multiple scopes exist, prefer "repo"; otherwise fallback.
-      return 'repo' if uniq.include?('repo')
-
-      fallback_scope
-    end
-
     def self.infer_scope(paths, fallback_scope:)
       # Tooling/script/build changes: prefer a stable scope
       if paths.any? && paths.all? { |p| tooling_path?(p) || doc_path?(p) || ci_path?(p) }
@@ -319,10 +301,14 @@ module KKGit
       return 'chore' if config_path?(path)
       return 'chore' if script_path?(path)
 
-      return 'chore' unless code_path?(path)
+      return default_code_type unless code_path?(path)
+
+      default_code_type
+    end
 
-      # Default: treat code changes as fix (conservative). Adds are handled as feat by infer_type.
-      'fix'
+    def self.default_code_type
+      type = ENV.fetch('KK_GIT_DEFAULT_TYPE', 'chore').to_s.strip
+      TYPE_PRIORITY.key?(type) ? type : 'chore'
     end
 
     def self.doc_path?(path)

data/lib/kk/git/git_ops.rb

@@ -1,20 +1,29 @@
 # frozen_string_literal: true
 
-require 'open3'
 require 'tempfile'
+require_relative 'git_runner'
+require_relative 'network_hints'
 
 module KKGit
   # Git 仓库操作：供 Rake task 与 CLI 复用。
   module GitOps
     class Error < StandardError; end
 
+    SENSITIVE_PATH_PATTERNS = [
+      %r{\A\.env(\.|$)}i,
+      /credentials/i,
+      %r{\.pem\z}i,
+      /id_rsa/i,
+      %r{\.key\z}i,
+      %r{\Asecrets?\.}i
+    ].freeze
+
     # 仓库同步状态快照
     Status = Struct.new(
       :branch, :remote, :clean, :ahead, :behind,
       :upstream_configured, :detached,
       keyword_init: true
     ) do
-      # 是否需要与远端同步（有未推送 commit 或落后远端）
       def needs_sync?
         ahead.positive? || behind.positive?
       end
@@ -29,7 +38,6 @@ module KKGit
     end
 
     class << self
-      # @return [Boolean] KK_GIT_DRY_RUN=1 时只打印命令不执行
       def dry_run?
         ENV['KK_GIT_DRY_RUN'] == '1'
       end
@@ -50,127 +58,152 @@ module KKGit
         ENV.fetch('KK_GIT_REMOTE', 'origin')
       end
 
-      # @param explicit [String, nil] KK_GIT_BRANCH 或显式传入
-      def branch(explicit: ENV['KK_GIT_BRANCH'])
-        explicit.to_s.strip.empty? ? current_branch : explicit.to_s.strip
+      def branch(explicit: ENV['KK_GIT_BRANCH'], repo_dir: '.')
+        explicit.to_s.strip.empty? ? current_branch(repo_dir: repo_dir) : explicit.to_s.strip
       end
 
-      # git add 路径，默认 `.`；可用 KK_GIT_ADD_PATHS 指定多个路径（空格分隔）
       def add_paths
         ENV.fetch('KK_GIT_ADD_PATHS', '.').split(/\s+/).reject(&:empty?)
       end
 
-      # 会修改仓库状态的 git 子命令；dry-run 时跳过这些命令
-      MUTATING_GIT_COMMANDS = %w[add commit push pull merge rebase checkout reset cherry-pick revert].freeze
+      def pull_target(remote)
+        url = ENV['KK_GIT_PULL_URL'].to_s.strip
+        url.empty? ? remote : url
+      end
+
+      def push_target(remote)
+        url = ENV['KK_GIT_PUSH_URL'].to_s.strip
+        url.empty? ? remote : url
+      end
+
+      def remote_fetch_url(repo_dir: '.')
+        out, _err, ok = run_cmd('git', 'remote', 'get-url', remote, chdir: repo_dir)
+        ok ? out.strip : nil
+      end
+
+      def suggested_https_push_url(repo_dir: '.')
+        NetworkHints.ssh_remote_to_https(remote_fetch_url(repo_dir: repo_dir))
+      end
 
-      def run_cmd(*cmd, chdir: nil)
+      MUTATING_GIT_COMMANDS = %w[add commit push pull merge rebase checkout reset cherry-pick revert tag].freeze
+
+      def run_cmd(*cmd, chdir: '.')
         if dry_run? && mutating_git_command?(cmd)
-          label = chdir ? "(cd #{chdir} && #{cmd.join(' ')})" : cmd.join(' ')
+          label = chdir == '.' ? cmd.join(' ') : "(cd #{chdir} && #{cmd.join(' ')})"
           puts "[dry-run] #{label}"
           return ['', '', true]
         end
 
-        stdout, stderr, status =
-          if chdir
-            Open3.capture3(*cmd, chdir: chdir)
-          else
-            Open3.capture3(*cmd)
-          end
-        [stdout.to_s, stderr.to_s, status.success?]
+        if cmd[0] == 'git'
+          stdout, stderr, ok = GitRunner.capture(cmd.drop(1), repo_dir: chdir)
+        else
+          require 'open3'
+          stdout, stderr, status = Open3.capture3(*cmd, chdir: chdir == '.' ? nil : chdir)
+          ok = status.success?
+          stdout = GitRunner.normalize_utf8(stdout)
+          stderr = GitRunner.normalize_utf8(stderr)
+        end
+        [stdout.to_s, stderr.to_s, ok]
       end
 
       def mutating_git_command?(cmd)
         cmd[0] == 'git' && MUTATING_GIT_COMMANDS.include?(cmd[1])
       end
 
-      def ensure_ok!(ok, title, stdout: nil, stderr: nil)
+      def ensure_ok!(ok, title, stdout: nil, stderr: nil, repo_dir: '.')
         return if ok
 
         msg = +"#{title} failed"
         msg << "\n#{stderr}" unless stderr.to_s.strip.empty?
         msg << "\n#{stdout}" unless stdout.to_s.strip.empty?
+
+        hints = NetworkHints.for_git_failure(
+          title: title,
+          stderr: stderr.to_s,
+          stdout: stdout.to_s,
+          suggested_https_url: suggested_https_push_url(repo_dir: repo_dir)
+        )
+        msg << "\n\n#{hints.join("\n\n")}" unless hints.empty?
+
         raise Error, msg
       end
 
-      def in_git_repo?
-        _, _, ok = run_cmd('git', 'rev-parse', '--git-dir')
+      def in_git_repo?(repo_dir: '.')
+        _, _, ok = run_cmd('git', 'rev-parse', '--git-dir', chdir: repo_dir)
         ok
       end
 
-      def ensure_in_repo!
-        raise Error, 'Not a git repository' unless in_git_repo?
+      def ensure_in_repo!(repo_dir: '.')
+        raise Error, 'Not a git repository' unless in_git_repo?(repo_dir: repo_dir)
       end
 
-      def current_branch
-        out, err, ok = run_cmd('git', 'rev-parse', '--abbrev-ref', 'HEAD')
-        ensure_ok!(ok, 'Get current branch', stdout: out, stderr: err)
+      def current_branch(repo_dir: '.')
+        out, err, ok = run_cmd('git', 'rev-parse', '--abbrev-ref', 'HEAD', chdir: repo_dir)
+        ensure_ok!(ok, 'Get current branch', stdout: out, stderr: err, repo_dir: repo_dir)
         out.strip
       end
 
-      def detached_head?
-        current_branch == 'HEAD'
+      def detached_head?(repo_dir: '.')
+        current_branch(repo_dir: repo_dir) == 'HEAD'
       end
 
-      def ensure_not_detached!
-        raise Error, 'Cannot push from detached HEAD' if detached_head?
+      def ensure_not_detached!(repo_dir: '.')
+        raise Error, 'Cannot push from detached HEAD' if detached_head?(repo_dir: repo_dir)
       end
 
-      def working_tree_clean?
-        out, err, ok = run_cmd('git', 'status', '--porcelain')
-        ensure_ok!(ok, 'Check git status', stdout: out, stderr: err)
+      def working_tree_clean?(repo_dir: '.')
+        out, err, ok = run_cmd('git', 'status', '--porcelain', chdir: repo_dir)
+        ensure_ok!(ok, 'Check git status', stdout: out, stderr: err, repo_dir: repo_dir)
         out.strip.empty?
       end
 
-      def upstream_configured?
-        _, _, ok = run_cmd('git', 'rev-parse', '--abbrev-ref', '@{u}')
+      def upstream_configured?(repo_dir: '.')
+        _, _, ok = run_cmd('git', 'rev-parse', '--abbrev-ref', '@{u}', chdir: repo_dir)
         ok
       end
 
-      # 相对 upstream / remote/branch 领先的 commit 数
-      def ahead_count(remote, branch)
-        out, _err, ok = run_cmd('git', 'rev-list', '--count', '@{u}..HEAD')
+      def ahead_count(remote, branch, repo_dir: '.')
+        out, _err, ok = run_cmd('git', 'rev-list', '--count', '@{u}..HEAD', chdir: repo_dir)
         return out.strip.to_i if ok
 
-        out, _err, ok = run_cmd('git', 'rev-list', '--count', "#{remote}/#{branch}..HEAD")
+        out, _err, ok = run_cmd('git', 'rev-list', '--count', "#{remote}/#{branch}..HEAD", chdir: repo_dir)
         return out.strip.to_i if ok
 
         0
       end
 
-      # 相对 upstream / remote/branch 落后的 commit 数
-      def behind_count(remote, branch)
-        out, _err, ok = run_cmd('git', 'rev-list', '--count', 'HEAD..@{u}')
+      def behind_count(remote, branch, repo_dir: '.')
+        out, _err, ok = run_cmd('git', 'rev-list', '--count', 'HEAD..@{u}', chdir: repo_dir)
         return out.strip.to_i if ok
 
-        out, _err, ok = run_cmd('git', 'rev-list', '--count', "HEAD..#{remote}/#{branch}")
+        out, _err, ok = run_cmd('git', 'rev-list', '--count', "HEAD..#{remote}/#{branch}", chdir: repo_dir)
         return out.strip.to_i if ok
 
         0
       end
 
-      def unpushed_commits?(remote, branch)
-        ahead_count(remote, branch).positive?
+      def unpushed_commits?(remote, branch, repo_dir: '.')
+        ahead_count(remote, branch, repo_dir: repo_dir).positive?
       end
 
-      # @return [Status]
-      def status(remote: nil, branch: nil)
-        ensure_in_repo!
+      def status(remote: nil, branch: nil, repo_dir: '.')
+        ensure_in_repo!(repo_dir: repo_dir)
         remote ||= self.remote
-        branch ||= self.branch
+        branch ||= self.branch(repo_dir: repo_dir)
 
         Status.new(
           branch: branch,
           remote: remote,
-          clean: working_tree_clean?,
-          ahead: ahead_count(remote, branch),
-          behind: behind_count(remote, branch),
-          upstream_configured: upstream_configured?,
-          detached: detached_head?
+          clean: working_tree_clean?(repo_dir: repo_dir),
+          ahead: ahead_count(remote, branch, repo_dir: repo_dir),
+          behind: behind_count(remote, branch, repo_dir: repo_dir),
+          upstream_configured: upstream_configured?(repo_dir: repo_dir),
+          detached: detached_head?(repo_dir: repo_dir)
         )
       end
 
-      def status_hash(remote: nil, branch: nil)
-        s = status(remote: remote, branch: branch)
+      def status_hash(remote: nil, branch: nil, repo_dir: '.')
+        s = status(remote: remote, branch: branch, repo_dir: repo_dir)
         {
           branch: s.branch,
           remote: s.remote,
@@ -183,70 +216,101 @@ module KKGit
         }
       end
 
-      def pull_remote!(remote, branch)
+      def pull_remote!(remote, branch, repo_dir: '.')
         return if skip_pull?
 
         pull_args = ENV.fetch('KK_GIT_PULL_ARGS', '--ff-only').split
-        out, err, ok = run_cmd('git', 'pull', remote, branch, *pull_args)
-        ensure_ok!(ok, 'git pull', stdout: out, stderr: err)
+        target = pull_target(remote)
+        out, err, ok = run_cmd('git', 'pull', target, branch, *pull_args, chdir: repo_dir)
+        ensure_ok!(ok, 'git pull', stdout: out, stderr: err, repo_dir: repo_dir)
       end
 
-      def push_remote!(remote, branch)
+      def push_remote!(remote, branch, repo_dir: '.')
         return if skip_push?
 
-        ensure_not_detached! unless dry_run?
+        ensure_not_detached!(repo_dir: repo_dir) unless dry_run?
 
-        if upstream_configured?
-          out, err, ok = run_cmd('git', 'push', remote, branch)
+        target = push_target(remote)
+        if upstream_configured?(repo_dir: repo_dir)
+          out, err, ok = run_cmd('git', 'push', target, branch, chdir: repo_dir)
         else
-          out, err, ok = run_cmd('git', 'push', '-u', remote, branch)
+          out, err, ok = run_cmd('git', 'push', '-u', target, branch, chdir: repo_dir)
         end
-        ensure_ok!(ok, 'git push', stdout: out, stderr: err)
+        ensure_ok!(ok, 'git push', stdout: out, stderr: err, repo_dir: repo_dir)
       end
 
-      def sync_with_remote!(remote, branch)
-        pull_remote!(remote, branch)
-        push_remote!(remote, branch)
+      def sync_with_remote!(remote, branch, repo_dir: '.')
+        pull_remote!(remote, branch, repo_dir: repo_dir)
+        push_remote!(remote, branch, repo_dir: repo_dir)
         puts "Synced: #{remote} #{branch}" unless dry_run?
       end
 
-      def add_all!
+      def add_all!(repo_dir: '.')
         paths = add_paths
-        out, err, ok = run_cmd('git', 'add', *paths)
-        ensure_ok!(ok, 'git add', stdout: out, stderr: err)
+        out, err, ok = run_cmd('git', 'add', *paths, chdir: repo_dir)
+        ensure_ok!(ok, 'git add', stdout: out, stderr: err, repo_dir: repo_dir)
+      end
+
+      def sensitive_path?(path)
+        SENSITIVE_PATH_PATTERNS.any? { |pattern| path.match?(pattern) }
+      end
+
+      def sensitive_staged_paths(repo_dir: '.')
+        out, _err, ok = run_cmd('git', 'diff', '--cached', '--name-only', chdir: repo_dir)
+        return [] unless ok
+
+        out.split("\n").reject(&:empty?).select { |path| sensitive_path?(path) }
       end
 
-      # @return [Boolean] commit 是否成功
-      def commit_with_message!(message)
+      def ensure_no_sensitive_staged!(repo_dir: '.')
+        paths = sensitive_staged_paths(repo_dir: repo_dir)
+        return if paths.empty?
+
+        if ENV['KK_GIT_ALLOW_SENSITIVE'] == '1'
+          warn "Warning: committing sensitive paths: #{paths.join(', ')}"
+        else
+          raise Error,
+                "Refusing to commit sensitive paths: #{paths.join(', ')}. " \
+                'Set KK_GIT_ALLOW_SENSITIVE=1 to override.'
+        end
+      end
+
+      def confirm_commit!(message)
+        return unless ENV['KK_GIT_CONFIRM'] == '1'
+        return if ENV['KK_GIT_YES'] == '1'
+
+        puts "Commit message:\n#{message}\n"
+        raise Error, 'Set KK_GIT_YES=1 to confirm this commit'
+      end
+
+      def commit_with_message!(message, repo_dir: '.')
         commit_args = amend? ? %w[commit --amend -F] : %w[commit -F]
 
         Tempfile.create('commit_message') do |f|
           f.write(message)
           f.flush
-          out, err, ok = run_cmd('git', *commit_args, f.path)
+          out, err, ok = run_cmd('git', *commit_args, f.path, chdir: repo_dir)
           if ok
             true
           elsif err.include?('nothing to commit') || out.include?('nothing to commit')
             puts 'No staged changes to commit'
             false
           else
-            ensure_ok!(ok, 'git commit', stdout: out, stderr: err)
+            ensure_ok!(ok, 'git commit', stdout: out, stderr: err, repo_dir: repo_dir)
             false
           end
         end
       end
 
-      # 自动 add → commit → pull → push 主流程
-      #
       # @return [Symbol] :synced | :committed_and_synced | :noop
-      def auto_commit_push!(commit_message_generator: nil)
-        ensure_in_repo!
+      def auto_commit_push!(commit_message_generator: nil, repo_dir: '.')
+        ensure_in_repo!(repo_dir: repo_dir)
         remote_name = remote
-        branch_name = branch
+        branch_name = branch(repo_dir: repo_dir)
 
-        if working_tree_clean?
-          if status(remote: remote_name, branch: branch_name).needs_sync?
-            sync_with_remote!(remote_name, branch_name)
+        if working_tree_clean?(repo_dir: repo_dir)
+          if status(remote: remote_name, branch: branch_name, repo_dir: repo_dir).needs_sync?
+            sync_with_remote!(remote_name, branch_name, repo_dir: repo_dir)
             return :synced
           end
 
@@ -254,20 +318,23 @@ module KKGit
           return :noop
         end
 
-        add_all!
+        add_all!(repo_dir: repo_dir)
+        ensure_no_sensitive_staged!(repo_dir: repo_dir)
 
         message =
           if commit_message_generator
             commit_message_generator.call
           else
-            KKGit::CommitMessage.generate(mode: :all)
+            KKGit::CommitMessage.generate(repo_dir: repo_dir, mode: :all)
           end
         message = message.to_s.strip
-        message = "chore(repo): update project files\n\n#{Time.now}" if message.empty?
+        raise Error, 'Could not generate commit message from staged changes' if message.empty?
+
+        confirm_commit!(message)
 
-        committed = commit_with_message!(message)
-        if committed || unpushed_commits?(remote_name, branch_name)
-          sync_with_remote!(remote_name, branch_name)
+        committed = commit_with_message!(message, repo_dir: repo_dir)
+        if committed || unpushed_commits?(remote_name, branch_name, repo_dir: repo_dir)
+          sync_with_remote!(remote_name, branch_name, repo_dir: repo_dir)
           return committed ? :committed_and_synced : :synced
         end
 

data/lib/kk/git/git_runner.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module KKGit
+  # Shared git subprocess helper for CommitMessage and GitOps.
+  module GitRunner
+    module_function
+
+    def capture(args, repo_dir: '.')
+      stdout, stderr, status = Open3.capture3('git', *args, chdir: repo_dir)
+      [normalize_utf8(stdout), normalize_utf8(stderr), status.success?]
+    end
+
+    def capture!(args, repo_dir: '.')
+      stdout, stderr, ok = capture(args, repo_dir: repo_dir)
+      raise "git #{args.join(' ')} failed: #{stderr.strip}" unless ok
+
+      stdout
+    end
+
+    def normalize_utf8(str)
+      str.to_s.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "\uFFFD")
+    end
+  end
+end

data/lib/kk/git/network_hints.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module KKGit
+  # Append actionable hints when git network operations fail.
+  module NetworkHints
+    module_function
+
+    def for_git_failure(title:, stderr:, stdout: nil, suggested_https_url: nil)
+      combined = [stderr, stdout].compact.join("\n")
+      return [] if combined.strip.empty?
+
+      hints = []
+      hints << ssh_timeout_hint(suggested_https_url) if ssh_timeout?(combined)
+      hints << auth_hint if auth_failure?(combined)
+      hints << unreachable_hint if host_unreachable?(combined) && hints.empty?
+
+      hints
+    end
+
+    def ssh_timeout?(text)
+      text.match?(/ssh:.*connect to host .+ port 22.*timed out/i) ||
+        (text.match?(/Operation timed out/i) && text.match?(/ssh:/i))
+    end
+
+    def auth_failure?(text)
+      text.match?(/Authentication failed/i) ||
+        text.match?(/Permission denied \(publickey\)/i) ||
+        text.match?(/could not read Username/i)
+    end
+
+    def host_unreachable?(text)
+      text.match?(/Could not read from remote repository/i) ||
+        text.match?(/unable to access/i) ||
+        text.match?(/Connection refused/i)
+    end
+
+    def ssh_timeout_hint(suggested_https_url)
+      lines = [
+        'Network hint: SSH to the git host on port 22 timed out (often blocked by firewalls or ISP).',
+        'Fix options:',
+        '  1) Switch remote to HTTPS:',
+        '       git remote set-url origin https://github.com/USER/REPO.git',
+        '  2) Use SSH over port 443 (~/.ssh/config):',
+        '       Host github.com',
+        '         Hostname ssh.github.com',
+        '         Port 443',
+        '  3) One-off push/pull without changing remote:',
+        '       KK_GIT_PUSH_URL=https://github.com/USER/REPO.git kk-git push'
+      ]
+      lines << "  Suggested KK_GIT_PUSH_URL=#{suggested_https_url}" if suggested_https_url
+      lines.join("\n")
+    end
+
+    def auth_hint
+      <<~HINT.strip
+        Auth hint: remote rejected credentials.
+          - HTTPS: use a PAT and credential helper
+          - SSH: ensure ssh-agent has the right key (ssh -T git@github.com)
+      HINT
+    end
+
+    def unreachable_hint
+      'Network hint: could not reach the remote. Check VPN, proxy, DNS, and `git remote -v`.'
+    end
+
+    # git@github.com:owner/repo.git -> https://github.com/owner/repo.git
+    def ssh_remote_to_https(url)
+      return nil if url.nil? || url.strip.empty?
+
+      if (m = url.strip.match(/\Agit@([^:]+):(.+?)(?:\.git)?\z/))
+        host = m[1]
+        path = m[2]
+        return "https://#{host}/#{path}.git"
+      end
+
+      nil
+    end
+  end
+end

data/lib/kk/git/rake_tasks.rb

@@ -67,6 +67,9 @@ module KKGit
           end
 
           KKGit::GitOps.auto_commit_push!(commit_message_generator: generator)
+        rescue KKGit::GitOps::Error => e
+          warn e.message
+          exit 1
         end
       end
     end

data/lib/kk/git/release.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module KKGit
+  # Semver bump and git tag helpers (maintainer release flow).
+  module Release
+    VERSION_PATH = File.join(__dir__, 'version.rb').freeze
+
+    module_function
+
+    def latest_semver_tag(prefix: 'v', repo_dir: '.')
+      stdout, _stderr, ok = GitOps.run_cmd(
+        'git', 'tag', '--list', "#{prefix}[0-9]*.[0-9]*.[0-9]*", '--sort=-v:refname',
+        chdir: repo_dir
+      )
+      return nil unless ok
+
+      stdout.to_s.split("\n").first&.strip
+    end
+
+    def parse_semver(str)
+      m = str.to_s.match(/\A(\d+)\.(\d+)\.(\d+)\z/)
+      return nil unless m
+
+      [m[1].to_i, m[2].to_i, m[3].to_i]
+    end
+
+    def bump_semver(version, level)
+      major, minor, patch = version
+      case level
+      when 'major' then [major + 1, 0, 0]
+      when 'minor' then [major, minor + 1, 0]
+      else [major, minor, patch + 1]
+      end
+    end
+
+    def semver_to_s(version)
+      "#{version[0]}.#{version[1]}.#{version[2]}"
+    end
+
+    def semver_gt?(a, b)
+      return false if a.nil? || b.nil?
+
+      a.each_with_index do |part, i|
+        return true if part > b[i]
+        return false if part < b[i]
+      end
+      false
+    end
+
+    def semver_max(*versions)
+      versions.compact.max_by { |v| v }
+    end
+
+    def tag_exists?(tag, repo_dir: '.')
+      out, _err, ok = GitOps.run_cmd('git', 'tag', '--list', tag, chdir: repo_dir)
+      ok && !out.to_s.strip.empty?
+    end
+
+    def current_version_in_file
+      content = File.read(VERSION_PATH, mode: 'r:BOM|UTF-8')
+      m = content.match(/VERSION\s*=\s*'([^']*)'/)
+      m ? parse_semver(m[1]) : nil
+    end
+
+    # @return [Boolean] true when file was updated
+    def update_version!(new_version)
+      content = File.read(VERSION_PATH, mode: 'r:BOM|UTF-8')
+      return false if content.match?(/VERSION\s*=\s*'#{Regexp.escape(new_version)}'/)
+
+      replaced = content.sub(/VERSION\s*=\s*'[^']*'/, "VERSION = '#{new_version}'")
+      raise "Failed to update version in #{VERSION_PATH}" if replaced == content
+
+      File.write(VERSION_PATH, replaced)
+      true
+    end
+
+    # @return [Array(String, String)] tag, version
+    def next_tag_and_version(prefix: nil, bump: nil, repo_dir: '.')
+      prefix ||= ENV.fetch('KK_GIT_TAG_PREFIX', 'v')
+      bump ||= ENV.fetch('KK_GIT_BUMP', 'patch')
+
+      latest_tag = latest_semver_tag(prefix: prefix, repo_dir: repo_dir)
+      tag_version = latest_tag ? parse_semver(latest_tag.delete_prefix(prefix)) : nil
+      file_version = current_version_in_file || parse_semver(KKGit::VERSION)
+
+      # version.rb already ahead of tags and tag not yet created → release that version
+      if file_version && tag_version && semver_gt?(file_version, tag_version)
+        candidate = "#{prefix}#{semver_to_s(file_version)}"
+        return [candidate, semver_to_s(file_version)] unless tag_exists?(candidate, repo_dir: repo_dir)
+      end
+
+      base = semver_max(tag_version, file_version) || [0, 1, 0]
+      version = base
+      50.times do
+        version = bump_semver(version, bump)
+        candidate = "#{prefix}#{semver_to_s(version)}"
+        return [candidate, semver_to_s(version)] unless tag_exists?(candidate, repo_dir: repo_dir)
+      end
+
+      raise 'Failed to generate next release tag: too many attempts'
+    end
+
+    def create_and_push_tag!(tag, remote: nil, repo_dir: '.')
+      remote ||= GitOps.remote
+      out, err, ok = GitOps.run_cmd('git', 'tag', '-a', tag, '-m', "Release #{tag}", chdir: repo_dir)
+      GitOps.ensure_ok!(ok, 'git tag', stdout: out, stderr: err, repo_dir: repo_dir)
+
+      push_target = GitOps.push_target(remote)
+      out, err, ok = GitOps.run_cmd('git', 'push', push_target, tag, chdir: repo_dir)
+      GitOps.ensure_ok!(ok, 'git push tag', stdout: out, stderr: err, repo_dir: repo_dir)
+    end
+  end
+end

data/lib/kk/git/version.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
 module KKGit
-  VERSION = '0.2.1'
+  VERSION = '0.2.2'
 end
-

data/lib/kk/git.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
 require_relative 'git/version'
+require_relative 'git/git_runner'
 require_relative 'git/commit_message'
 require_relative 'git/git_ops'
+require_relative 'git/release'
 
 module KKGit
 end

metadata

@@ -1,19 +1,19 @@
 --- !ruby/object:Gem::Specification
 name: kk-git
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
 platform: ruby
 authors:
 - kk
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-19 00:00:00.000000000 Z
+date: 2026-07-07 00:00:00.000000000 Z
 dependencies: []
 description: Generate Conventional Commits commit messages from current git changes
   (staged/worktree), designed for Rake/script usage.
 email:
-- ''
+- kk@users.noreply.github.com
 executables:
 - kk-git
 extensions: []
@@ -23,13 +23,18 @@ files:
 - lib/kk/git.rb
 - lib/kk/git/commit_message.rb
 - lib/kk/git/git_ops.rb
+- lib/kk/git/git_runner.rb
+- lib/kk/git/network_hints.rb
 - lib/kk/git/rake_tasks.rb
+- lib/kk/git/release.rb
 - lib/kk/git/version.rb
-homepage: ''
+homepage: https://github.com/kevin197011/kk-git
 licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/kevin197011/kk-git
+  changelog_uri: https://github.com/kevin197011/kk-git/blob/main/CHANGELOG.md
 post_install_message:
 rdoc_options: []
 require_paths: