metaclean 1.0.2 → 4.0.1

data/lib/metaclean/display.rb

@@ -1,16 +1,7 @@
 # frozen_string_literal: true
 
-# ───────────────────────────────────────────────────────────────────────────
-# Anything that prints to the terminal lives here: ANSI colors, headers,
-# tables, the before/after diff. Keeping presentation in one module means
-# the rest of the codebase stays focused on logic.
-#
-# ANSI escape sequences:
-#   "\e[31m" turns the terminal text red.
-#   "\e[0m"  resets all styling.
-# A modern terminal interprets these; if you redirect to a file, they show
-# up as garbage — that's why we check `tty?` before emitting them.
-# ───────────────────────────────────────────────────────────────────────────
+# All terminal output lives here: ANSI colors, headers, tables, the
+# before/after diff. Colors are gated on `tty?` (see color?).
 
 module Metaclean
   module Display
@@ -21,7 +12,6 @@ module Metaclean
       red:     "\e[31m",
       green:   "\e[32m",
       yellow:  "\e[33m",
-      blue:    "\e[34m",
       magenta: "\e[35m",
       cyan:    "\e[36m",
       gray:    "\e[90m"
@@ -33,35 +23,51 @@ module Metaclean
     # Excluding these makes the diff focus on what actually got stripped.
     NON_METADATA_GROUPS = %w[System File ExifTool Composite].freeze
 
+    # ASCII wordmark shown at the top of --help / --version. Printed by `banner`
+    # (see there for why it's colored line-by-line).
+    LOGO = <<~ART
+      ███╗   ███╗███████╗████████╗ █████╗  ██████╗██╗     ███████╗ █████╗ ███╗   ██╗
+      ████╗ ████║██╔════╝╚══██╔══╝██╔══██╗██╔════╝██║     ██╔════╝██╔══██╗████╗  ██║
+      ██╔████╔██║█████╗     ██║   ███████║██║     ██║     █████╗  ███████║██╔██╗ ██║
+      ██║╚██╔╝██║██╔══╝     ██║   ██╔══██║██║     ██║     ██╔══╝  ██╔══██║██║╚██╗██║
+      ██║ ╚═╝ ██║███████╗   ██║   ██║  ██║╚██████╗███████╗███████╗██║  ██║██║ ╚████║
+      ╚═╝     ╚═╝╚══════╝   ╚═╝   ╚═╝  ╚═╝ ╚═════╝╚══════╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═══╝
+    ART
+
     module_function
 
     # Decides whether to emit ANSI color codes. Colors are wrong when:
     #   * stdout is a pipe/file (not a terminal) — `tty?` is false there
     #   * NO_COLOR env var is set (de-facto convention, see no-color.org)
-    #   * we're on classic Windows cmd.exe (modern Windows Terminal is fine,
-    #     but to be safe we require an explicit FORCE_COLOR opt-in there)
     def color?
       return @color if defined?(@color)
 
       # Per https://no-color.org: disable only when NO_COLOR is set to a
       # non-empty value. An unset or empty NO_COLOR leaves colors on.
       no_color = ENV['NO_COLOR'].to_s
-      @color = $stdout.tty? && no_color.empty? && !Gem.win_platform?
+      @color = $stdout.tty? && no_color.empty?
       @color = true if ENV['FORCE_COLOR']
       @color
     end
 
-    # `c` for "color". Wraps text in the requested color, or returns it
-    # plain if colors are disabled. The reset code at the end stops the
-    # color from bleeding into following output.
+    # Wrap text in a color, or pass it through plain when colors are off.
     def c(text, color)
-      return text.to_s unless color?
+      text = printable(text)
+      return text unless color?
 
       "#{COLORS[color]}#{text}#{COLORS[:reset]}"
     end
 
-    # Visual section markers used throughout the runner's output. Keeping
-    # them here means a single change updates the look everywhere.
+    # Red ASCII wordmark (matches Ruby's brand color) + one-line tagline for
+    # --help / --version. Colored line-by-line on purpose: `c` runs text through
+    # `printable`, which turns control chars (including the heredoc's newlines)
+    # into spaces — so coloring the whole block at once would collapse the logo
+    # onto one line.
+    def banner
+      LOGO.each_line { |line| puts c(line.chomp, :red) }
+      puts c('  strip EXIF · IPTC · XMP · GPS · ID3 — leave the file clean', :gray)
+    end
+
     def header(text)
       puts
       puts c('━' * 64, :gray)
