Module: Kward::ImageAttachments

Defined in:
lib/kward/image_attachments.rb

Overview

Image attachment parsing, validation, encoding, and display helpers.

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 



235
236
237
 
# File 'lib/kward/image_attachments.rb', line 235

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

.content_from_text(text) ⇒ Object 



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

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 



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

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 



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

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 



296
297
298
299
 
# File 'lib/kward/image_attachments.rb', line 296

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 



47
48
49
50
51
52
 
# File 'lib/kward/image_attachments.rb', line 47

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) 


206
207
208
 
# File 'lib/kward/image_attachments.rb', line 206

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

.embedded_image_candidates_from_line(line) ⇒ Object 



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

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 



210
211
212
213
214
 
# File 'lib/kward/image_attachments.rb', line 210

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 



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

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 



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

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 



41
42
43
44
45
 
# File 'lib/kward/image_attachments.rb', line 41

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 



281
282
283
284
285
286
 
# File 'lib/kward/image_attachments.rb', line 281

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) 


288
289
290
 
# File 'lib/kward/image_attachments.rb', line 288

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

.image_parts_from_text(text) ⇒ Object 



36
37
38
39
 
# File 'lib/kward/image_attachments.rb', line 36

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

.image_paths_from_text(text) ⇒ Object 



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

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 



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

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) 


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

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) 


313
314
315
 
# File 'lib/kward/image_attachments.rb', line 313

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

.iterm_image_sequence(data, name, width) ⇒ Object 



321
322
323
324
325
 
# File 'lib/kward/image_attachments.rb', line 321

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) 


317
318
319
 
# File 'lib/kward/image_attachments.rb', line 317

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 



327
328
329
330
331
 
# File 'lib/kward/image_attachments.rb', line 327

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 



292
293
294
 
# File 'lib/kward/image_attachments.rb', line 292

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

.missing_image_reference(path) ⇒ Object 



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

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) 


271
272
273
 
# File 'lib/kward/image_attachments.rb', line 271

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

.path_candidate_from_line(line) ⇒ Object 



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

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 



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

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 



229
230
231
232
233
 
# File 'lib/kward/image_attachments.rb', line 229

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 



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

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 



239
240
241
242
243
244
 
# File 'lib/kward/image_attachments.rb', line 239

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 



275
276
277
278
279
 
# File 'lib/kward/image_attachments.rb', line 275

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 



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

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