metaclean 1.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dd45cefaffcadee5f5c740e5e469cba971140c9a2d448d54d433970c985aedf6
+  data.tar.gz: 3c998706d833d78bbaa039ad537d6ed6a4918cb443294f1249597ca88c1b9799
+SHA512:
+  metadata.gz: 81170d9320c56d98a22939c92ca91e40c896ec1e1383880face355a5c372efdb77c6b94cb3614e98a6c6840296c14a1a7eadb6d885a093853015832cdeef2e23
+  data.tar.gz: 67855bc4b712f6bf1601d9224f672006d4d0f3b9a9ed1c73888b204d45393f1f71323dc9ade31e527205771a726274113cfdd4082943ab3b62a102851cbc343c

data/LICENSE

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2026 metaclean contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,132 @@
+# metaclean
+
+A small cross-platform Ruby CLI that strips metadata from almost any file
+(images, audio, video, PDFs, Office documents, …) and shows you a colored
+before/after diff of exactly what was removed.
+
+It wraps three battle-tested tools and routes each file to the right one:
+
+- **ExifTool** — the broadest format coverage (EXIF, IPTC, XMP, GPS, ID3, …)
+- **mat2** — stricter on `.docx` / `.pdf` / `.png` (rebuilds the file)
+- **qpdf** — rebuilds PDFs and clears residual metadata in unused streams
+
+## Install
+
+```bash
+# 1. Install the underlying tools (ExifTool is required, mat2 + qpdf optional)
+brew install exiftool mat2 qpdf                    # macOS
+sudo apt install libimage-exiftool-perl mat2 qpdf  # Debian / Ubuntu
+sudo dnf install perl-Image-ExifTool mat2 qpdf     # Fedora
+sudo pacman -S perl-image-exiftool mat2 qpdf       # Arch
+scoop install exiftool qpdf                        # Windows
+
+# 2. Install metaclean after it has been published to RubyGems
+gem install metaclean
+metaclean --version
+metaclean --help
+```
+
+From a source checkout before publishing:
+
+```bash
+git clone https://github.com/26zl/metaclean.git && cd metaclean
+chmod +x bin/metaclean
+bundle install
+bundle exec rake install
+metaclean --version
+```
+
+You can also run the checkout without installing it by using
+`./bin/metaclean`.
+
+### Windows
+
+You also need Ruby itself. The recommended installer is
+[**RubyInstaller**](https://rubyinstaller.org/) — it ships Ruby plus the
+MSYS2 toolchain (DevKit) that some gems need to compile native extensions.
+`scoop install ruby` and `choco install ruby` install the same RubyInstaller
+distribution under the hood.
+
+Note: `mat2` is hard to install on native Windows (it depends on Python +
+GTK). If you want full coverage, the simplest route is
+**[WSL2](https://learn.microsoft.com/windows/wsl/install)** with Ubuntu, then
+follow the Debian/Ubuntu line above. On native Windows without `mat2`,
+metaclean still works — ExifTool + qpdf cover the common cases.
+
+## Quick start
+
+These examples assume metaclean is installed as a gem. From a source checkout,
+replace `metaclean` with `./bin/metaclean`.
+
+```bash
+# Show metadata, do not modify
+metaclean --inspect photo.jpg
+
+# Clean a file → writes photo_clean.jpg next to the original
+metaclean photo.jpg
+
+# Overwrite the original (a .bak is kept by default)
+metaclean --in-place photo.jpg
+
+# Clean a whole folder, recursively, no prompts, no backups
+metaclean -r --in-place --no-backup --force ./vacation
+
+# See what would change without writing anything
+metaclean --dry-run photo.jpg
+```
+
+## Flags
+
+| Flag | What it does |
+|---|---|
+| `--inspect` | Read-only — print metadata, never write |
+| `--json` | JSON output (with `--inspect`) |
+| `--dry-run` | Simulate cleaning, show diff, write nothing |
+| `-i`, `--in-place` | Overwrite originals |
+| `--no-backup` | Do not keep `<file>.bak` (with `--in-place`) |
+| `-r`, `--recursive` | Recurse into directories |
+| `--types=jpg,png,…` | Only process these extensions |
+| `--follow-symlinks` | Follow symlinks (default: skip) |
+| `--keep-orientation` | Preserve EXIF Orientation |
+| `--keep-color-profile` | Preserve embedded ICC profile |
+| `--exiftool-only` | Use only ExifTool |
+| `--no-mat2` / `--no-qpdf` / `--no-exiftool` | Disable a specific tool |
+| `-f`, `--force` | Skip the confirmation prompt |
+| `--strict-verify` | Exit non-zero if privacy tags survive |
+
+## Publishing
+
+The release workflow builds a `.gem` file for every `v*` tag. If the GitHub
+repository has a `RUBYGEMS_API_KEY` secret, the workflow also publishes the gem
+to RubyGems.
+
+```bash
+git tag v1.0.1
+git push origin v1.0.1
+```
+
+## Safety
+
+- All shell-outs use argument arrays (`Open3.capture3(*args)`), so filenames
+  with spaces, quotes, or shell metacharacters are safe.
+- `--in-place` writes atomically: the file is built in a temp file and
+  renamed into place, so a crash mid-run cannot leave a half-written original.
+- Symlinks are skipped by default.
+- Filename collisions (`photo_clean.jpg` already exists, `.bak` already
+  exists) are resolved with `_1`, `_2`, … suffixes.
+- After cleaning, metaclean re-reads the file and warns if known
+  privacy-relevant tags (GPS, MakerNotes, Author, camera serial number, etc.)
+  survived. With `--strict-verify` this becomes a non-zero exit code.
+
+## What it does *not* do
+
+- Steganography (data hidden inside the pixel/audio data itself).
+- Filesystem metadata (mtime, ownership) — that's the OS, not the file.
+- Office macros or PDF JavaScript — open untrusted files in a sandbox.
+
+Keep ExifTool, mat2, and qpdf updated; they parse hostile binary formats and
+have had CVEs in the past.
+
+## License
+
+MIT

data/bin/metaclean

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# ───────────────────────────────────────────────────────────────────────────
+# bin/metaclean — entry point invoked by the user's shell.
+#
+# The shebang `#!/usr/bin/env ruby` makes the file executable on macOS/Linux
+# (after `chmod +x`). `env` looks up Ruby on PATH so it works regardless of
+# where Ruby is installed (Homebrew, rbenv, asdf, etc.).
+#
+# `frozen_string_literal: true` is a Ruby 3 magic comment: every string in
+# this file is implicitly frozen (immutable). This prevents accidental
+# mutation and gives a small performance/memory win.
+# ───────────────────────────────────────────────────────────────────────────
+
+# Add `<repo>/lib` to Ruby's load path so `require 'metaclean'` finds our code
+# without needing the gem installed. `__dir__` is the directory of this file
+# (`bin/`), so `../lib` is the sibling `lib/` directory. `expand_path` turns
+# the relative path into an absolute one.
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+
+# Pull in the whole library. See `lib/metaclean.rb` — that file `require`s
+# every sub-component in dependency order.
+require 'metaclean'
+
+# Hand control to the CLI. `ARGV` is Ruby's built-in array of command-line
+# arguments (everything after the script name). `CLI.start` parses them and
+# decides what to do.
+Metaclean::CLI.start(ARGV)

data/lib/metaclean/cli.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+# ───────────────────────────────────────────────────────────────────────────
+# Command-line argument parser.
+#
+# We use Ruby's standard library `OptionParser` instead of a gem like Thor
+# because it has zero dependencies and is plenty for our needs. The pattern is:
+#
+#   1. Define each flag inside an `OptionParser.new do |o| ... end` block.
+#   2. `o.on(...)` takes the flag spec and a block that runs when the flag
+#      is seen. The block usually mutates `@options` to record the choice.
+#   3. `parser.parse!(@argv)` consumes flags from `@argv` and leaves
+#      positional args (the file paths) behind.
+# ───────────────────────────────────────────────────────────────────────────
+
+require 'optparse'
+
+module Metaclean
+  class CLI
+    # Class-level convenience: `Metaclean::CLI.start(ARGV)` reads cleaner
+    # than `Metaclean::CLI.new(ARGV).run`.
+    def self.start(argv)
+      new(argv).run
+    end
+
+    def initialize(argv)
+      # `dup` makes a shallow copy so we can mutate `@argv` without
+      # surprising the caller (ARGV itself stays intact).
+      @argv = argv.dup
+
+      # All options default to safe/off values. `parse!` flips them
+      # selectively as it sees flags.
+      @options = {
+        recursive:          false,
+        in_place:           false,
+        no_backup:          false,
+        force:              false,
+        inspect_only:       false,
+        format:             :pretty,
+        keep_orientation:   false,
+        keep_color_profile: false,
+        dry_run:            false,
+        follow_symlinks:    false,
+        strict_verify:      false,
+        no_mat2:            false,
+        no_qpdf:            false,
+        no_exiftool:        false,
+        exiftool_only:      false,
+        types:              nil
+      }
+      @paths = []
+    end
+
+    # Top-level dispatcher. Catches our errors and exits with codes that
+    # shells/CI can act on:
+    #   0  → success
+    #   1  → general failure
+    #   2  → ExifTool missing (specific install hint shown)
+    #   130→ user pressed Ctrl-C (matches the standard SIGINT exit code)
+    def run
+      parse!
+      runner = Runner.new(@options)
+      if @options[:inspect_only]
+        runner.inspect_paths(@paths)
+      else
+        runner.clean_paths(@paths)
+      end
+    rescue ExiftoolMissing => e
+      warn Display.error('ExifTool missing')
+      warn e.message
+      exit 2
+    rescue Error => e
+      warn Display.error(e.message)
+      exit 1
+    rescue Interrupt
+      # Pressing Ctrl-C raises `Interrupt`. Catching it lets us print a
+      # clean message instead of a Ruby stack trace.
+      warn "\n#{Display.error('Interrupted.')}"
+      exit 130
+    end
+
+    private
+
+    def parse!
+      parser = OptionParser.new do |o|
+        # The banner shows up at the top of `--help`.
+        o.banner = 'Usage: metaclean [options] <path> [<path>...]'
+        o.separator ''
+        o.separator 'Cross-platform metadata cleaner. Strips EXIF, IPTC, XMP, GPS,'
+        o.separator 'MakerNotes, ID3, document properties, etc. — uses ExifTool, mat2'
+        o.separator 'and qpdf together for maximum coverage.'
+        o.separator ''
+
+        # Each `o.on` registers a flag. The block runs when that flag is
+        # found in argv. `_v` is the captured value (unused for booleans).
+        o.separator 'Modes:'
+        o.on('--inspect',    'Only show metadata, do not modify files')      { @options[:inspect_only] = true }
+        o.on('--json',       'Output as JSON (with --inspect)')              { @options[:format] = :json }
+        o.on('--dry-run',    'Simulate cleaning, show diff, write nothing') { @options[:dry_run] = true }
+
+        o.separator ''
+        o.separator 'Output:'
+        o.on('-i', '--in-place', 'Overwrite originals (default: write *_clean.<ext>)') { @options[:in_place] = true }
+        o.on('--no-backup',      "Don't keep a .bak when --in-place")                  { @options[:no_backup] = true }
+
+        o.separator ''
+        o.separator 'Selection:'
+        o.on('-r', '--recursive',     'Recurse into directories')              { @options[:recursive] = true }
+        o.on('--follow-symlinks',     'Follow symlinks (default: skip them)') { @options[:follow_symlinks] = true }
+        # `--types=LIST, Array` tells OptionParser to split the value on
+        # commas. So `--types=jpg,png` arrives as ["jpg", "png"].
+        o.on('--types=LIST', Array,   'Only process these extensions (e.g. jpg,png,pdf)') do |v|
+          @options[:types] = v.map { |x| x.to_s.downcase.delete('.') }
+        end
+
+        o.separator ''
+        o.separator 'Tool selection:'
+        o.on('--exiftool-only', 'Use only ExifTool (skip mat2 and qpdf)') { @options[:exiftool_only] = true }
+        o.on('--no-mat2',       'Disable mat2 even if available')         { @options[:no_mat2] = true }
+        o.on('--no-qpdf',       'Disable qpdf even if available')         { @options[:no_qpdf] = true }
+        o.on('--no-exiftool',   'Disable ExifTool')                       { @options[:no_exiftool] = true }
+
+        o.separator ''
+        o.separator 'Preservation:'
+        o.on('--keep-orientation',   'Preserve EXIF Orientation tag') { @options[:keep_orientation] = true }
+        o.on('--keep-color-profile', 'Preserve embedded ICC profile') { @options[:keep_color_profile] = true }
+
+        o.separator ''
+        o.separator 'Verification:'
+        o.on('-f', '--force',     'Skip confirmation prompt')              { @options[:force] = true }
+        o.on('--strict-verify',   'Exit non-zero if privacy tags survive') { @options[:strict_verify] = true }
+
+        o.separator ''
+        o.separator 'Other:'
+        o.on('-h', '--help')    { puts o; exit }
+        o.on('-v', '--version') do
+          puts "metaclean #{Metaclean::VERSION}"
+          # `&.split&.last` is safe-navigation: if `Qpdf.version` is nil
+          # (qpdf not installed), the chain short-circuits to nil rather
+          # than blowing up with NoMethodError.
+          puts "  exiftool: #{Exiftool.version || 'not found'}"
+          puts "  mat2:     #{Mat2.version     || 'not found'}"
+          puts "  qpdf:     #{Qpdf.version&.split&.last || 'not found'}"
+          exit
+        end
+      end
+
+      # `parse!` mutates @argv in place: known flags are consumed,
+      # positional args (file paths) are left behind.
+      begin
+        parser.parse!(@argv)
+      rescue OptionParser::InvalidOption, OptionParser::MissingArgument => e
+        # Bad flag → show the message + the help text and exit non-zero.
+        warn Display.error(e.message)
+        warn parser
+        exit 1
+      end
+
+      # No paths after flags → user probably ran `metaclean` with no args.
+      # Show help and exit non-zero so scripts notice.
+      if @argv.empty?
+        puts parser
+        exit 1
+      end
+
+      @paths = @argv.dup
+    end
+  end
+end

data/lib/metaclean/display.rb

@@ -0,0 +1,197 @@
+# 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.
+# ───────────────────────────────────────────────────────────────────────────
+
+module Metaclean
+  module Display
+    COLORS = {
+      reset:   "\e[0m",
+      bold:    "\e[1m",
+      dim:     "\e[2m",
+      red:     "\e[31m",
+      green:   "\e[32m",
+      yellow:  "\e[33m",
+      blue:    "\e[34m",
+      magenta: "\e[35m",
+      cyan:    "\e[36m",
+      gray:    "\e[90m"
+    }.freeze
+
+    # ExifTool reports four "groups" that are descriptions of the file
+    # itself, not embedded metadata: System (filesystem stat), File (header
+    # info), ExifTool (its own version), Composite (computed values).
+    # Excluding these makes the diff focus on what actually got stripped.
+    NON_METADATA_GROUPS = %w[System File ExifTool Composite].freeze
+
+    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 = 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.
+    def c(text, color)
+      return text.to_s 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.
+    def header(text)
+      puts
+      puts c('━' * 64, :gray)
+      puts c(text, :bold)
+      puts c('━' * 64, :gray)
+    end
+
+    def section(text); puts c("▸ #{text}",  :cyan);  end
+    def info(text);    puts c("  #{text}",  :gray);  end
+    def success(text); puts c("✓ #{text}",  :green); end
+    def warning(text); puts c("⚠ #{text}",  :yellow);end
+
+    # `error` returns a string instead of printing it — callers usually want
+    # to send it to STDERR via `warn`, not stdout via `puts`.
+    def error(text); c("✗ #{text}", :red); end
+
+    # Prints a metadata Hash as a grouped, indented table.
+    # `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
+
+      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.
+      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
+      end
+    end
+
+    # Compares two metadata hashes (before vs after) and prints three
+    # 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)) }
+
+      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]
+        if a.nil? && !b.nil?
+          removed << [k, b]
+        elsif !b.nil? && a != b
+          changed << [k, b, a]
+        elsif !b.nil?
+          kept << [k, b]
+        end
+      end
+
+      if removed.any?
+        section "Removed (#{removed.size})"
+        removed.each do |k, b|
+          puts "  #{c('-', :red)} #{c(k, :red)}  #{c(truncate(format_value(b), 60), :gray)}"
+        end
+      end
+
+      if changed.any?
+        section "Changed (#{changed.size})"
+        changed.each do |k, b, a|
+          puts "  #{c('~', :yellow)} #{c(k, :yellow)}"
+          puts "      #{c('-', :red)}   #{truncate(format_value(b), 60)}"
+          puts "      #{c('+', :green)} #{truncate(format_value(a), 60)}"
+        end
+      end
+
+      if kept.any?
+        section "Still present (#{kept.size})"
+        kept.each do |k, b|
+          puts "  #{c('=', :gray)} #{c(k, :gray)}  #{c(truncate(format_value(b), 60), :gray)}"
+        end
+      end
+
+      if removed.empty? && changed.empty? && kept.empty?
+        info 'Nothing to strip — file already clean.'
+      elsif removed.empty? && changed.empty?
+        info 'No tags were removed — see "Still present" above.'
+      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.
+    def group_of(key)
+      key.to_s.split(':', 2).first.to_s
+    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+/, ' ')
+      end
+    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.
+    def truncate(s, n)
+      s = s.to_s
+      s.length > n ? "#{s[0, n - 1]}…" : s
+    end
+
+    # 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
+    end
+  end
+end