feat(cache): add tar.gz pack/unpack helpers for remote-cache artifacts

[Exelord]

Summary

Pure tar+gzip helpers used by the upcoming LayeredCache to bridge the v10 on-disk layout and the Turbo /v8/artifacts wire body.

packArchive(stageDir): Promise<Uint8Array>        // tar -cz, returns bytes
unpackArchive(buf, destDir): Promise<void>        // tar -xz from stdin, mkdir -p destDir
packAndDiscard(stageDir): Promise<Uint8Array>     // pack then rm -rf the stage
tarPath(...segs): string                          // POSIX-safe path join
uniqueStageDir(parent, prefix): string            // pid+timestamp suffix

Implementation note: shells out to system tar via Bun.spawn — streaming stdin/stdout, no temp files for the archive bytes themselves. tar ships with every supported platform (GNU/BSD on Linux/Mac, MS-bundled on Windows 10+), so this avoids adding a JS tar dep.

What this enables (PR #11b)

The caller will build a stage dir matching the design doc layout:

stage/
  meta.json
  outputs/
    <project-relative paths>

…and packArchive(stage) becomes the PUT body. On GET, unpackArchive(body, stage) reproduces the same tree, which the LayeredCache then materializes into the v10 local layout (DB row + <hash>/<rel paths> + logs/<hash>.{stdout,stderr}).

Test plan

• bun run format:check — clean
• bun run lint — clean
• bun test src/ — 209 / 209 (was 197; +12)

New tests (src/cache-archive.test.ts)

• Round-trip: stage with meta.json + outputs/ survives pack→unpack with identical content.
• Binary preservation: 256-byte all-values blob compares byte-for-byte.
• Empty stage dirs pack and unpack cleanly.
• Deep tree (6 levels) survives the round-trip.
• unpackArchive creates destDir if missing.
• packArchive rejects on missing source.
• unpackArchive rejects corrupt tarballs.
• Accepts ArrayBuffer and Uint8Array inputs.
• tarPath: backslash normalization, double-slash collapse.

https://claude.ai/code/session_016HXj6HW6bxSn8EYuKcxTD9

---

Generated by Claude Code