@@ -82,23 +88,19 @@ module Metaclean
     # `only_embedded:` filters out the System/File/etc. noise.
     def metadata_table(meta, only_embedded: false)
       rows = meta.reject { |k, _| k == 'SourceFile' }
-      rows = rows.reject { |k, _| NON_METADATA_GROUPS.include?(group_of(k)) } if only_embedded
+      rows = rows.select { |k, _| embedded_key?(k) } if only_embedded
 
       if rows.empty?
         info(only_embedded ? '(no embedded metadata)' : '(no metadata)')
         return
       end
 
-      # `group_by` partitions an Enumerable into a Hash keyed by the block's
-      # result. Here we group all "GPS:*" tags together, all "EXIF:*" together,
-      # etc., then print each group as a labeled sub-table.
+      # Group "GPS:*", "EXIF:*", … each into its own labeled sub-table.
       grouped = rows.group_by { |k, _| group_of(k) }
       grouped.sort_by { |g, _| g.to_s }.each do |group, pairs|
         puts c("  [#{group}]", :magenta)
         pairs.sort_by { |k, _| k.to_s }.each do |k, v|
           tag = k.to_s.split(':', 2).last
-          # `format` (alias of sprintf) does column alignment: %-38s = left-
-          # aligned, padded to 38 chars.
           line = format('    %-38s %s', truncate(tag, 38), truncate(format_value(v), 60))
           puts c(line, :dim)
         end
@@ -109,16 +111,12 @@ module Metaclean
     # sections: removed, changed, still-present. This is the "before/after"
     # the user asked for.
     def diff(before, after)
-      keys = (before.keys + after.keys).uniq
-                                       .reject { |k| k == 'SourceFile' }
-                                       .reject { |k| NON_METADATA_GROUPS.include?(group_of(k)) }
+      keys = (before.keys + after.keys).uniq.select { |k| embedded_key?(k) }
 
       removed = []
       changed = []
       kept    = []
 
-      # Classifying each key into one of three buckets keeps the rest of
-      # the method simple and testable.
       keys.sort.each do |k|
         b = before[k]
         a = after[k]
@@ -161,22 +159,46 @@ module Metaclean
       end
     end
 
-    # Pull the group name out of "Group:Tag". The `2` argument to split caps
-    # the result at 2 elements, so a value containing ":" doesn't break it.
+    # Group name out of "Group:Tag" (split caps at 2 so a ":" in the value is safe).
     def group_of(key)
       key.to_s.split(':', 2).first.to_s
     end
 
+    # True when `key` names real embedded metadata: not the SourceFile
+    # bookkeeping key, and not one of the System/File/ExifTool/Composite
+    # groups that describe the file rather than its embedded tags. Single
+    # source of truth for "is this a tag we actually stripped?" — shared by
+    # the table, diff, count, removed-count and privacy-residual checks.
+    def embedded_key?(key)
+      key != 'SourceFile' && !NON_METADATA_GROUPS.include?(group_of(key))
+    end
+
     # Make any value safe to print on a single line. Hashes/Arrays get
     # `inspect` (shows their structure); strings are collapsed to single
     # spaces so a multiline tag value doesn't wreck the table.
     def format_value(v)
       case v
-      when Hash, Array then v.inspect
-      else v.to_s.gsub(/\s+/, ' ')
+      when Hash, Array then printable(v.inspect)
+      else
+        # Guard the regexp gsub against invalid-encoding tag values — gsub raises
+        # ArgumentError on them. Exiftool.read already scrubs; this is belt-and-
+        # suspenders so the display layer can never crash the run on hostile bytes.
+        s = printable(v)
+        s.gsub(/\s+/, ' ')
       end
     end
 
+    # Render untrusted filenames/metadata as terminal text, not terminal control.
+    # Exif/Office/PDF metadata can contain ANSI/OSC escape bytes; printing those
+    # raw can recolor output, rewrite a terminal title, or worse. We keep the
+    # content readable by replacing C0/DEL and C1 control chars with spaces
+    # (C1, U+0080–U+009F, holds the 8-bit CSI/OSC introducers some terminals honor).
+    def printable(text)
+      s = text.to_s
+      s = s.scrub unless s.valid_encoding?
+      s.gsub(/[[:cntrl:]]/, ' ')
+    end
+
     # Truncate to N chars with a single-character ellipsis. We use "…"
     # (one Unicode char) instead of "..." so the truncation doesn't itself
     # spill over the budget.
