Module: Kward::ImageAttachments

Defined in:
lib/kward/image_attachments.rb

Constant Summary collapse

MAX_IMAGE_BYTES = 
20 * 1024 * 1024
MIME_TYPES = 
{
  ".gif" => "image/gif",
  ".jpg" => "image/jpeg",
  ".jpeg" => "image/jpeg",
  ".png" => "image/png",
  ".webp" => "image/webp"
}.freeze
DATA_URI_PATTERN = 
%r{data:(image/(?:gif|jpe?g|png|webp));base64,([A-Za-z0-9+/=\r\n]+)}i.freeze
MARKDOWN_IMAGE_PATTERN = 
/!\[[^\]]*\]\(([^)]+)\)/.freeze
EMBEDDED_IMAGE_EXTENSION_PATTERN = 
/\.(?:gif|jpe?g|png|webp)\b/i.freeze
DEFAULT_TERMINAL_IMAGE_WIDTH = 
"40".freeze
SCREENSHOT_SEARCH_DIRS = 
["Desktop", "Downloads", "Pictures"].freeze
PASTED_IMAGE_BASENAME_PATTERN = 
/\A(?:screenshot|screen shot|pasted[-_]image)/i.freeze

Class Method Summary collapse

Class Method Details

.clean_markdown_path(path) ⇒ Object 



233
234
235
 
# File 'lib/kward/image_attachments.rb', line 233

