feat(cache): add filesystem-backed cache with TTL expiration and size-limited GC

Implement a cache module with CacheConfig and Cache structs supporting
read/write (string and binary), atomic writes via temp+rename, TTL-based
expiration, and size-limited garbage collection. Wire the repo cache into
packagist.rs and resolver.rs for API response caching, and the files
cache into downloader.rs for dist archive caching. Implement the
clear-cache command with full clear and --gc modes. All existing call
sites pass None for backward compatibility.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

7 files changed, 66 insertions, 9 deletions

diff --git a/crates/mozart/src/commands/clear_cache.rs b/crates/mozart/src/commands/clear_cache.rs
index 638de06..819ca9f 100644
--- a/crates/mozart/src/commands/clear_cache.rs
+++ b/crates/mozart/src/commands/clear_cache.rs
@@ -1,3 +1,4 @@
+use crate::cache::{Cache, build_cache_config};
 use clap::Args;
 
 #[derive(Args)]
@@ -7,6 +8,45 @@ pub struct ClearCacheArgs {
     pub gc: bool,
 }
 
-pub fn execute(_args: &ClearCacheArgs, _cli: &super::Cli) -> anyhow::Result<()> {
-    todo!()
+pub fn execute(args: &ClearCacheArgs, cli: &super::Cli) -> anyhow::Result<()> {
+    let config = build_cache_config(cli);
+
+    if args.gc {
+        // Run GC only (probabilistic under normal circumstances, but forced here)
+        let repo_cache = Cache::repo(&config);
+        let files_cache = Cache::files(&config);
+
+        repo_cache.gc(config.cache_ttl, u64::MAX)?;
+        files_cache.gc(config.cache_files_ttl, config.cache_files_maxsize)?;
+
+        eprintln!("Cache garbage collection complete.");
+        eprintln!("Cache directory: {}", config.cache_dir.display());
+    } else {
+        // Full clear of all cache directories
+        let repo_cache = Cache::repo(&config);
+        let files_cache = Cache::files(&config);
+        repo_cache.clear()?;
+        files_cache.clear()?;
+        // Clear anything else at the root that isn't covered by sub-caches
+        if config.cache_dir.exists() {
+            for entry in std::fs::read_dir(&config.cache_dir)? {
+                let entry = entry?;
+                let path = entry.path();
+                // Skip repo/files subdirs (already cleared above)
+                if path == config.cache_files_dir || path == config.cache_repo_dir {
+                    continue;
+                }
+                if path.is_file() {
+                    std::fs::remove_file(&path)?;
+                } else if path.is_dir() {
+                    std::fs::remove_dir_all(&path)?;
+                }
+            }
+        }
+
+        eprintln!("Cache cleared.");
+        eprintln!("Cache directory: {}", config.cache_dir.display());
+    }
+
+    Ok(())
 }
diff --git a/crates/mozart/src/commands/install.rs b/crates/mozart/src/commands/install.rs
index 53b827a..b5f9142 100644
--- a/crates/mozart/src/commands/install.rs
+++ b/crates/mozart/src/commands/install.rs
@@ -417,6 +417,7 @@ pub fn install_from_lock(
                 vendor_dir,
                 &pkg.name,
                 Some(&mut progress),
+                None,
             )?;
 
             progress.finish();
diff --git a/crates/mozart/src/commands/outdated.rs b/crates/mozart/src/commands/outdated.rs
index f517871..f355e09 100644
--- a/crates/mozart/src/commands/outdated.rs
+++ b/crates/mozart/src/commands/outdated.rs
@@ -332,7 +332,7 @@ fn fetch_latest_version(name: &str) -> anyhow::Result<PackageInfo> {
     use crate::package::Stability;
     use crate::version::find_best_candidate;
 
-    let versions = crate::packagist::fetch_package_versions(name)?;
+    let versions = crate::packagist::fetch_package_versions(name, None)?;
     let best = find_best_candidate(&versions, Stability::Stable)
         .ok_or_else(|| anyhow::anyhow!("No stable version found for {name}"))?;
 
diff --git a/crates/mozart/src/commands/remove.rs b/crates/mozart/src/commands/remove.rs
index 3010547..ecfbba8 100644
--- a/crates/mozart/src/commands/remove.rs
+++ b/crates/mozart/src/commands/remove.rs
@@ -268,6 +268,7 @@ pub fn execute(args: &RemoveArgs, cli: &super::Cli) -> anyhow::Result<()> {
         platform: PlatformConfig::new(),
         ignore_platform_reqs: args.ignore_platform_reqs,
         ignore_platform_req_list: args.ignore_platform_req.clone(),
+        repo_cache: None,
     };
 
     // Print header messages
@@ -365,6 +366,7 @@ pub fn execute(args: &RemoveArgs, cli: &super::Cli) -> anyhow::Result<()> {
         composer_json_content: composer_json_content.clone(),
         composer_json: raw.clone(),
         include_dev: dev_mode,
+        repo_cache: None,
     })?;
 
     // Compute and print change report
@@ -701,6 +703,7 @@ mod tests {
             platform: crate::resolver::PlatformConfig::new(),
             ignore_platform_reqs: false,
             ignore_platform_req_list: vec![],
+            repo_cache: None,
         };
         let resolved = resolve(&request).expect("initial resolution should succeed");
         let initial_lock = generate_lock_file(&LockFileGenerationRequest {
@@ -708,6 +711,7 @@ mod tests {
             composer_json_content: content.to_string(),
             composer_json: raw.clone(),
             include_dev: false,
+            repo_cache: None,
         })
         .expect("initial lock file generation should succeed");
         initial_lock
@@ -730,6 +734,7 @@ mod tests {
             platform: crate::resolver::PlatformConfig::new(),
             ignore_platform_reqs: false,
             ignore_platform_req_list: vec![],
+            repo_cache: None,
         };
         let resolved2 = resolve(&request2).expect("post-remove resolution should succeed");
 
@@ -739,6 +744,7 @@ mod tests {
             composer_json_content: composer_json_content2,
             composer_json: raw,
             include_dev: false,
+            repo_cache: None,
         })
         .expect("post-remove lock file generation should succeed");
 
diff --git a/crates/mozart/src/commands/require.rs b/crates/mozart/src/commands/require.rs
index 128e4a9..7709f86 100644
--- a/crates/mozart/src/commands/require.rs
+++ b/crates/mozart/src/commands/require.rs
@@ -276,7 +276,7 @@ fn interactive_search_packages(
                 ))
             );
 