@@ -188,10 +210,7 @@ module Metaclean
     # How many "real" embedded tags are there? Used for the
     # "Before (24 embedded tags) → After (0)" summary line.
     def count_embedded(meta)
-      meta.keys
-          .reject { |k| k == 'SourceFile' }
-          .reject { |k| NON_METADATA_GROUPS.include?(group_of(k)) }
-          .size
+      meta.keys.count { |k| embedded_key?(k) }
     end
   end
 end

data/lib/metaclean/exiftool.rb

@@ -1,140 +1,121 @@
 # frozen_string_literal: true
 
-# ───────────────────────────────────────────────────────────────────────────
-# A thin Ruby wrapper around the external `exiftool` binary.
+# Thin wrapper around the external `exiftool` binary.
 #
-# We use `Open3.capture3` instead of backticks or `system()` because:
-#   1. It returns stdout, stderr, and the process status separately.
-#   2. When called with multiple arguments, it bypasses the shell entirely
-#      — so a filename like `cat; rm -rf /` is treated as ONE filename, not
-#      a shell command. This is the standard way to safely shell out in Ruby.
-# ───────────────────────────────────────────────────────────────────────────
+# Open3.capture3 with multiple args bypasses the shell, so a filename like
+# `cat; rm -rf /` is one argument, not a command. That's not the whole story:
+# exiftool still parses its own arguments, so a filename beginning with "-"
+# (e.g. `-config`) would be read as an option. Every path goes through
+# `Metaclean.safe_path`, which prefixes a leading dash with "./" so it's
+# always seen as a filename.
 
 require 'open3'
 require 'json'
 
 module Metaclean
-  # `module Exiftool` (vs `class`) because we want module-level methods like
-  # `Exiftool.read(path)` — there's no state to carry per instance.
   module Exiftool
-    # `module_function` makes every method below act like a "static" method
-    # on the module *and* a private instance method (rarely used). It saves
-    # writing `def self.read` for every method.
     module_function
 
-    # Returns true if `exiftool` is on PATH. The result is memoized in `@available`
-    # so repeated checks don't re-spawn the process.
-    #
-    # `defined?(@available)` is safer than `@available.nil?` because the
-    # cached value could legitimately be `false` — we want to skip the
-    # re-check in that case too.
+    # True if `exiftool` is on PATH. Memoized so repeated checks don't re-spawn
+    # it (defined? not nil? — the cached value can legitimately be false).
     def available?
       return @available if defined?(@available)
 
-      _out, _err, status = Open3.capture3('exiftool', '-ver')
+      out, _err, status = Open3.capture3('exiftool', '-ver')
       @available = status.success?
+      # Stash the version off the same call so `version` need not re-spawn.
+      @version = @available ? out.strip : nil
+      @available
     rescue Errno::ENOENT
-      # `Errno::ENOENT` ("no such file or directory") is what Open3 raises
-      # when the executable can't be found. We treat that as "not available".
-      @available = false
+      @version = nil
+      @available = false # exiftool not on PATH
     end
 
     # Returns the version string, or nil if exiftool is missing/broken.
+    # Captured by `available?`, so this never re-runs the binary.
     def version
-      return nil unless available?
-
-      out, _err, status = Open3.capture3('exiftool', '-ver')
-      status.success? ? out.strip : nil
-    rescue Errno::ENOENT
-      nil
-    end
-
-    # Hard-fail with a helpful install hint. Called from `read`/`strip!` before
-    # any work, so users see one clear message instead of a low-level Errno.
-    # The `<<~MSG ... MSG` is a "squiggly heredoc": leading indentation is
-    # stripped automatically, so the output is left-aligned.
-    def ensure_available!
-      return if available?
-
-      raise ExiftoolMissing, <<~MSG
-        ExifTool is not installed or not on PATH.
-
-        Install:
-          macOS:    brew install exiftool
-          Debian:   sudo apt install libimage-exiftool-perl
-          Fedora:   sudo dnf install perl-Image-ExifTool
-          Arch:     sudo pacman -S perl-image-exiftool
-          Windows:  scoop install exiftool   (or download exiftool.org)
-      MSG
+      available? ? @version : nil
     end
 
     # Reads metadata from a file and returns a flat Hash of "Group:Tag" => value.
     #
     # ExifTool flag glossary:
     #   -j         JSON output (machine-parseable)
