metaclean 1.0.2 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dd45cefaffcadee5f5c740e5e469cba971140c9a2d448d54d433970c985aedf6
-  data.tar.gz: 3c998706d833d78bbaa039ad537d6ed6a4918cb443294f1249597ca88c1b9799
+  metadata.gz: 29c5b4aad77d530c77d0f4fbae6bbb1811dd6c801719e67999a1da802522a06a
+  data.tar.gz: cbeb0bc1eaf21557b922641fe255b1542dfc776e8833d20ae3fc1c74c9d378a5
 SHA512:
-  metadata.gz: 81170d9320c56d98a22939c92ca91e40c896ec1e1383880face355a5c372efdb77c6b94cb3614e98a6c6840296c14a1a7eadb6d885a093853015832cdeef2e23
-  data.tar.gz: 67855bc4b712f6bf1601d9224f672006d4d0f3b9a9ed1c73888b204d45393f1f71323dc9ade31e527205771a726274113cfdd4082943ab3b62a102851cbc343c
+  metadata.gz: b33eebe165d0d484d8fd19c9ba8bcaa28a2767b5597c5a08df946fa329256fb23694b9df35507007d4301998b49ca2bf7599eae1f11b0979b1408ee46a71ee74
+  data.tar.gz: 48a238f59f367c4bd905455cc44bfe12863b02a73bda64b22391d528ef8523d513e5d668992a8d337fe593448ee6552746ca41cf1766fcac6dabbd540e36ba85

data/LICENSE

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright (c) 2026 metaclean contributors
+Copyright (c) 2026 Laurent Zogaj
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,32 +1,89 @@
 # 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.