-            match packagist::fetch_package_versions(&package_name) {
+            match packagist::fetch_package_versions(&package_name, None) {
                 Ok(versions) => {
                     match version::find_best_candidate(&versions, preferred_stability) {
                         Some(best) => {
@@ -469,7 +469,7 @@ pub fn execute(args: &RequireArgs, cli: &super::Cli) -> anyhow::Result<()> {
                     ))
                 );
 
-                let versions = packagist::fetch_package_versions(&name)?;
+                let versions = packagist::fetch_package_versions(&name, None)?;
                 let best = version::find_best_candidate(&versions, preferred_stability)
                     .ok_or_else(|| {
                         anyhow::anyhow!(
@@ -596,6 +596,7 @@ pub fn execute(args: &RequireArgs, cli: &super::Cli) -> anyhow::Result<()> {
         platform: PlatformConfig::new(),
         ignore_platform_reqs: args.ignore_platform_reqs,
         ignore_platform_req_list: args.ignore_platform_req.clone(),
+        repo_cache: None,
     };
 
     // Print header messages
@@ -673,6 +674,7 @@ pub fn execute(args: &RequireArgs, cli: &super::Cli) -> anyhow::Result<()> {
         composer_json_content: composer_json_content.clone(),
         composer_json: raw.clone(),
         include_dev: dev_mode,
+        repo_cache: None,
     })?;
 
     // Compute and print change report
@@ -934,6 +936,7 @@ mod tests {
             platform: PlatformConfig::new(),
             ignore_platform_reqs: false,
             ignore_platform_req_list: vec![],
+            repo_cache: None,
         };
 
         let resolved = resolver::resolve(&request).expect("Resolution should succeed");
@@ -945,6 +948,7 @@ mod tests {
             composer_json_content: composer_json_content.to_string(),
             composer_json,
             include_dev: false,
+            repo_cache: None,
         })
         .expect("Lock file generation should succeed");
 
@@ -980,6 +984,7 @@ mod tests {
             platform: PlatformConfig::new(),
             ignore_platform_reqs: false,
             ignore_platform_req_list: vec![],
+            repo_cache: None,
         };
 
         let resolved = resolver::resolve(&request).expect("Resolution should succeed");
@@ -988,6 +993,7 @@ mod tests {
             composer_json_content: content.to_string(),
             composer_json: raw,
             include_dev: false,
+            repo_cache: None,
         })
         .expect("Lock file generation should succeed");
 
diff --git a/crates/mozart/src/commands/show.rs b/crates/mozart/src/commands/show.rs
index ff157e0..ab013e3 100644
--- a/crates/mozart/src/commands/show.rs
+++ b/crates/mozart/src/commands/show.rs
@@ -468,7 +468,7 @@ fn fetch_latest_for_package(name: &str) -> anyhow::Result<LatestInfo> {
     use crate::package::Stability;
     use crate::version::find_best_candidate;
 
-    let versions = crate::packagist::fetch_package_versions(name)?;
+    let versions = crate::packagist::fetch_package_versions(name, None)?;
     let best = find_best_candidate(&versions, Stability::Stable)
         .ok_or_else(|| anyhow::anyhow!("No stable version found for {name}"))?;
 
@@ -1447,7 +1447,7 @@ fn show_available(args: &ShowArgs, working_dir: &Path) -> anyhow::Result<()> {
             if is_platform_package(&pkg.name) {
                 continue;
             }
-            match crate::packagist::fetch_package_versions(&pkg.name) {
+            match crate::packagist::fetch_package_versions(&pkg.name, None) {
                 Ok(versions) => {
                     let version_strings: Vec<String> =
                         versions.iter().map(|v| v.version.clone()).collect();
@@ -1482,7 +1482,7 @@ fn show_available(args: &ShowArgs, working_dir: &Path) -> anyhow::Result<()> {
 }
 
 fn show_available_versions(pkg_name: &str, args: &ShowArgs) -> anyhow::Result<()> {
-    let versions = crate::packagist::fetch_package_versions(pkg_name)?;
+    let versions = crate::packagist::fetch_package_versions(pkg_name, None)?;
     if versions.is_empty() {
         println!("No versions found for {pkg_name}");
         return Ok(());
@@ -1510,7 +1510,7 @@ fn show_available_versions(pkg_name: &str, args: &ShowArgs) -> anyhow::Result<()
 }
 
 fn show_available_versions_inline(pkg_name: &str) {
-    match crate::packagist::fetch_package_versions(pkg_name) {
+    match crate::packagist::fetch_package_versions(pkg_name, None) {
         Ok(versions) => {
             if versions.is_empty() {
                 println!("{}: no versions found", crate::console::info(pkg_name));
diff --git a/crates/mozart/src/commands/update.rs b/crates/mozart/src/commands/update.rs
index fc9400a..930c458 100644
--- a/crates/mozart/src/commands/update.rs
+++ b/crates/mozart/src/commands/update.rs
@@ -735,6 +735,7 @@ pub fn execute(args: &UpdateArgs, cli: &super::Cli) -> anyhow::Result<()> {
         platform: PlatformConfig::new(),
         ignore_platform_reqs: args.ignore_platform_reqs,
         ignore_platform_req_list: args.ignore_platform_req.clone(),
+        repo_cache: None,
     };
 
     // Step 6: Print header and run resolver
@@ -872,6 +873,7 @@ pub fn execute(args: &UpdateArgs, cli: &super::Cli) -> anyhow::Result<()> {
         composer_json_content: composer_json_content.clone(),
         composer_json: composer_json.clone(),
         include_dev: dev_mode,
+        repo_cache: None,
     })?;
 
     // Step 10: Compute and print change report
@@ -1677,6 +1679,7 @@ mod tests {
             platform: PlatformConfig::new(),
             ignore_platform_reqs: false,
             ignore_platform_req_list: vec![],
+            repo_cache: None,
         };
 
         let resolved = resolve(&request).expect("Resolution should succeed");
@@ -1688,6 +1691,7 @@ mod tests {
             composer_json_content: composer_json_content.to_string(),
             composer_json,
             include_dev: false,
+            repo_cache: None,
         })
         .expect("Lock file generation should succeed");