-    #   -G1        Include the family-1 group name (e.g. "EXIF", "GPS", "IPTC")
+    #   -G1        Include the family-1 group name. NB: with -G1 mainstream EXIF
+    #              tags appear under "IFD0"/"ExifIFD"/"IFD1", not "EXIF" (that's
+    #              the family-0 name); GPS/IPTC/XMP-dc keep those group names.
     #   -a         Allow duplicate tags (some formats have several with same name)
     #   -u         Include unknown/unidentified tags
     #   -s         Short tag names (no descriptions)
     #   -n         Numeric values (no human formatting like "1/100 sec")
     #   -api largefilesupport=1   Allow files >4 GB
     def read(path)
-      ensure_available!
       out, err, status = Open3.capture3(
-        'exiftool', '-j', '-G1', '-a', '-u', '-s', '-n', '-api', 'largefilesupport=1', path.to_s
+        'exiftool', '-j', '-G1', '-a', '-u', '-s', '-n', '-api', 'largefilesupport=1',
+        Metaclean.safe_path(path)
       )
       raise Error, "ExifTool read failed: #{err.strip}" unless status.success?
 
       # ExifTool's JSON output is an array (one entry per file). We always
       # pass one file, so we take the first element. `|| {}` handles the
-      # edge case where exiftool returns an empty array.
+      # edge case where exiftool returns an empty array. A non-array shape is
+      # unexpected — bail with a clear error instead of crashing later on
+      # `.first` returning a Hash/scalar.
       data = JSON.parse(out)
-      data.first || {}
+      raise Error, 'Unexpected ExifTool output (expected a JSON array)' unless data.is_a?(Array)
+
+      scrub_encoding(data.first || {})
     rescue JSON::ParserError => e
       raise Error, "Could not parse ExifTool output: #{e.message}"
     end
 
-    # Removes every removable tag, in place. Returns true on success.
-    #
-    # `-all=` is the magic incantation: it sets every tag to nothing (= empty),
-    # which deletes them. `-overwrite_original` makes ExifTool replace the
-    # file directly instead of writing `file_original` next to it.
-    #
-    # The optional `keep_*` flags are useful because:
-    #   * Orientation tells viewers how to rotate phone photos. Removing it
-    #     can show the picture sideways.
-    #   * ICC profile tells viewers which color space the image is in.
-    #     Removing it can shift colors.
-    def strip!(path, keep_orientation: false, keep_color_profile: false)
-      ensure_available!
-
-      preserving = keep_orientation || keep_color_profile
-      args = ['exiftool', '-all=']
-
-      # `-tagsFromFile @` says "copy tags from the same file you're writing
-      # to". That sounds redundant, but combined with `-all=` running first,
-      # it means "delete everything, then re-add only the listed tags".
-      if preserving
-        args.concat(['-tagsFromFile', '@'])
-        args << '-Orientation' if keep_orientation
-        args << '-ICC_Profile' if keep_color_profile
+    # ExifTool labels its -j output UTF-8, but binary/odd tag values (UserComment,
+    # MakerNotes fragments, corrupt or hostile files) can carry invalid bytes. A
+    # later gsub (Display.format_value) raises on an invalid-encoding String and
+    # would crash the whole run, so replace bad bytes up front. This hash is only
+    # used for display/diff/residual checks — the actual strip operates on the
+    # file via the tools — so scrubbing is safe.
+    def scrub_encoding(obj)
+      case obj
+      when String then obj.valid_encoding? ? obj : obj.scrub
+      when Array  then obj.map { |e| scrub_encoding(e) }
+      when Hash   then obj.transform_values { |v| scrub_encoding(v) }
+      else obj
       end