def clean_markdown_path(path)
  path.to_s.strip.sub(/\A["']/, "").sub(/["']\z/, "")
end

.content_from_text(text) ⇒ Object 



26
27
28
29
30
31
32
 
# File 'lib/kward/image_attachments.rb', line 26

def content_from_text(text)
  text = text.to_s
  images = image_parts_from_text(text)
  return text if images.empty?

  [{ type: "text", text: text }] + images
end

.data_uri_parts(text, seen) ⇒ Object 



134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
 
# File 'lib/kward/image_attachments.rb', line 134

def data_uri_parts(text, seen)
  text.scan(DATA_URI_PATTERN).filter_map do |media_type, data|
    normalized_data = data.gsub(/\s+/, "")
    key = "data:#{media_type.downcase};#{normalized_data}"
    next if seen[key]

    decoded_bytes = Base64.decode64(normalized_data).bytesize
    next if decoded_bytes > MAX_IMAGE_BYTES

    seen[key] = true
    { type: "image", media_type: media_type.downcase.sub("image/jpg", "image/jpeg"), data: normalized_data }
  rescue ArgumentError
    nil
  end
end

.data_uri_references(text, seen) ⇒ Object 



79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/kward/image_attachments.rb', line 79

def data_uri_references(text, seen)
  text.scan(DATA_URI_PATTERN).filter_map do |media_type, data|
    source_text = Regexp.last_match[0]
    normalized_data = data.gsub(/\s+/, "")
    key = "data:#{media_type.downcase};#{normalized_data}"
    next if seen[key]

    decoded_bytes = Base64.decode64(normalized_data).bytesize
    next if decoded_bytes > MAX_IMAGE_BYTES

    seen[key] = true
    {
      status: :attached,
      type: "image",
      label: "pasted image",
      media_type: media_type.downcase.sub("image/jpg", "image/jpeg"),
      size_bytes: decoded_bytes,
      source_text: source_text
    }
  rescue ArgumentError
    nil
  end
end

.data_url(part) ⇒ Object 



294
295
296
297
 
# File 'lib/kward/image_attachments.rb', line 294

def data_url(part)
  media_type = part[:mimeType] || part["mimeType"] || part[:media_type] || part["media_type"]
  "data:#{media_type};base64,#{part[:data] || part["data"]}"
end

.display_text_without_references(text, references) ⇒ Object 



45
46
47
48
49
50
 
# File 'lib/kward/image_attachments.rb', line 45

def display_text_without_references(text, references)
  references.reduce(text.to_s.dup) do |result, reference|
    source = reference[:source_text].to_s
    source.empty? ? result : result.sub(source, "")
  end.gsub(/[ \t]{2,}/, " ").gsub(/[ \t]+\n/, "\n").strip
end

.embedded_image_candidate?(path) ⇒ Boolean

Returns:

  • (Boolean) 


204
205
206
 
# File 'lib/kward/image_attachments.rb', line 204

def embedded_image_candidate?(path)
  image_reference_candidate?(path)
end

.embedded_image_candidates_from_line(line) ⇒ Object 



188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
 
# File 'lib/kward/image_attachments.rb', line 188

def embedded_image_candidates_from_line(line)
  text = line.to_s
  candidates = []
  text.scan(EMBEDDED_IMAGE_EXTENSION_PATTERN) do
    end_index = Regexp.last_match.end(0)
    embedded_path_start_indexes(text, end_index).each do |start_index|
      candidate = clean_markdown_path(text[start_index...end_index])
      next unless embedded_image_candidate?(candidate)

      candidates << candidate
      break
    end
  end
  candidates
end

.embedded_path_start_indexes(text, end_index) ⇒ Object 



208
209
210
211
212
 
# File 'lib/kward/image_attachments.rb', line 208

def embedded_path_start_indexes(text, end_index)
  starts = [0]
  text[0...end_index].scan(/\s+/) { starts << Regexp.last_match.end(0) }
  starts.uniq
end

.expand_image_basename(path) ⇒ Object 



252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
 
# File 'lib/kward/image_attachments.rb', line 252

def expand_image_basename(path)
  path = clean_markdown_path(path)
  return nil unless image_extension?(path)
  return nil unless File.basename(path) == path

  current_candidate = File.join(Dir.pwd, path)
  return File.expand_path(current_candidate) if File.file?(current_candidate)
  return nil unless pasted_image_basename?(path)

  screenshot_search_dirs.filter_map do |dir|
    candidate = File.join(dir, path)
    next unless File.file?(candidate)

    File.expand_path(candidate)
  end.first
end

.expand_image_path(path) ⇒ Object 



244
245
246
247
248
249
250
 
# File 'lib/kward/image_attachments.rb', line 244

def expand_image_path(path)
  path = clean_markdown_path(path)
  path = file_uri_path(path) if path.start_with?("file://")
  return nil unless image_extension?(path)

  File.expand_path(path)
end

.extract_references_from_text(text) ⇒ Object 



39
40
41
42
43
 
# File 'lib/kward/image_attachments.rb', line 39

def extract_references_from_text(text)
  text = text.to_s
  references = references_from_text(text).select { |reference| reference[:status] == :attached }
  { text: display_text_without_references(text, references), attachments: references }
end

.file_uri_path(uri_text) ⇒ Object 



279
280
281
282
283
284
 
# File 'lib/kward/image_attachments.rb', line 279

def file_uri_path(uri_text)
  uri = URI.parse(uri_text)
  CGI.unescape(uri.path.to_s)
rescue URI::InvalidURIError
  uri_text.delete_prefix("file://")
end

.image_extension?(path) ⇒ Boolean

Returns:

  • (Boolean) 


286
287
288
 
# File 'lib/kward/image_attachments.rb', line 286

def image_extension?(path)
  MIME_TYPES.key?(File.extname(path.to_s).downcase)
end

.image_parts_from_text(text) ⇒ Object 



34
35
36
37
 
# File 'lib/kward/image_attachments.rb', line 34

def image_parts_from_text(text)
  seen = {}
  data_uri_parts(text, seen) + path_parts(text, seen)
end

.image_paths_from_text(text) ⇒ Object 



173
174
175
176
177
178
179
180
181
182
183
184
185
186
 
# File 'lib/kward/image_attachments.rb', line 173

def image_paths_from_text(text)
  paths = []
  text.scan(MARKDOWN_IMAGE_PATTERN) do |match|
    paths << clean_markdown_path(match.first)
  end

  text.each_line do |line|
    candidate = path_candidate_from_line(line)
    paths << candidate if candidate
    paths.concat(path_tokens_from_line(line))
    paths.concat(embedded_image_candidates_from_line(line))
  end
  paths.compact.uniq
end

.image_reference(original_path, expanded_path) ⇒ Object 



103
104
105
106
107
108
109
110
111
112
113
114
 
# File 'lib/kward/image_attachments.rb', line 103

def image_reference(original_path, expanded_path)
  {
    status: :attached,
    type: "image",
    label: File.basename(expanded_path),
    media_type: mime_type(expanded_path),
    size_bytes: File.size(expanded_path),
    path: expanded_path,
    original_path: original_path,
    source_text: original_path
  }
end

.image_reference_candidate?(path) ⇒ Boolean

Returns:

  • (Boolean) 


126
127
128
129
130
131
132
 
# File 'lib/kward/image_attachments.rb', line 126

def image_reference_candidate?(path)
  path = clean_markdown_path(path)
  return false unless image_extension?(path) || path.start_with?("file://")
  return true if path.start_with?("file://", "/", "~/", "./", "../")

  File.basename(path) == path && pasted_image_basename?(path)
end

.iterm_image_protocol?(env) ⇒ Boolean

Returns:

  • (Boolean) 


311
312
313
 
# File 'lib/kward/image_attachments.rb', line 311

def iterm_image_protocol?(env)
  env["TERM_PROGRAM"] == "iTerm.app"
end

.iterm_image_sequence(data, name, width) ⇒ Object 



319
320
321
322
323
 
# File 'lib/kward/image_attachments.rb', line 319

def iterm_image_sequence(data, name, width)
  params = ["inline=1", "preserveAspectRatio=1", "width=#{width}"]
  params << "name=#{Base64.strict_encode64(File.basename(name))}" if name
  "\e]1337;File=#{params.join(";")}:#{data}\a"
end

.kitty_image_protocol?(env) ⇒ Boolean

Returns:

  • (Boolean) 


315
316
317
 
# File 'lib/kward/image_attachments.rb', line 315

def kitty_image_protocol?(env)
  env["KITTY_WINDOW_ID"].to_s != "" || env["TERM"].to_s.include?("kitty") || env["TERM_PROGRAM"] == "WezTerm"
end

.kitty_image_sequence(data, name, width) ⇒ Object 



325
326
327
328
329
 
# File 'lib/kward/image_attachments.rb', line 325

def kitty_image_sequence(data, name, width)
  params = ["inline=1", "preserveAspectRatio=1", "width=#{width}"]
  params << "name=#{Base64.strict_encode64(File.basename(name))}" if name
  "\e_G#{params.join(";")}:#{data}\e\\"
end

.mime_type(path) ⇒ Object 



290
291
292
 
# File 'lib/kward/image_attachments.rb', line 290

def mime_type(path)
  MIME_TYPES[File.extname(path.to_s).downcase]
end

.missing_image_reference(path) ⇒ Object 



116
117
118
119
120
121
122
123
124
 
# File 'lib/kward/image_attachments.rb', line 116

def missing_image_reference(path)
  {
    status: :missing,
    type: "image",
    label: File.basename(clean_markdown_path(path)),
    original_path: path,
    source_text: path
  }
end

.pasted_image_basename?(path) ⇒ Boolean

Returns:

  • (Boolean) 


269
270
271
 
# File 'lib/kward/image_attachments.rb', line 269

def pasted_image_basename?(path)
  File.basename(path).match?(PASTED_IMAGE_BASENAME_PATTERN)
end

.path_candidate_from_line(line) ⇒ Object 



214
215
216
217
218
219
220
221
222
223
224
225
 
# File 'lib/kward/image_attachments.rb', line 214

def path_candidate_from_line(line)
  stripped = line.strip
  return nil if stripped.empty?
  return stripped if stripped.start_with?("file://")

  shell_words = Shellwords.split(stripped)
  return shell_words.first if shell_words.length == 1

  stripped
rescue ArgumentError
  stripped
end

.path_parts(text, seen) ⇒ Object 



150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
 
# File 'lib/kward/image_attachments.rb', line 150

def path_parts(text, seen)
  image_paths_from_text(text).filter_map do |path|
    expanded_path = resolve_image_path(path)
    next unless expanded_path
    next if seen[expanded_path]
    next unless File.file?(expanded_path)
    next if File.size(expanded_path) > MAX_IMAGE_BYTES

    media_type = mime_type(expanded_path)
    next unless media_type

    seen[expanded_path] = true
    {
      type: "image",
      media_type: media_type,
      data: Base64.strict_encode64(File.binread(expanded_path)),
      path: expanded_path
    }
  rescue SystemCallError
    nil
  end
end

.path_tokens_from_line(line) ⇒ Object 



227
228
229
230
231
 
# File 'lib/kward/image_attachments.rb', line 227

def path_tokens_from_line(line)
  Shellwords.split(line).select { |word| image_extension?(word) || word.start_with?("file://") }
rescue ArgumentError
  line.scan(/\S+/).select { |word| image_extension?(word) || word.start_with?("file://") }
end

.references_from_text(text) ⇒ Object 



52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/kward/image_attachments.rb', line 52

def references_from_text(text)
  seen = {}
  refs = data_uri_references(text.to_s, seen)
  image_paths_from_text(text.to_s).each do |path|
    key = "path:#{path}"
    next if seen[key]

    expanded_path = resolve_image_path(path)
    if expanded_path && File.file?(expanded_path)
      next if seen[expanded_path]
      next if File.size(expanded_path) > MAX_IMAGE_BYTES
      next unless mime_type(expanded_path)

      seen[key] = true
      seen[expanded_path] = true
      refs << image_reference(path, expanded_path)
    elsif image_reference_candidate?(path)
      seen[key] = true
      refs << missing_image_reference(path)
    end
  rescue SystemCallError
    seen[key] = true
    refs << missing_image_reference(path)
  end
  refs
end

.resolve_image_path(path) ⇒ Object 



237
238
239
240
241
242
 
# File 'lib/kward/image_attachments.rb', line 237

def resolve_image_path(path)
  expanded_path = expand_image_path(path)
  return expanded_path if expanded_path && File.file?(expanded_path)

  expand_image_basename(path)
end

.screenshot_search_dirs(home: Dir.home, tmpdir: Dir.tmpdir) ⇒ Object 



273
274
275
276
277
 
# File 'lib/kward/image_attachments.rb', line 273

def screenshot_search_dirs(home: Dir.home, tmpdir: Dir.tmpdir)
  (SCREENSHOT_SEARCH_DIRS.map { |dir| File.join(home, dir) } + [tmpdir]).uniq
rescue ArgumentError
  []
end

.terminal_image_sequence(part, width: DEFAULT_TERMINAL_IMAGE_WIDTH, env: ENV) ⇒ Object 



299
300
301
302
303
304
305
306
307
308
309
 
# File 'lib/kward/image_attachments.rb', line 299

def terminal_image_sequence(part, width: DEFAULT_TERMINAL_IMAGE_WIDTH, env: ENV)
  data = part[:data] || part["data"]
  return nil if data.to_s.empty?

  name = part[:path] || part["path"]
  if iterm_image_protocol?(env)
    iterm_image_sequence(data, name, width)
  elsif kitty_image_protocol?(env)
    kitty_image_sequence(data, name, width)
  end
end