Add persistent metadata cache for binary resolution

[pirate]

Summary

This PR introduces a persistent on-disk JSON cache for binary resolution metadata, dramatically improving cold-start performance by avoiding redundant binary --version calls (~100ms each). For projects managing 20+ binaries, this reduces startup time from 2+ seconds to near-instant on cache hits.

Key Changes

• New metadata_cache.py module: Implements BinaryMetadataCache class with:

  • get(): Retrieve cached (abspath, version, sha256) with validation
  • set(): Store resolved metadata with file fingerprinting (mtime + size)
  • invalidate(): Remove specific entries after install/update/uninstall
  • prune_stale(): Clean up entries for deleted/modified binaries
  • 7-day TTL with automatic expiration
  • File integrity checks to detect stale entries

• Unified cache directory infrastructure in base_types.py:

  • New ABX_PKG_CACHE_DIR and DEFAULT_CACHE_DIR constants
  • New abx_pkg_cache_dir_default() function with env var precedence:
    1. ABX_PKG_<PROVIDER>_CACHE_DIR (most specific)
    2. ABX_PKG_CACHE_DIR / <provider>
    3. user_cache_path("abx-pkg") / <provider> (fallback)

• Integration in binprovider.py:

  • load() checks persistent cache before expensive version resolution
  • install() and load() persist results to cache after successful resolution
  • invalidate_cache() clears both in-memory and persistent caches

• Provider updates (pip, npm, uv, pnpm, bun, deno, yarn):

  • Replaced hardcoded USER_CACHE_PATH logic with abx_pkg_cache_dir_default()
  • Simplified cache directory initialization using Field(default_factory=...)
  • Added detect_cache_arg() validator to derive cache arguments per-instance
  • uv: Added --link-mode=hardlink for near-instant installs from cached wheels

• Public API exports in __init__.py:

  • Exposed BinaryMetadataCache, metadata_cache, ABX_PKG_CACHE_DIR, and related utilities

Implementation Details

• Thread-safety: Cache is not thread-safe but safe for concurrent processes (worst case is stale read/lost write, both harmless)
• File fingerprinting: Uses (mtime, size) tuple to detect binary changes; allows 0.01s mtime tolerance for filesystem precision
• Graceful degradation: All cache operations are advisory; callers always fall back to live resolution on cache miss
• Atomic writes: Uses temp file + rename pattern to prevent corruption
• Error handling: Silently ignores cache I/O errors; cache is purely a performance optimization

https://claude.ai/code/session_018Jkv9vUDZyMqE5AYY1r9Fh

---

---

Summary by cubic

Adds a persistent on-disk metadata cache for binary resolution and unifies provider download caches, cutting cold-start time by avoiding repeated --version calls and enabling faster installs from shared caches.

• New Features

  • Added BinaryMetadataCache (JSON store with 7-day TTL, mtime+size validation, malformed-entry guards, atomic writes).
  • Integrated cache into load()/install()/update(); invalidate_cache() now clears in-memory and on-disk entries.
  • Enabled uv with --link-mode=hardlink for near-instant installs from cached wheels.
  • Exported BinaryMetadataCache, metadata_cache, ABX_PKG_CACHE_DIR, DEFAULT_CACHE_DIR, abx_pkg_cache_dir_default.

• Refactors

  • Unified cache dir: ~/.cache/abx-pkg/<provider> with env precedence ABX_PKG_<PROVIDER>_CACHE_DIR > ABX_PKG_CACHE_DIR > default.
  • Updated pip, npm, pnpm, yarn, bun, deno, uv to use the unified cache and derive cache args per instance; updated uv.lock.
  • Updated README with cache-directory controls, env var precedence, and new provider defaults.

^{Written for commit 3e415d4. Summary will update on new commits.}