-      args.concat(['-overwrite_original', '-q', '-q', '-api', 'largefilesupport=1', path.to_s])
+    end
+
+    # ExifTool can READ many formats it cannot WRITE, and mat2 owns the strip for
+    # them: the ZIP-based documents (docx/xlsx/pptx/odt/ods/odp/odg/odf/epub) and
+    # the RIFF containers (avi/wav). ExifTool announces the inability with one of
+    # a few phrasings — "writing of X files is not yet supported", "does not yet
+    # support writing of …", or "Can't currently write RIFF … files" — so we
+    # match all of them. strip! returns :unsupported in these cases so the runner
+    # treats it as a soft skip (mat2 does the actual strip), NOT a pipeline
+    # failure that would wrongly pin an already-clean file at :unverified. This is
+    # safe because the post-strip residual re-read still gates the :cleaned status.
+    WRITE_UNSUPPORTED_RE = /not yet support|can't currently write|writing of .* files/i
+
+    # Removes every removable tag, in place. Returns true on success,
+    # :unsupported when ExifTool cannot write the format, and raises on failure.
+    #
+    # `-all=` sets every tag to empty, which deletes them. `-overwrite_original`
+    # makes ExifTool replace the file directly instead of writing `file_original`
+    # next to it. `-api largefilesupport=1` lets files larger than 4 GB through.
+    def strip!(path, also_delete: [])
+      # `-all=` clears metadata, but for TIFF/DNG ExifTool refuses to delete the
+      # IFD0 directory and leaves its tags (Artist, Software, …) behind. So we
+      # ALSO delete the known privacy tags by name and clear the GPS group: both
+      # are no-ops where `-all=` already removed them (e.g. JPEG), but they make
+      # the strip complete AND lossless (no re-encode) for IFD0-preserving formats.
+      args = ['exiftool', '-all=', '-gps:all=']
+      also_delete.each { |tag| args << "-#{tag}=" }
+      args.concat(['-overwrite_original', '-q', '-q', '-api', 'largefilesupport=1', Metaclean.safe_path(path)])
 
       _out, err, status = Open3.capture3(*args)
       return true if status.success?
+      return :unsupported if err.match?(WRITE_UNSUPPORTED_RE)
 
-      # Some minimal/odd files reject the preserve-pass. Fall back to a plain
-      # full strip — but only if we *were* preserving, otherwise the retry
-      # would be identical to the failed attempt.
-      raise Error, "ExifTool strip failed: #{err.strip}" unless preserving
-
-      _out2, err2, status2 = Open3.capture3(
-        'exiftool', '-all=', '-overwrite_original', '-q', '-q', path.to_s
-      )
-      return true if status2.success?
-
-      raise Error, "ExifTool strip failed: #{err2.strip.empty? ? err.strip : err2.strip}"
+      raise Error, "ExifTool strip failed: #{err.strip}"
     end
   end
 end

