[rdawebb]

feat(cli): redesign the commands and flags, add entry filters, --rm, --dereference and a 'test' command

The CLI is refactored so each flag has one meaning, modelled on tar/bsdtar for archives and gzip/zstd/xz for codecs. The format and output rules move out of the CLI into frontend/dispatch.py, so the commands only parse, run and render. Several inputs now carry on past a failure, and each finished input prints one summary line. Adds new include and exclude globs for archive entries, deleting inputs with --rm, archiving symlink targets with --dereference, a test command that checks files for damage, and info showing what a codec file's own header states.

Breaking changes

• The comp executable is removed; use compresso
• inspect is renamed info, and the old list (backends and levels) is renamed formats; list is now a new command for an archive's entries
• Each command now has one alias: c, x, l, i, t and b
• extract --list and inspect --entries are removed; use list and list --long
• --overwrite, --skip-existing and --error-on-conflict are replaced by --on-conflict <mode>, with -f/--force as shorthand for overwrite
• compress --format moves from -f to -F, since -f is now --force
• extract -o/--output-dir splits into -C/--directory (where to write) and -o/--output (the one file to write, for a single input that isn't an archive)
• compress -o takes the path as given; an existing directory is no longer treated as the output directory
• extract --max-total-size becomes --max-size and takes a suffix, e.g. 500M or 10G
• benchmark --algos/--strategies/--levels, which took comma-separated values, become the repeatable -a/--algo, -s/--strategy and -l/--level
• compress -a or -s on a format other than .comp now exits 2 with nothing written, and -a with -s is a usage error
• -a and -s only accept the compiled backends and the known strategies, so a typo is refused while parsing, with the valid names listed
• lz4 output now records the content size when the input's length is known, so .lz4 bytes change and the codec manifest is re-recorded
• A special file or symlink that the platform or user can't create now raises IncompleteExtractionError after the rest is extracted, instead of logging a warning; on Windows a failed symlink maps to EPERM for a missing privilege or unsupported volume, and to EIO otherwise, so a full disk still fails the extraction
• CompressionOptions.strategy is now a Strategy StrEnum instead of a str
• print_results() is removed from compresso and compresso.introspect; the table now lives in cli/_render/benchmark.py
• ExtractJob.list_contents() is removed
• ArchiveOptions.format defaults to None instead of 'tar.zst'; plan_archive() now infers it from the output's suffix, falling back to zip
• plan_decompression() reports an OSError's own strerror instead of wrapping it in Cannot read file: …
• compress no longer prints speed, bytes saved, or the separate ratio and original size in its stats, since the plan block and the summary line already show them

Commands

• Several inputs: extract, list, info and test run each input in turn; a failed input is reported against its name and the rest still run, with the exit code reflecting the failure; a path that isn't a file is still a usage error, checked before anything runs
• Output: each finished input prints one line, name before → after (n%) in time, noting a rename or a skip under --on-conflict skip; extraction and decompression leave out the ratio; the plan and stats blocks moved behind -v/--verbose, and -v with -q is a usage error; on a terminal a run gets exactly one blank line above and below its output; piped output isn't padded
• test: new command that decodes each input in full and writes nothing, checking whatever the format checksums; a plain .tar has no checksum over its data, so only its headers and the data's presence are checked; trailing data fails, and an unrecognised file is refused before decoding starts
• list: takes several archives, each under a ==> path <== header as head prints them; --long adds each entry's mode, mtime and, where the format tracks them, compressed size and CRC; --json gives one array item per archive
• info: dispatches on the detected format: an archive gets its summary, a .comp its header and a codec file its format and size; a gzip file also shows its stored name and mtime; an xz, zstd, lz4 or snappy file shows the uncompressed size its index or header states, with the ratio that size gives, read without decoding so a damaged file still shows it; takes several inputs, and --json gives one array item per input
• formats: lists the .comp algorithms with their level ranges, the standalone containers with their aliases and extensions, and the archive formats with their compressed variants; the list comes from the core, so a codec that isn't compiled in isn't listed
• compress and extract:
  • New repeatable --include and --exclude take fnmatch globs matched against any run of whole path components; an exclude overrides everything else, and with any includes an entry must match one; on extract an include adds to --entry, and an include that matches nothing fails the archive after the rest is extracted; a single-file input or output refuses both flags
  • New --rm deletes each input once its output is complete, and --keep/-k keeps the default; an archive removes deepest first, so only what was stored is deleted; it's refused with --on-conflict skip, and on extraction with --entry, --include or --exclude, since the output would hold less than the input; an input that can't be removed gives a warning and a non-zero exit
• compress:
  • New -h/--dereference stores what a symlink points to instead of the link; a link to one of its own ancestor directories stays a link so the walk can't loop, and so does a dangling one; --rm with it deletes the links and leaves their targets
  • -F comp writes the .comp container whatever the output is called, and an unknown -F lists the valid formats
• extract:
  • New repeatable -e/--entry extracts only that entry, or a directory and everything below it; the plan, progress total and count describe only what is writtenl; a name matching nothing fails that archive after the rest is extracted, and -e on a non-archive input fails
  • New --no-same-permissions, -m/--touch, --overwrite-dir and --max-depth expose the remaining extract options; -p with --no-same-permissions is a usage error
  • Contradictory combinations are refused: -o with -C, -o with several inputs, and -o on an archive
  • A missing output directory is now created for single-file inputs too
• benchmark: -r/--repeats must be at least 1; benchmark_file() drops the redundant warnings about sizes changing between runs
• asyncio and tabulate are imported only when used, which speeds up startup for the synchronous commands

Core

• create_archive() and extract_archive() take include and exclude patterns; when creating, an excluded tree is never descended into, and a directory that matches no include is kept only if something below it survives
• New path_matches() and format_stores_hardlinks(), so the planner matches entry names and counts hardlinks the same way the walk and the extractor do
• create_archive() takes remove_sources and dereference; a source that couldn't be removed raises the new SourceRemovalError, which carries the path written and every path left behind with its reason
• New verify_file() for test. list_archive_contents() becomes a generic reader pass that verify_file() reuses; a plain archive gets a headers-only pass first, so progress counts what its entries hold rather than the file's size
• Zip now reads one byte past a link target, since libzip only checks the CRC once a read reaches the end
• A cancel while the reader opens is reported as cancelled, not as an unexplained failure
• New stored_content_size() reads the size a codec file states, and returns None unless the structures account for the whole file; zstd frames are walked per RFC 8878, because ZSTD_getFrameHeader needs static linking; xz goes through lzma_file_info_decoder(), so concatenated streams and their padding add up

Frontend

• New frontend/dispatch.py takes the dispatch rules from cli/_dispatch.py; plan_compress() and plan_extract() take a frozen CompressRequest or ExtractRequest and return the planned job, or one per input, so the GUI can reuse them unchanged
• Several inputs to a single-file format is now a ValueError from the planner, which compress turns into a usage error
• ArchiveOptions gains include, exclude, remove_sources and dereference, and ExtractOptions gains include and exclude; the plans apply the same rules as the core, so the planned entries are the ones written
• New VerificationPlan, plan_verification() and VerificationJob, plus Strategy, exported from compresso and compresso.frontend
• plan_compression() runs the core's check even with no level given, so the plan catches an unknown algorithm instead of the run
• The format tables, canonical_standalone_format(), infer_format(), archive_formats() and gzip_stored_mtime() move to frontend/_formats.py

CLI internals

• _render becomes a package that holds all CLI output: jobs.py for each job's plan, result and summary, info.py for list and info text and JSON, plus formats.py and benchmark.py
• New cli/_run.py holds run_job(), run_all(), conflict_mode(), require_files() and remove_source(), which replace each command's own timing, progress bar and exit handling; InputFailed and NotRemoved mark one input's failure for run_all() to report
• New handles_errors() decorator holds the Ctrl-C exit, the core-error exit and the catch-all that every command repeated, so a command now names its operation for a core error instead of calling it unexpected
• report_error() splits out of fail() and flushes stdout first, so an error doesn't print above earlier inputs' summary lines
• main() wraps a terminal's stdout and stderr to pad a run's output in one place, replacing each command's own leading and trailing print()

Python tests

• test_cli.py splits into tests/python/cli/, with one module per command, test_app.py for shared formatting, exit codes, interruption and output padding, and a conftest.py for the shared fixtures
• New frontend/test_dispatch.py asserts on the job each request plans; the CLI round trips keep one case each and check that the commands run what the planner returns
• New cli/test_benchmark.py, cli/test_verify.py and frontend/test_verification.py
• test_archive_create.py, test_archive_extract.py and test_core.py cover include and exclude, --rm, dereferencing (including links to ancestors and dangling links), and the stored-size readers

C tests

• test_select.c covers path_matches()
• The gzip-header fuzz target also drives the four stored-size readers