suaveplan/openspec/changes/add-drive-storage-archive/proposal.md

Why

The drive VFS already abstracts file operations behind a structural DriveStorage view, but there is no way to mount a compressed archive (zip, tar, gz, tgz, rar, 7z) as a drive. Users routinely receive bundles whose extension lies about the real compression (a .zip that is actually a 7z stream, a .tar.gz renamed .bin) or whose contents are split across multi-volume sets (.part1.rar/.r00–.r99, .7z.001–.7z.NNN, multi-file split-zip). Treating those archives as first-class drives lets every existing drive consumer (sharing, hydrate-from, file-operations, plugins) browse, read, and (where the format permits) write archive contents without ad-hoc extraction.

What Changes

• Add a shared @suaveplan/drive-storage-archive-core package: format sniffing by magic bytes (extension is advisory only), split-volume reassembly, central-directory caching, password/encryption hook contract, and a streaming EntryReader abstraction so per-format adapters only implement the format-specific decode path.
• Add six per-format storage adapters, each implementing the DriveStorage contract over an underlying AbstractStorage (or raw byte source) holding the archive bytes:
  • @suaveplan/drive-storage-zip — ZIP / ZIP64 / split-zip (.z01–.zNN + .zip), read-write with rewrite-on-flush.
  • @suaveplan/drive-storage-tar — POSIX/USTAR/PAX, sparse files, long-name extensions; read-write (append + rewrite on delete).
  • @suaveplan/drive-storage-gz — single-stream gzip wrapping one logical entry; read-write.
  • @suaveplan/drive-storage-tgz — composition of tar over gz (and .tar.bz2, .tar.xz, .tar.zst via pluggable codec); read-mostly, write via full rewrite.
  • @suaveplan/drive-storage-rar — RAR4 + RAR5 + multi-volume (.partN.rar, legacy .r00–.r99); read-only (writing RAR is patent-encumbered).
  • @suaveplan/drive-storage-7z — 7z LZMA/LZMA2/BCJ filters + multi-volume (.7z.001–.7z.NNN); read-write via rewrite-on-flush.
• Public factory openArchiveStorage(source, { format?, password?, splitParts?, mode? }) that auto-detects format from magic bytes, discovers split volumes through a sibling-resolver callback on the host storage, and returns a DriveStorage ready to hand to new Drive(...).
• Mode flags: read-only | copy-on-write (in-memory overlay, materialise on flush()) | rewrite (write directly back through host storage on each mutation). RAR is locked to read-only.
• Error codes namespaced per package (ARCHIVE_*, ZIP_*, TAR_*, GZ_*, RAR_*, SEVENZ_*) registered in each package's error registry.

Capabilities

New Capabilities

• drive-storage-archive-core: shared format sniffing, split-volume reassembly, mode/flush contract, password hook, codec registry, error taxonomy, and conformance harness all per-format adapters run against.
• drive-storage-zip: ZIP/ZIP64/split-zip adapter exposing archive entries as a DriveStorage.
• drive-storage-tar: POSIX/USTAR/PAX tar adapter exposing tar entries as a DriveStorage.
• drive-storage-gz: single-entry gzip adapter exposing the wrapped stream as a DriveStorage.
• drive-storage-tgz: composed tar-over-codec adapter (gzip/bzip2/xz/zstd) exposing entries as a DriveStorage.
• drive-storage-rar: read-only RAR4/RAR5 + multi-volume adapter exposing rar entries as a DriveStorage.
• drive-storage-7z: 7z + multi-volume adapter exposing 7z entries as a DriveStorage.

Modified Capabilities

None — drive's DriveStorage view is already satisfied; no requirement changes to existing specs.

Impact

• New packages under packages/drive/drive-storage-{zip,tar,gz,tgz,rar,7z} plus packages/drive/drive-storage-archive-core (seven total). All universal-tier where the codec is pure-TS, server-tier where native bindings are needed (RAR, optionally 7z LZMA SDK).
• New dependencies on pure-TS codec libraries via Bun catalog (fflate for deflate, pako fallback, lzma-native or wasm lzma, xz-decompress, @zip.js/zip.js is not used — we implement directly for streaming + split support).
• Drive consumers (drive-sharing, drive-template, drive-react-sharing) gain transparent archive browsing with no API changes.
• Bin: optional suaveplan-archive CLI in drive-storage-archive-core for listing/extracting any supported archive from the shell. (Decision deferred to design.md.)
• Test surface: runArchiveConformance harness in drive-storage-archive-core/testing exercised by all six adapters.