data/lib/metaclean/ffmpeg.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+# Wrapper around the external `ffmpeg` binary.
+#
+# ffmpeg is used for ONE job the other tools can't do: the Matroska containers
+# (mkv/webm). ExifTool is read-only for Matroska, and mat2 has no Matroska
+# parser, so without ffmpeg those formats can't be cleaned at all. ffmpeg
+# rewrites the container while copying every stream verbatim (`-c copy`) — no
+# re-encode, so the audio/video is bit-identical and only the metadata is gone.
+#
+# Like mat2, ffmpeg can't edit in place: it muxes to a new file. We write to a
+# SecureRandom-named sibling and move it back over the source on success.
+
+require 'open3'
+require 'fileutils'
+require 'securerandom'
+
+module Metaclean
+  module Ffmpeg
+    module_function
+
+    # Memoized PATH check (same pattern as the other wrappers).
+    def available?
+      return @available if defined?(@available)
+
+      out, _err, status = Open3.capture3('ffmpeg', '-version')
+      @available = status.success?
+      # First line is "ffmpeg version 7.1.1 Copyright ..."; grab the 3rd token.
+      @version = @available ? out.lines.first.to_s.split[2] : nil
+      @available
+    rescue Errno::ENOENT
+      @version = nil
+      @available = false
+    end
+
+    def version
+      available? ? @version : nil
+    end
+
+    # Strips all metadata from `path` in place, losslessly. Returns true on
+    # success, raises Metaclean::Error on failure.
+    #
+    #   -map 0            keep every stream (video, audio, subtitles)
+    #   -map_metadata -1  drop global/container metadata
+    #   -map_chapters -1  drop chapter markers (they can carry titles)
+    #   -c copy           remux without re-encoding — bit-identical streams
+    def strip!(path)
+      raise Error, 'ffmpeg not available' unless available?
+
+      tmp  = tmp_path_for(path)
+      # Clear any stale temp from an earlier crashed run before muxing.
+      File.delete(tmp) if File.exist?(tmp)
+
+      _out, err, status = Open3.capture3(
+        'ffmpeg', '-y', '-v', 'error', '-nostdin', '-i', file_url(path),
+        '-map', '0', '-map_metadata', '-1', '-map_chapters', '-1', '-c', 'copy',
+        file_url(tmp)
+      )
+      # ffmpeg can exit 0 yet write nothing on some odd inputs, so require the
+      # output to actually exist before we trust it and move it into place.
+      raise Error, "ffmpeg failed: #{err.strip}" unless status.success? && File.exist?(tmp)
+
+      FileUtils.mv(tmp, path)
+      true
+    ensure
+      # Interrupt-safety: drop the temp if we were killed between mux and rename.
+      # On the success path it's already moved, so this is a no-op.
+      File.delete(tmp) if tmp && File.exist?(tmp)
+    end
+
+    # Sibling temp with the SAME extension (ffmpeg picks the muxer from it) in
+    # the SAME directory (so the final rename is an atomic same-fs move). The
+    # ".metaclean.tmp." marker means Runner#skip? ignores any stray leftover.
+    def tmp_path_for(path)
+      dir  = File.dirname(path)
+      ext  = File.extname(path)
+      File.join(dir, "#{Metaclean::TMP_MARKER}ff.#{Process.pid}.#{SecureRandom.hex(8)}#{ext}")
+    end
+
+    def file_url(path)
+      "file:#{File.expand_path(path)}"
+    end
+  end
+end

data/lib/metaclean/mat2.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-# ───────────────────────────────────────────────────────────────────────────
 # Wrapper around the external `mat2` (Metadata Anonymisation Toolkit 2).
 #
 # mat2 is stricter than ExifTool on certain formats (DOCX/PDF/PNG): instead
@@ -10,7 +9,6 @@
 # mat2's CLI quirk: it does NOT overwrite the original. It writes a new file
 # named `<name>.cleaned.<ext>` next to it. We adapt by renaming that result
 # back over the source after a successful run.
-# ───────────────────────────────────────────────────────────────────────────
 
 require 'open3'
 require 'fileutils'
@@ -20,17 +18,22 @@ module Metaclean
     # File extensions we know mat2 can handle. Keep this list conservative —
     # if mat2 doesn't actually support an extension, the call will fail
     # gracefully via UNSUPPORTED_RE below, but we'd rather not even try.
+    # Deliberately ABSENT: Matroska (mkv/webm) — mat2 has no parser for it; ffmpeg
+    # owns those (Strategy::FFMPEG_FORMATS). QuickTime/MP4-audio (mov/m4a) — mat2
+    # can't write them and ExifTool already cleans them, so listing them only
+    # caused a wasted mat2 spawn that always soft-skipped. WMV (ASF) IS here on
+    # purpose: mat2 CAN write it but ExifTool can't, so mat2 is the only tool that
+    # cleans .wmv — dropping it would make every .wmv permanently :failed.
     SUPPORTED_EXTS = %w[
       pdf png jpg jpeg tif tiff gif bmp svg webp
-      mp3 flac ogg opus wav m4a
-      mp4 avi mkv mov wmv webm
+      mp3 flac ogg opus wav
+      mp4 avi wmv
       docx xlsx pptx odt ods odp odg odf epub
       zip torrent
     ].freeze
 
