suaveplan/openspec/changes/add-drive-storage-archive/tasks.md at main

Files

admin fbc70f96e6 Initial Commit

2026-05-27 23:29:53 +01:00

0. Pre-flight (non-negotiable)

0.1 Confirm clean working tree (git status reports nothing) and no in-flight worktrees with uncommitted work (git worktree list then git status in each)
0.2 If any worktrees exist under .claude/worktrees/, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (git worktree remove) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
0.3 Confirm the package set in MANIFEST.md matches find packages -maxdepth 3 -name package.json count. Drift here means a prior change archived without regenerating the manifest.

1.1 Scaffold packages/drive/drive-storage-archive-core/ with package.json, vite/tsup config, vitest config via createTestConfig(), README, biome-clean tree
1.2 Define ArchiveFormat union, ArchiveMode, ArchiveCodec, ResolveSibling, PasswordHook, OpenArchiveStorageOptions types in src/types/
1.3 Implement sniffFormat(bytes) with magic-byte registry + structural validators (EOCD locate for zip, header checksum for tar, CRC trailer for gz, etc.)
1.4 Implement openArchiveStorage(source, opts) factory with dynamic import() of per-format packages (no eager bundling)
1.5 Implement ARCHIVE_* error code registry via defineCodes from @suaveplan/error
1.6 Implement runArchiveConformance(adapterFactory, opts) harness exported via ./testing subpath
1.7 Implement default sibling-resolver helpers per format (zipResolver, rarResolver, sevenZipResolver) over a DriveStorage-shaped host
1.8 Co-locate .md for every implementation file (Purpose, Features, Usage Basic/Advanced, API Reference, Implementation Notes — ≥200 words, real-import examples)
1.9 100% Vitest coverage on drive-storage-archive-core via bunx turbo test:coverage --filter=@suaveplan/drive-storage-archive-core
1.10 Green bunx turbo lint typecheck test --filter=@suaveplan/drive-storage-archive-core
1.11 Update MANIFEST.md via bun scripts/folder-reorg/generate-manifest.ts

2.1 Scaffold packages/drive/drive-storage-gz/
2.2 Implement gzip member parser (RFC 1952), multi-member concatenation, FNAME extraction
2.3 Implement GzipArchiveStorage DriveStorage view with single-entry presentation
2.4 Implement gzipCodec: ArchiveCodec export for tgz composition
2.5 Implement write paths for copy-on-write and rewrite modes (full re-encode)
2.6 Implement CRC32 + ISIZE validation
2.7 Register GZ_* error codes
2.8 Run runArchiveConformance from drive-storage-archive-core/testing
2.9 Co-located .md docs per implementation file
2.10 100% coverage + lint + typecheck green
2.11 Regenerate MANIFEST

3.1 Scaffold packages/drive/drive-storage-tar/
3.2 Implement tar block reader (512-byte alignment, two-block terminator)
3.3 Implement legacy v7, USTAR, POSIX.1-2001 PAX header parsing
3.4 Implement GNU long-name (L) and long-link (K) reconstruction
3.5 Implement PAX extended header records (path, size, mtime, atime, ctime, uid, gid)
3.6 Implement GNU sparse 1.0 reconstruction with zero-fill
3.7 Implement TarArchiveStorage DriveStorage view
3.8 Implement append-write fast path (before terminator) and full-rewrite path for deletes
3.9 Implement header-checksum validation, raise TAR_HEADER_CHECKSUM_INVALID
3.10 Register TAR_* error codes
3.11 Run runArchiveConformance
3.12 Co-located .md docs per implementation file
3.13 100% coverage + lint + typecheck green
3.14 Regenerate MANIFEST

