Module: KKGit::NetworkHints

Defined in:
lib/kk/git/network_hints.rb

Overview

Append actionable hints when git network operations fail.

Class Method Summary collapse

Class Method Details

.auth_failure?(text) ⇒ Boolean

Returns:

  • (Boolean) 


25
26
27
28
29
 
# File 'lib/kk/git/network_hints.rb', line 25

def auth_failure?(text)
  text.match?(/Authentication failed/i) ||
    text.match?(/Permission denied \(publickey\)/i) ||
    text.match?(/could not read Username/i)
end

.auth_hint ⇒ Object 



54
55
56
57
58
59
60
 
# File 'lib/kk/git/network_hints.rb', line 54

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

.for_git_failure(title:, stderr:, stdout: nil, suggested_https_url: nil) ⇒ Object 



8
9
10
11
12
13
14
15
16
17
18
 
# File 'lib/kk/git/network_hints.rb', line 8

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

.host_unreachable?(text) ⇒ Boolean

Returns:

  • (Boolean) 


31
32
33
34
35
 
# File 'lib/kk/git/network_hints.rb', line 31

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

.ssh_remote_to_https(url) ⇒ Object

git@github.com:owner/repo.git -> https://github.com/owner/repo.git



67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/kk/git/network_hints.rb', line 67

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

.ssh_timeout?(text) ⇒ Boolean

Returns:

  • (Boolean) 


20
21
22
23
 
# File 'lib/kk/git/network_hints.rb', line 20

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

.ssh_timeout_hint(suggested_https_url) ⇒ Object 



37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
 
# File 'lib/kk/git/network_hints.rb', line 37

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

.unreachable_hint ⇒ Object 



62
63
64
 
# File 'lib/kk/git/network_hints.rb', line 62

def unreachable_hint
  'Network hint: could not reach the remote. Check VPN, proxy, DNS, and `git remote -v`.'
end