bz2 extractor

The bz2 extractor is a specialized tool for accessing data stored in bz2 compressed archives, including single-file bz2 streams and tar.bz2 bundles. It is intended for developers, system administrators, data engineers, and IT operations teams who receive compressed archives as backups, data feeds, or deliverables. The tool focuses on correctness, speed, and safety, performing streaming decompression when possible and preserving file metadata. Its output is a clear file listing plus the actual extracted content when requested, enabling downstream tasks such as data ingestion, archival verification, and disaster recovery.\n\nCore logic is designed around automatic format detection and safe extraction. On input, the engine detects whether the stream is a plain bz2 file or a tar archive compressed with bz2. For tar.bz2 it iterates archive members, recreating directory structures when requested and reporting per-file size, modification time, and CRC if available. For simple bz2, it writes the decompressed data to the chosen destination. The tool supports both disk-based extraction and in-memory results for small artifacts, supporting automation and scripting.\n\nOutputs include a structured listing of extracted files, total decompressed size, and optional integrity results. Errors map to concrete codes (invalid header, truncated stream, or unsupported compression), enabling robust integration with CI pipelines and monitoring. Industry practices such as POSIX path handling, UTF-8 filenames, and cross-platform compatibility are respected, with normalized timestamps and consistent unit usage in bytes. Assumptions include no encryption in bz2 streams and compatibility with common tar formats; exclusions cover other compression schemes and UI-specific behaviors.