4.1 Scaffold packages/drive/drive-storage-tgz/
4.2 Implement TgzArchiveStorage composing TarArchiveStorage over ArchiveCodec
4.3 Implement openTarGz(source, opts) convenience defaulting to gzipCodec from drive-storage-gz
4.4 Validate ARCHIVE_CODEC_MISSING on construction without codec
4.5 Implement write path (codec-encode tar bytes back to host)
4.6 Register TGZ_* error codes, propagate inner tar/codec errors with chain
4.7 Run runArchiveConformance with gzipCodec
4.8 Co-located .md docs per implementation file
4.9 100% coverage + lint + typecheck green
4.10 Regenerate MANIFEST

5.1 Scaffold packages/drive/drive-storage-zip/
5.2 Implement EOCD + Central Directory parser, ZIP64 EOCD locator/record handling
5.3 Implement Local File Header reader, deflate decode via fflate
5.4 Implement WinZip AE-2 AES-256 decrypt with PBKDF2 key derivation
5.5 Implement split-zip volume reassembly via resolveSibling, validate volume signatures
5.6 Implement ZipArchiveStorage DriveStorage view
5.7 Implement write path: append local headers + rebuild central directory + EOCD on flush
5.8 Block AES write with ZIP_AES_WRITE_UNSUPPORTED (deferred to v0.2.0)
5.9 Implement CRC32 validation, raise ZIP_CRC_MISMATCH
5.10 Register ZIP_* error codes
5.11 Run runArchiveConformance
5.12 Co-located .md docs per implementation file
5.13 100% coverage + lint + typecheck green
5.14 Regenerate MANIFEST

6.1 Scaffold packages/drive/drive-storage-7z/
6.2 Benchmark wasm LZMA vs lzma-native on 100MB archive; record decision in package README
6.3 Implement 7z trailing header parser, EncodedHeader decode path
6.4 Implement LZMA + LZMA2 decompression
6.5 Implement BCJ, BCJ2, Delta, ARM/X86/SPARC filter chain
6.6 Implement multi-volume reassembly (.7z.NNN) via resolveSibling
6.7 Implement 7zAES header + content encryption with password hook
6.8 Implement SevenZipArchiveStorage DriveStorage view
6.9 Implement write path: re-encode affected folders + rewrite trailing header
6.10 Register SEVENZ_* error codes
6.11 Run runArchiveConformance
6.12 Co-located .md docs per implementation file
6.13 100% coverage + lint + typecheck green
6.14 Regenerate MANIFEST

7.1 Scaffold packages/drive/drive-storage-rar/ with engines.node + browser stub
7.2 Vendor wasm unrar (permissive license) or wire native binding; record license attribution in README
7.3 Implement RAR4 + RAR5 signature detection and version routing
7.4 Implement multi-volume reassembly: RAR5 .partN.rar + RAR4 .r00...r99 via resolveSibling
7.5 Implement encrypted-header and per-entry-encrypted reads with password hook
7.6 Implement RarArchiveStorage DriveStorage view; reject any non-read-only mode in constructor
7.7 Implement browser stub that throws RAR_UNAVAILABLE_IN_BROWSER for every entry point
7.8 Register RAR_* error codes
7.9 Run runArchiveConformance (read-only subset)
7.10 Co-located .md docs per implementation file
7.11 100% coverage + lint + typecheck green
7.12 Regenerate MANIFEST

8.1 Wire openArchiveStorage end-to-end test fixture using a real .zip, .tar, .gz, .tar.gz, .rar, .7z and a split-zip set
8.2 Add an integration test demonstrating new Drive(openArchiveStorage(...)) for each format
8.3 Update openspec/specs/drive/spec.md only if drive-side contract clarification is needed (likely no change — DriveStorage view already satisfied)
8.4 Run bunx turbo lint typecheck test across all seven new packages and ensure green
8.5 Run bunx turbo test:coverage across all seven packages and confirm 100% coverage on touched modules
8.6 Final MANIFEST.md regeneration + commit
8.7 Archive change to openspec/archive/<yyyy-mm-dd>-add-drive-storage-archive/ per repo workflow