-    # Regex matching the messages mat2 prints when it can't handle a file.
-    # We use this to distinguish "soft skip" from a real error.
-    # `i` flag = case-insensitive.
+    # Matches the messages mat2 prints when it can't handle a file — lets us
+    # distinguish a soft skip from a real error.
     UNSUPPORTED_RE = /(not supported|isn't supported|cannot be cleaned|unsupported file)/i.freeze
 
     module_function
@@ -39,21 +42,20 @@ module Metaclean
     def available?
       return @available if defined?(@available)
 
-      _out, _err, status = Open3.capture3('mat2', '--version')
+      out, _err, status = Open3.capture3('mat2', '--version')
       @available = status.success?
+      # `mat2 --version` prints "mat2 0.14.0" — `.split.last` grabs the
+      # version number regardless of whatever prefix appears. Captured here
+      # so `version` reuses it instead of re-spawning the binary.
+      @version = @available ? out.strip.split.last : nil
+      @available
     rescue Errno::ENOENT
+      @version = nil
       @available = false
     end
 
     def version
-      return nil unless available?
-
-      out, _err, status = Open3.capture3('mat2', '--version')
-      # `mat2 --version` prints "mat2 0.14.0" — `.split.last` grabs the
-      # version number regardless of whatever prefix appears.
-      status.success? ? out.strip.split.last : nil
-    rescue Errno::ENOENT
-      nil
+      available? ? @version : nil
     end
 
     # Quick check before we even try mat2 on a file. Used by Strategy to
@@ -61,7 +63,7 @@ module Metaclean
     def supports?(path)
       return false unless available?
 
-      SUPPORTED_EXTS.include?(File.extname(path).downcase.delete('.'))
+      SUPPORTED_EXTS.include?(Metaclean.ext_of(path))
     end
 
     # Strips metadata from `path` in place. Returns:
@@ -76,38 +78,39 @@ module Metaclean
       raise Error, 'mat2 not available' unless available?
 
       cleaned = cleaned_path_for(path)
+      safe    = Metaclean.safe_path(path)
 
       # Defensive: if a stale `<name>.cleaned.<ext>` exists from an earlier
       # crashed run, remove it so we don't accidentally use old data.
       File.delete(cleaned) if File.exist?(cleaned)
 
-      out, err, status = Open3.capture3('mat2', path.to_s)
-      combined = "#{out}\n#{err}"
+      out, err, status = Open3.capture3('mat2', safe)
 
-      # Soft skip — mat2 itself told us it can't process this file.
-      # Defensive: if mat2 still wrote a partial `<name>.cleaned.<ext>`,
-      # remove it so a later run doesn't pick up stale output.
-      if combined.match?(UNSUPPORTED_RE)
-        File.delete(cleaned) if File.exist?(cleaned)
-        return :unsupported
-      end
+      # Success path first. mat2 only creates `<name>.cleaned.<ext>` when it
+      # actually stripped something; no file after exit 0 means there was
+      # nothing to remove. We check exit status BEFORE the "unsupported"
+      # message so a successful run that merely warns about one embedded
+      # stream isn't misreported as a soft skip.
+      if status.success?
+        return :no_metadata unless File.exist?(cleaned)
 
-      unless status.success?
-        File.delete(cleaned) if File.exist?(cleaned)
-        # `err.strip.empty? ? out.strip : err.strip` picks whichever stream
-        # has actual content — some tools log to stdout, others to stderr.
-        raise Error, "mat2 failed: #{err.strip.empty? ? out.strip : err.strip}"
+        FileUtils.mv(cleaned, safe)
+        return true
       end
 
-      # mat2 only creates `<name>.cleaned.<ext>` when it actually stripped
-      # something. If the file didn't exist after a successful run, there
-      # was nothing to remove.
-      if File.exist?(cleaned)
-        FileUtils.mv(cleaned, path.to_s)
-        true
-      else
-        :no_metadata
-      end
+      # Failure path. A "not supported" message means a soft skip we report
+      # so the runner can continue with the next tool, not a hard error.
+      combined = "#{out}\n#{err}"
+      return :unsupported if combined.match?(UNSUPPORTED_RE)
+
+      # `err.strip.empty? ? out.strip : err.strip` picks whichever stream
+      # has actual content — some tools log to stdout, others to stderr.
+      raise Error, "mat2 failed: #{err.strip.empty? ? out.strip : err.strip}"
+    ensure
+      # Interrupt-safety: if we were killed (Ctrl-C) between mat2 writing
+      # `<name>.cleaned.<ext>` and the rename, don't leave the orphan behind.
+      # On the success path it's already moved, so this is a no-op.
+      File.delete(cleaned) if cleaned && File.exist?(cleaned)
     end
 
     # Builds the path mat2 will write to: `name.cleaned.ext`.