+```
+███╗   ███╗███████╗████████╗ █████╗  ██████╗██╗     ███████╗ █████╗ ███╗   ██╗
+████╗ ████║██╔════╝╚══██╔══╝██╔══██╗██╔════╝██║     ██╔════╝██╔══██╗████╗  ██║
+██╔████╔██║█████╗     ██║   ███████║██║     ██║     █████╗  ███████║██╔██╗ ██║
+██║╚██╔╝██║██╔══╝     ██║   ██╔══██║██║     ██║     ██╔══╝  ██╔══██║██║╚██╗██║
+██║ ╚═╝ ██║███████╗   ██║   ██║  ██║╚██████╗███████╗███████╗██║  ██║██║ ╚████║
+╚═╝     ╚═╝╚══════╝   ╚═╝   ╚═╝  ╚═╝ ╚═════╝╚══════╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═══╝
+  strip EXIF · IPTC · XMP · GPS · ID3 — leave the file clean
+```
+
+[![CI](https://img.shields.io/github/actions/workflow/status/26zl/metaclean/ci.yml?branch=main&label=CI)](https://github.com/26zl/metaclean/actions/workflows/ci.yml)
+[![Gem](https://img.shields.io/gem/v/metaclean)](https://rubygems.org/gems/metaclean)
+[![Ruby](https://img.shields.io/badge/ruby-%E2%89%A5%203.2-CC342D)](https://www.ruby-lang.org)
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+A small Ruby CLI that strips metadata from almost any file —
+images, audio, video, PDFs, Office documents — and shows a colored before/after
+diff of exactly what was removed.
 
-It wraps three battle-tested tools and routes each file to the right one:
+It wraps four 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)
+- **mat2** — stricter on `.docx` / `.png` and Office/OpenDocument files (rebuilds the file)
 - **qpdf** — rebuilds PDFs and clears residual metadata in unused streams
+- **ffmpeg** — strips the Matroska containers (`.mkv` / `.webm`) the others can't write, by remuxing losslessly (stream copy, no re-encode)
+
+## Why metaclean?
+
+- **Verification-first:** it re-reads the cleaned file and refuses to write a
+  result when known privacy metadata survives.
+- **Safer defaults:** it writes `*_clean` copies by default; `--in-place` keeps a
+  `.bak` and asks for confirmation unless `--force` is set. Note the `.bak` is the
+  **original, with all its metadata** — delete or move the `.bak` files before
+  sharing an in-place-cleaned folder.
+- **Lossless routing:** it avoids mat2 paths that recompress JPEG/WebP or
+  downconvert TIFF, and uses ffmpeg stream-copy for Matroska.
+- **Batch-friendly:** failed or unverified files exit non-zero, so scripts and CI
+  do not mistake uncertainty for success.
+
+## What it looks like
+
+```text
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📄 photo.jpg
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+▸ Before (5 embedded tags)
+  [GPS]
+    GPSLatitude        59.9139
+    GPSLongitude       10.7522
+  [IFD0]
+    Artist             Jane Doe
+    Make               Apple
+    Model              iPhone 15
+  Pipeline: exiftool
+    ✓ exiftool
+▸ After (0 embedded tags)
+  (no embedded metadata)
+▸ Diff
+▸ Removed (5)
+  - GPS:GPSLatitude    59.9139
+  - GPS:GPSLongitude   10.7522
+  - IFD0:Artist        Jane Doe
+  - IFD0:Make          Apple
+  - IFD0:Model         iPhone 15
+✓ → photo_clean.jpg
+```
 
 ## 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
+# 1. Install the four required tools — metaclean refuses to run without all of them
+brew install exiftool mat2 qpdf ffmpeg                    # macOS
+sudo apt install libimage-exiftool-perl mat2 qpdf ffmpeg  # Debian / Ubuntu
+sudo dnf install perl-Image-ExifTool mat2 qpdf ffmpeg     # Fedora
+sudo pacman -S perl-image-exiftool mat2 qpdf ffmpeg       # Arch
+# Windows: use WSL2 (see below), then the Debian / Ubuntu line above
+
+# 2. Install metaclean from RubyGems
 gem install metaclean
 metaclean --version
 metaclean --help
 ```
 
-From a source checkout before publishing:
+From a source checkout:
 
 ```bash
 git clone https://github.com/26zl/metaclean.git && cd metaclean
@@ -41,17 +98,31 @@ You can also run the checkout without installing it by using
 
 ### 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.
+Native Windows isn't supported: `mat2` depends on Python + GTK and doesn't
+install cleanly there, and metaclean requires all four tools. Use
+**[WSL2](https://learn.microsoft.com/windows/wsl/install)** with Ubuntu and
+follow the Debian / Ubuntu line above — everything runs inside WSL.
+
+### Android
 
-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.
+There's no native Android app, but the full CLI runs unchanged inside
+**[Termux](https://f-droid.org/packages/com.termux/)** (install it from F-Droid,
+not the Play Store) via a Debian proot — where `mat2` and the other three tools
+install cleanly from `apt`:
+
+```bash
+pkg install proot-distro
+termux-setup-storage                 # tap "Allow" to grant access to your files
+proot-distro install debian
+proot-distro login debian --bind ~/storage/shared:/sdcard
+# now inside Debian:
+apt update && apt install -y ruby mat2 libimage-exiftool-perl qpdf ffmpeg
+gem install metaclean
+metaclean /sdcard/DCIM/Camera/photo.jpg
+```
+
+The `--bind` is what lets metaclean reach your photos — without it Debian can't
+see the phone's storage.
 
 ## Quick start
 
@@ -68,8 +139,8 @@ 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
+# Clean a whole folder, recursively, no prompts
+metaclean -r --in-place --force ./vacation
 
 # See what would change without writing anything
 metaclean --dry-run photo.jpg
@@ -78,31 +149,27 @@ 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`) |
+| `-i`, `--in-place` | Overwrite originals (keeps a `<file>.bak` — the **original, metadata intact**; remove it before sharing) |
 | `-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 |
+| `-h`, `--help` | Show usage and exit |
+| `-v`, `--version` | Show metaclean's version **and** the detected versions of exiftool/mat2/qpdf/ffmpeg (prints `not found` for any missing) |
 
 ## 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.
+The release workflow builds a `.gem` for every `v*` tag, attaches it to a
+GitHub Release, and publishes it to RubyGems via a
+[Trusted Publisher](https://guides.rubygems.org/trusted-publishing/) (OIDC) —
+`rubygems/release-gem` with `id-token: write`. There is **no `RUBYGEMS_API_KEY`
+secret**; the one-time prerequisite is registering this gem's Trusted Publisher
+on rubygems.org.
 
 ```bash
-git tag v1.0.1
-git push origin v1.0.1
+git tag v4.0.1
+git push origin v4.0.1
 ```
 
 ## Safety
@@ -111,12 +178,29 @@ git push origin v1.0.1
   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.
+- Symlinks are always skipped — metaclean never cleans through a link.
+- Folder and recursive (`-r`) scans deliberately skip **hidden files** (dot-prefixed,
+  e.g. `.secret.jpg`) and metaclean's own outputs (`*_clean.*`, `*.bak`), so a
+  directory run does not clean every file in the tree. To clean a hidden file,
+  name it explicitly: `metaclean .secret.jpg`.
+- A `<file>.bak` left by `--in-place` is the **untouched original** and still
+  contains all its metadata. It is reported in the run, but it is yours to delete
+  or move before sharing the folder.
 - Filename collisions (`photo_clean.jpg` already exists, `.bak` already
-  exists) are resolved with `_1`, `_2`, … suffixes.
+  exists) are resolved with `_1`, `_2`, … suffixes, including late collisions
+  that appear while a file is being cleaned.
 - 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.
+  survived.
+- A file whose strip leaves a privacy residual is **never written** — no
+  `_clean` copy and no `--in-place` overwrite — it is reported failed and the
+  original is left untouched.
+- metaclean requires ExifTool, mat2, qpdf, and ffmpeg, and refuses to run (with
+  install instructions, exit code 2) if any is missing — so the post-clean
+  residual check always runs.
+- Naming no files (a missing path, or everything filtered out), failed files,
+  and unverified cleans exit non-zero, so scripts do not mistake uncertainty for
+  success.
 
 ## What it does *not* do
 
@@ -124,8 +208,20 @@ git push origin v1.0.1
 - 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.
+The post-clean "still present" check is bounded by what ExifTool can re-read.
+For container formats that mat2 cleans but ExifTool only partially parses (e.g.
+`.zip`, `.epub` internals), metadata may be removed that the verification can't
+independently confirm — a clean report means "the tools ran", not "every byte
+was audited".
+
+**SVG:** some mat2 builds (e.g. 0.14.0 on recent Python) crash on SVG, and
+ExifTool is read-only for it — so on those systems metaclean cannot clean
+`.svg`. It reports the file as **failed** (exit 1) and leaves the original
+untouched rather than claiming a false "clean". Where mat2 handles SVG, it
+cleans normally.
+
+Keep ExifTool, mat2, qpdf, and ffmpeg updated; they parse hostile binary
+formats and have had CVEs in the past.
 
 ## License
 

data/bin/metaclean

@@ -1,29 +1,8 @@
 #!/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.
+# Add <repo>/lib to the load path so this runs from a checkout, gem or not.
 $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

@@ -1,52 +1,23 @@
 # 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.
-# ───────────────────────────────────────────────────────────────────────────
+# CLI argument parser. Uses stdlib OptionParser (zero deps) over a gem like Thor.
 
 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
+        recursive:    false,
+        in_place:     false,
+        force:        false,
+        inspect_only: false,
+        dry_run:      false
       }
       @paths = []
     end
@@ -55,26 +26,32 @@ module Metaclean
     # shells/CI can act on:
     #   0  → success
     #   1  → general failure
-    #   2  → ExifTool missing (specific install hint shown)
+    #   2  → a required tool (exiftool/mat2/qpdf/ffmpeg) is missing (install hint shown)
     #   130→ user pressed Ctrl-C (matches the standard SIGINT exit code)
     def run
       parse!
+      # Refuse to run unless all four external tools are present (see
+      # Metaclean.ensure_tools!). --help/--version already exited inside parse!,
+      # so this only gates an actual inspect/clean.
+      Metaclean.ensure_tools!
       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')
+    rescue ToolsMissing => e
+      warn Display.error('Missing required tools')
       warn e.message
       exit 2
-    rescue Error => e
+    rescue Error, SystemCallError => e
+      # Errno::* (disk full, permission denied, read-only fs) is a SIBLING of
+      # our Error, not a subclass; naming it here gives filesystem failures a
+      # clean message + exit 1 instead of a raw backtrace.
       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.
+      # Print a clean message instead of a stack trace.
       warn "\n#{Display.error('Interrupted.')}"
       exit 130
     end
@@ -83,82 +60,55 @@ module Metaclean
 
     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 'Metadata cleaner. Strips EXIF, IPTC, XMP, GPS,'
+        o.separator 'MakerNotes, ID3, document properties, etc. — uses ExifTool, mat2,'
+        o.separator 'qpdf and ffmpeg 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.on('--inspect', 'Only show metadata, do not modify files')     { @options[:inspect_only] = true }
+        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.on('-i', '--in-place', 'Overwrite originals (keeps a .bak; default: *_clean.<ext>)') { @options[:in_place] = true }
+        o.on('-r', '--recursive', 'Recurse into directories') { @options[:recursive] = true }
+        o.on('-f', '--force',     'Skip confirmation prompt')  { @options[:force] = true }
 
         o.separator ''
         o.separator 'Other:'
-        o.on('-h', '--help')    { puts o; exit }
+        o.on('-h', '--help')    { Display.banner; puts o; exit }
         o.on('-v', '--version') do
+          Display.banner
           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'}"
+          # Route tool versions (from the binaries' own stdout) through printable,
+          # like every other output path, so a tool emitting ANSI/OSC control
+          # bytes on its version line can't inject the terminal.
+          puts "  exiftool: #{Display.printable(Exiftool.version || 'not found')}"
+          puts "  mat2:     #{Display.printable(Mat2.version     || 'not found')}"
+          puts "  qpdf:     #{Display.printable(Qpdf.version     || 'not found')}"
+          puts "  ffmpeg:   #{Display.printable(Ffmpeg.version   || '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.
+      rescue OptionParser::ParseError => e
+        # Any malformed flag — unknown, missing argument, or an ambiguous
+        # abbreviation like `--i` (matches both --inspect and --in-place) —
+        # shows the message + help and exits non-zero, never a raw backtrace.
+        # ParseError is the base class of all of OptionParser's error types.
         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.
+      # No paths: show help, exit non-zero so scripts notice.
       if @argv.empty?
+        Display.banner
         puts parser
         exit 1
       end