libcontext 0.4.0__tar.gz → 0.6.0__tar.gz

{libcontext-0.4.0 → libcontext-0.6.0}/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-03-23
+
+### Added
+
+- **`--version` flag**: `libctx --version` displays the installed version, read from package metadata.
+- **`cache list`**: new subcommand showing cached packages with version, size, and relative age.
+- **`cache clear <package>`**: selective cache clearing by package name (normalises hyphens and case). Without argument, `cache clear` still removes all entries as before.
+
 ## [0.4.0] - 2026-03-23
 
 ### Added
@@ -93,7 +101,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Free-form `extra_context` field for library authors.
 - Python API for programmatic usage (`collect_package`, `render_package`).
 
-[Unreleased]: https://github.com/Syclaw/libcontext/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/Syclaw/libcontext/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/Syclaw/libcontext/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/Syclaw/libcontext/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/Syclaw/libcontext/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/Syclaw/libcontext/compare/v0.1.0...v0.2.0

{libcontext-0.4.0 → libcontext-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: libcontext
-Version: 0.4.0
+Version: 0.6.0
 Summary: Generate optimized LLM context from Python library APIs — CLI, skill, and MCP server
 Project-URL: Homepage, https://github.com/Syclaw/libcontext
 Project-URL: Repository, https://github.com/Syclaw/libcontext
@@ -37,30 +37,38 @@ Description-Content-Type: text/markdown
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![Typed](https://img.shields.io/badge/typed-mypy-blue.svg)](https://mypy-lang.org/)
 
-> Make your AI coding assistant aware of any Python library's API — on demand, not always-on.
+> Context-efficient API references for LLM toolchains — structured, on-demand, not always-on.
 
-**libcontext** inspects any installed Python package via static AST analysis (no code execution) and generates compact Markdown API references. It integrates with Claude Code (via a `/lib` skill) and VS Code Copilot (via an MCP server) to provide **progressive disclosure** — only loading API context when you actually need it, avoiding context window pollution.
+**libcontext** inspects any installed Python package via static AST analysis (no code execution) and generates compact Markdown API references. It integrates with Claude Code, GitHub Copilot (via a `/lib` skill), and VS Code / Cursor (via an MCP server) to provide **progressive disclosure** — only loading API context when you actually need it, avoiding context window pollution.
 
 ## Why This Exists
 
-When you ask an AI assistant how to use a library, the quality of the output depends entirely on what the model knows about that library's API. For many real-world scenarios, the model is working blind:
+LLMs can often use popular libraries correctly from training data alone. For well-known packages like `requests` or `flask`, libcontext adds little value. The real problems arise in specific scenarios:
 
 - **Internal / private libraries** — Zero training data exists. The model has never seen the API.
-- **Niche open-source packages** — Sparse or outdated training data leads to hallucinated methods and wrong signatures.
+- **Niche open-source packages** — Sparse or outdated training data leads to hallucinated methods and wrong signatures. GPT-4o achieves only 38% valid invocations on low-frequency APIs ([Amazon Science, ICSE 2025](https://www.amazon.science/publications/on-mitigating-code-llm-hallucinations-with-api-documentation)).
 - **New versions of any library** — Training data has a cutoff. The model knows v2, you're using v3.
 
-Dumping entire API references into always-on instruction files (like `copilot-instructions.md` or `CLAUDE.md`) wastes context window on every interaction — even when you're not using that library. Research ([ReadMe.LLM, UC Berkeley 2025](https://arxiv.org/abs/2504.15870)) confirms that excessive context triggers hallucinations and degrades output quality.
+Even when an LLM could read source files directly, structured API summaries are more context-efficient: providing API documentation via retrieval improves pass rates by 83–220% compared to no documentation, while consuming far fewer tokens than raw source code ([arXiv 2503.15231, March 2025](https://arxiv.org/abs/2503.15231)).
 
-libcontext solves this with **progressive disclosure**: overview first, then drill into specific modules only when needed.
+Dumping entire API references into always-on instruction files wastes context window on every interaction. Selective retrieval outperforms always-on injection — always-on docs actually hurt performance on well-known APIs ([Amazon Science, ICSE 2025](https://www.amazon.science/publications/on-mitigating-code-llm-hallucinations-with-api-documentation)).
+
+libcontext addresses this with **progressive disclosure**: overview first, then drill into specific modules only when needed.
 
 ## When libcontext makes the biggest difference
 
 | Scenario | Impact | Why |
 |---|---|---|
-| **Internal / private libraries** | Critical | Zero training data exists for proprietary code |
-| **Niche open-source packages** | High | Sparse training data leads to hallucinated methods |
+| **Internal / private libraries** | Critical | Zero training data — the model has never seen the API |
+| **Niche open-source packages** | High | Sparse training data; 19.7% of LLM package suggestions are hallucinated ([USENIX Security 2025](https://www.usenix.org/publications/loginonline/we-have-package-you-comprehensive-analysis-package-hallucinations-code)) |
 | **New versions of any library** | High | Training cutoff — the LLM knows v2, you're using v3 |
-| **Popular, stable libraries** | Low | The LLM already has good knowledge from training data |
+| **Popular, stable libraries** | Low | The LLM already has good knowledge from training data — libcontext adds little here |
+
+### What libcontext does NOT do
+
+- **Replace reading source code** — LLMs with tool access (Claude Code, Cursor) can read files directly. For popular libraries, that's often sufficient.
+- **Guarantee correctness** — Even with perfect API docs, LLMs still make errors. Research shows pass rates of 74–91% with target documentation, not 100% ([arXiv 2503.15231](https://arxiv.org/abs/2503.15231)).
+- **Provide usage examples** — libcontext extracts signatures and docstrings, not example code. Research indicates examples have the highest impact on code generation quality.
 
 ## Quick Start
 
@@ -99,7 +107,7 @@ libctx inspect requests   libctx inspect requests     libctx inspect requests
   (no signatures)           for one module              across all modules
 ```
 
-The `/lib` skill (Claude Code) and MCP server (VS Code / Cursor) automate this workflow — the AI assistant decides what to inspect based on the task at hand.
+The `/lib` skill (Claude Code, GitHub Copilot) and MCP server (Claude Code, VS Code, Cursor) automate this workflow — the AI assistant decides what to inspect based on the task at hand.
 
 ### Direct CLI Usage
 
@@ -138,8 +146,10 @@ libctx diff old.json new.json
 # Bypass disk cache
 libctx inspect requests --no-cache
 
-# Clear all cached API data
-libctx cache clear
+# Cache management
+libctx cache list               # show cached packages with size and age
+libctx cache clear               # clear all cached API data
+libctx cache clear requests      # clear only the entries for one package
 ```
 
 ### AST Analysis
@@ -322,7 +332,7 @@ All async operations use httpx internally.
 | `diff.py` | API diff between two package versions with breaking change detection |
 | `cache.py` | Persistent disk cache with mtime/file-count invalidation and LRU eviction |
 | `cli.py` | CLI entry point — `inspect`, `install`, `diff`, and `cache` subcommands |
-| `mcp_server.py` | MCP server for VS Code / Cursor integration (optional) |
+| `mcp_server.py` | MCP server for Claude Code / VS Code / Cursor integration (optional) |
 
 ## Development
 

{libcontext-0.4.0 → libcontext-0.6.0}/README.md

@@ -8,30 +8,38 @@
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![Typed](https://img.shields.io/badge/typed-mypy-blue.svg)](https://mypy-lang.org/)
 
-> Make your AI coding assistant aware of any Python library's API — on demand, not always-on.
+> Context-efficient API references for LLM toolchains — structured, on-demand, not always-on.
 
-**libcontext** inspects any installed Python package via static AST analysis (no code execution) and generates compact Markdown API references. It integrates with Claude Code (via a `/lib` skill) and VS Code Copilot (via an MCP server) to provide **progressive disclosure** — only loading API context when you actually need it, avoiding context window pollution.
+**libcontext** inspects any installed Python package via static AST analysis (no code execution) and generates compact Markdown API references. It integrates with Claude Code, GitHub Copilot (via a `/lib` skill), and VS Code / Cursor (via an MCP server) to provide **progressive disclosure** — only loading API context when you actually need it, avoiding context window pollution.
 
 ## Why This Exists
 
-When you ask an AI assistant how to use a library, the quality of the output depends entirely on what the model knows about that library's API. For many real-world scenarios, the model is working blind:
+LLMs can often use popular libraries correctly from training data alone. For well-known packages like `requests` or `flask`, libcontext adds little value. The real problems arise in specific scenarios:
 
 - **Internal / private libraries** — Zero training data exists. The model has never seen the API.
-- **Niche open-source packages** — Sparse or outdated training data leads to hallucinated methods and wrong signatures.
+- **Niche open-source packages** — Sparse or outdated training data leads to hallucinated methods and wrong signatures. GPT-4o achieves only 38% valid invocations on low-frequency APIs ([Amazon Science, ICSE 2025](https://www.amazon.science/publications/on-mitigating-code-llm-hallucinations-with-api-documentation)).
 - **New versions of any library** — Training data has a cutoff. The model knows v2, you're using v3.
 
-Dumping entire API references into always-on instruction files (like `copilot-instructions.md` or `CLAUDE.md`) wastes context window on every interaction — even when you're not using that library. Research ([ReadMe.LLM, UC Berkeley 2025](https://arxiv.org/abs/2504.15870)) confirms that excessive context triggers hallucinations and degrades output quality.
+Even when an LLM could read source files directly, structured API summaries are more context-efficient: providing API documentation via retrieval improves pass rates by 83–220% compared to no documentation, while consuming far fewer tokens than raw source code ([arXiv 2503.15231, March 2025](https://arxiv.org/abs/2503.15231)).
 
-libcontext solves this with **progressive disclosure**: overview first, then drill into specific modules only when needed.
+Dumping entire API references into always-on instruction files wastes context window on every interaction. Selective retrieval outperforms always-on injection — always-on docs actually hurt performance on well-known APIs ([Amazon Science, ICSE 2025](https://www.amazon.science/publications/on-mitigating-code-llm-hallucinations-with-api-documentation)).
+
+libcontext addresses this with **progressive disclosure**: overview first, then drill into specific modules only when needed.
 
 ## When libcontext makes the biggest difference
 
 | Scenario | Impact | Why |
 |---|---|---|
-| **Internal / private libraries** | Critical | Zero training data exists for proprietary code |
-| **Niche open-source packages** | High | Sparse training data leads to hallucinated methods |
+| **Internal / private libraries** | Critical | Zero training data — the model has never seen the API |
+| **Niche open-source packages** | High | Sparse training data; 19.7% of LLM package suggestions are hallucinated ([USENIX Security 2025](https://www.usenix.org/publications/loginonline/we-have-package-you-comprehensive-analysis-package-hallucinations-code)) |
 | **New versions of any library** | High | Training cutoff — the LLM knows v2, you're using v3 |
-| **Popular, stable libraries** | Low | The LLM already has good knowledge from training data |
+| **Popular, stable libraries** | Low | The LLM already has good knowledge from training data — libcontext adds little here |
+
+### What libcontext does NOT do
+
+- **Replace reading source code** — LLMs with tool access (Claude Code, Cursor) can read files directly. For popular libraries, that's often sufficient.
+- **Guarantee correctness** — Even with perfect API docs, LLMs still make errors. Research shows pass rates of 74–91% with target documentation, not 100% ([arXiv 2503.15231](https://arxiv.org/abs/2503.15231)).
+- **Provide usage examples** — libcontext extracts signatures and docstrings, not example code. Research indicates examples have the highest impact on code generation quality.
 
 ## Quick Start
 
@@ -70,7 +78,7 @@ libctx inspect requests   libctx inspect requests     libctx inspect requests
   (no signatures)           for one module              across all modules
 ```
 
-The `/lib` skill (Claude Code) and MCP server (VS Code / Cursor) automate this workflow — the AI assistant decides what to inspect based on the task at hand.
+The `/lib` skill (Claude Code, GitHub Copilot) and MCP server (Claude Code, VS Code, Cursor) automate this workflow — the AI assistant decides what to inspect based on the task at hand.
 
 ### Direct CLI Usage
 
@@ -109,8 +117,10 @@ libctx diff old.json new.json
 # Bypass disk cache
 libctx inspect requests --no-cache
 
-# Clear all cached API data
-libctx cache clear
+# Cache management
+libctx cache list               # show cached packages with size and age
+libctx cache clear               # clear all cached API data
+libctx cache clear requests      # clear only the entries for one package
 ```
 
 ### AST Analysis
@@ -293,7 +303,7 @@ All async operations use httpx internally.
 | `diff.py` | API diff between two package versions with breaking change detection |
 | `cache.py` | Persistent disk cache with mtime/file-count invalidation and LRU eviction |
 | `cli.py` | CLI entry point — `inspect`, `install`, `diff`, and `cache` subcommands |
-| `mcp_server.py` | MCP server for VS Code / Cursor integration (optional) |
+| `mcp_server.py` | MCP server for Claude Code / VS Code / Cursor integration (optional) |
 
 ## Development
 

{libcontext-0.4.0 → libcontext-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "libcontext"
-version = "0.4.0"
+version = "0.6.0"
 description = "Generate optimized LLM context from Python library APIs — CLI, skill, and MCP server"
 readme = "README.md"
 license = "MIT"

{libcontext-0.4.0 → libcontext-0.6.0}/src/libcontext/cache.py

@@ -258,6 +258,74 @@ def clear_all() -> int:
     return count
 
 
+def clear_package(package_name: str) -> int:
+    """Remove cached entries matching a package name.
+
+    Matches entries whose embedded ``name`` field equals *package_name*
+    (case-insensitive, normalised with hyphens → underscores).
+
+    Args:
+        package_name: Package name to clear.
+
+    Returns:
+        Number of entries removed.
+    """
+    target = package_name.lower().replace("-", "_")
+    cache_dir = _get_cache_dir()
+    count = 0
+    for f in cache_dir.glob("*.json"):
+        try:
+            raw = json.loads(f.read_text(encoding="utf-8"))
+            data = _deserialize_envelope(raw)
+        except (json.JSONDecodeError, ValueError, OSError):
+            continue
+        name = data.get("name", "")
+        if isinstance(name, str) and name.lower().replace("-", "_") == target:
+            _safe_delete(f)
+            count += 1
+    return count
+
+
+@dataclass
+class CacheEntry:
+    """Summary of a single cache entry for display."""
+
+    package: str
+    version: str
+    cached_at: str
+    size_bytes: int
+    file_path: Path
+
+
+def list_entries() -> list[CacheEntry]:
+    """List all cached API snapshots with metadata.
+
+    Returns:
+        List of :class:`CacheEntry` sorted by package name then version.
+    """
+    cache_dir = _get_cache_dir()
+    entries: list[CacheEntry] = []
+    for f in cache_dir.glob("*.json"):
+        try:
+            size = f.stat().st_size
+            raw = json.loads(f.read_text(encoding="utf-8"))
+            data = _deserialize_envelope(raw)
+        except (json.JSONDecodeError, ValueError, OSError):
+            continue
+        meta = data.get("_cache_meta", {})
+        entries.append(
+            CacheEntry(
+                package=data.get("name", "unknown"),
+                version=data.get("version", "unknown"),
+                cached_at=meta.get("cached_at", "unknown"),
+                size_bytes=size,
+                file_path=f,
+            )
+        )
+    entries.sort(key=lambda e: (e.package.lower(), e.version))
+    return entries
+
+
 def _cache_filename(
     package_name: str,
     version: str | None,

{libcontext-0.4.0 → libcontext-0.6.0}/src/libcontext/cli.py

@@ -1,6 +1,6 @@
 """CLI entry point for libcontext.
 
-Provides the ``libctx`` command with two subcommands:
+Provides the ``libctx`` command with subcommands:
 
 ``inspect``
     Generate LLM-optimised Markdown context from installed Python packages.
@@ -8,6 +8,12 @@ Provides the ``libctx`` command with two subcommands:
 ``install``
     Install libcontext integration files (skills, MCP) into the current project.
 
+``diff``
+    Compare two API snapshots and show what changed.
+
+``cache``
+    Manage the disk cache (``list``, ``clear``).
+
 Usage examples::
 
     libctx inspect requests
@@ -18,6 +24,12 @@ Usage examples::
     libctx install --skills
     libctx install --mcp --target vscode
     libctx install --all --target all
+
+    libctx diff old.json new.json
+
+    libctx cache list
+    libctx cache clear
+    libctx cache clear requests
 """
 
 from __future__ import annotations
@@ -54,6 +66,7 @@ from .renderer import (
 
 
 @click.group()
+@click.version_option(package_name="libcontext")
 def main() -> None:
     """Generate LLM-optimised context from Python library APIs."""
 
@@ -758,10 +771,68 @@ def cache() -> None:
 
 
 @cache.command()
-def clear() -> None:
-    """Remove all cached API snapshots."""
-    count = _cache.clear_all()
-    click.echo(f"Cleared {count} cache entries.")
+@click.argument("package", required=False, default=None)
+def clear(package: str | None) -> None:
+    """Remove cached API snapshots.
+
+    When PACKAGE is given, only entries for that package are removed.
+    Without arguments, all entries are cleared.
+    """
+    if package is not None:
+        count = _cache.clear_package(package)
+        label = f"for {package!r}" if count else f"no entries found for {package!r}"
+    else:
+        count = _cache.clear_all()
+        label = "cache entries" if count else "cache entries (already empty)"
+    click.echo(f"Cleared {count} {label}.")
+
+
+@cache.command(name="list")
+def list_() -> None:
+    """Show cached API snapshots."""
+    entries = _cache.list_entries()
+    if not entries:
+        click.echo("Cache is empty.")
+        return
+    total_bytes = 0
+    for entry in entries:
+        age = _format_age(entry.cached_at)
+        size = _format_size(entry.size_bytes)
+        click.echo(f"  {entry.package} {entry.version}  ({size}, {age})")
+        total_bytes += entry.size_bytes
+    click.echo(f"\n{len(entries)} entries, {_format_size(total_bytes)} total.")
+
+
+def _format_size(size_bytes: int) -> str:
+    """Format byte count as a human-readable string."""
+    if size_bytes < 1024:
+        return f"{size_bytes} B"
+    if size_bytes < 1024 * 1024:
+        return f"{size_bytes / 1024:.1f} kB"
+    return f"{size_bytes / (1024 * 1024):.1f} MB"
+
+
+def _format_age(iso_timestamp: str) -> str:
+    """Format an ISO timestamp as a relative age string."""
+    import datetime
+
+    try:
+        cached = datetime.datetime.fromisoformat(iso_timestamp)
+        now = datetime.datetime.now(tz=datetime.timezone.utc)
+        delta = now - cached
+        seconds = int(delta.total_seconds())
+        if seconds < 60:
+            return "just now"
+        if seconds < 3600:
+            m = seconds // 60
+            return f"{m}m ago"
+        if seconds < 86400:
+            h = seconds // 3600
+            return f"{h}h ago"
+        d = seconds // 86400
+        return f"{d}d ago"
+    except (ValueError, TypeError):
+        return "unknown age"
 
 
 # ---------------------------------------------------------------------------

{libcontext-0.4.0 → libcontext-0.6.0}/tests/test_cache.py

@@ -12,6 +12,8 @@ from libcontext.cache import (
     _evict_oldest,
     _get_cache_dir,
     clear_all,
+    clear_package,
+    list_entries,
     load,
     save,
 )
@@ -286,6 +288,166 @@ def test_clear_all_empty(tmp_path, monkeypatch):
     assert count == 0
 
 
+# ---------------------------------------------------------------------------
+# clear_package
+# ---------------------------------------------------------------------------
+
+
+def test_clear_package_removes_matching(tmp_path, monkeypatch):
+    """Only entries for the given package are removed."""
+    monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path))
+    monkeypatch.setattr("libcontext.cache.sys.platform", "linux")
+
+    src_dir = tmp_path / "src"
+    src_dir.mkdir()
+    (src_dir / "mod.py").write_text("# code")
+
+    pkg_a = PackageInfo(
+        name="alpha",
+        version="1.0.0",
+        modules=[ModuleInfo(name="alpha.core", functions=[FunctionInfo(name="f")])],
+    )
+    pkg_b = PackageInfo(
+        name="beta",
+        version="2.0.0",
+        modules=[ModuleInfo(name="beta.core", functions=[FunctionInfo(name="g")])],
+    )
+    save(pkg_a, src_dir)
+    save(pkg_b, src_dir)
+
+    count = clear_package("alpha")
+    assert count == 1
+
+    remaining = list_entries()
+    assert len(remaining) == 1
+    assert remaining[0].package == "beta"
+
+
+def test_clear_package_normalises_name(tmp_path, monkeypatch):
+    """Hyphens and case differences are normalised for matching."""
+    monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path))
+    monkeypatch.setattr("libcontext.cache.sys.platform", "linux")
+
+    src_dir = tmp_path / "src"
+    src_dir.mkdir()
+    (src_dir / "mod.py").write_text("# code")
+
+    pkg = PackageInfo(
+        name="my_package",
+        version="1.0.0",
+        modules=[ModuleInfo(name="my_package.core", functions=[])],
+    )
+    save(pkg, src_dir)
+
+    count = clear_package("My-Package")
+    assert count == 1
+
+
+def test_clear_package_no_match(tmp_path, monkeypatch):
+    monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path))
+    monkeypatch.setattr("libcontext.cache.sys.platform", "linux")
+    _get_cache_dir()
+
+    count = clear_package("nonexistent")
+    assert count == 0
+
+
+def test_clear_package_skips_corrupted(tmp_path, monkeypatch):
+    """Corrupted JSON files are skipped without crashing."""
+    monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path))
+    monkeypatch.setattr("libcontext.cache.sys.platform", "linux")
+
+    cache_dir = _get_cache_dir()
+    (cache_dir / "bad.json").write_text("not json", encoding="utf-8")
+
+    src_dir = tmp_path / "src"
+    src_dir.mkdir()
+    (src_dir / "mod.py").write_text("# code")
+
+    pkg = PackageInfo(
+        name="goodpkg",
+        version="1.0.0",
+        modules=[ModuleInfo(name="goodpkg.core", functions=[])],
+    )
+    save(pkg, src_dir)
+
+    count = clear_package("goodpkg")
+    assert count == 1
+    # Corrupted file still exists (not matched, not deleted)
+    assert (cache_dir / "bad.json").exists()
+
+
+# ---------------------------------------------------------------------------
+# list_entries
+# ---------------------------------------------------------------------------
+
+
+def test_list_entries_returns_saved_packages(tmp_path, monkeypatch):
+    monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path))
+    monkeypatch.setattr("libcontext.cache.sys.platform", "linux")
+
+    src_dir = tmp_path / "src"
+    src_dir.mkdir()
+    (src_dir / "mod.py").write_text("# code")
+
+    save(_make_pkg("1.0.0"), src_dir)
+
+    entries = list_entries()
+    assert len(entries) == 1
+    assert entries[0].package == "testpkg"
+    assert entries[0].version == "1.0.0"
+    assert entries[0].size_bytes > 0
+    assert entries[0].cached_at != "unknown"
+
+
+def test_list_entries_sorted_by_name(tmp_path, monkeypatch):
+    monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path))
+    monkeypatch.setattr("libcontext.cache.sys.platform", "linux")
+
+    src_dir = tmp_path / "src"
+    src_dir.mkdir()
+    (src_dir / "mod.py").write_text("# code")
+
+    for name in ("zeta", "alpha", "mid"):
+        pkg = PackageInfo(
+            name=name,
+            version="1.0.0",
+            modules=[ModuleInfo(name=f"{name}.core", functions=[])],
+        )
+        save(pkg, src_dir)
+
+    entries = list_entries()
+    names = [e.package for e in entries]
+    assert names == ["alpha", "mid", "zeta"]
+
+
+def test_list_entries_empty(tmp_path, monkeypatch):
+    monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path))
+    monkeypatch.setattr("libcontext.cache.sys.platform", "linux")
+    _get_cache_dir()
+
+    entries = list_entries()
+    assert entries == []
+
+
+def test_list_entries_skips_corrupted(tmp_path, monkeypatch):
+    """Corrupted files are silently skipped."""
+    monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path))
+    monkeypatch.setattr("libcontext.cache.sys.platform", "linux")
+
+    cache_dir = _get_cache_dir()
+    (cache_dir / "bad.json").write_text("not json", encoding="utf-8")
+
+    src_dir = tmp_path / "src"
+    src_dir.mkdir()
+    (src_dir / "mod.py").write_text("# code")
+    save(_make_pkg(), src_dir)
+
+    entries = list_entries()
+    assert len(entries) == 1
+    assert entries[0].package == "testpkg"
+
+
 # ---------------------------------------------------------------------------
 # _cache_filename
 # ---------------------------------------------------------------------------

{libcontext-0.4.0 → libcontext-0.6.0}/tests/test_cli.py

@@ -860,6 +860,152 @@ def test_cache_clear(tmp_path: Path, monkeypatch) -> None:
     assert "Cleared" in result.output
 
 
+def test_cache_clear_specific_package(tmp_path: Path, monkeypatch) -> None:
+    """``libctx cache clear <package>`` removes only that package."""
+    monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path))
+    monkeypatch.setattr("libcontext.cache.sys.platform", "linux")
+
+    from libcontext import cache as _c
+    from libcontext.models import FunctionInfo, ModuleInfo, PackageInfo
+
+    src = tmp_path / "src"
+    src.mkdir()
+    (src / "mod.py").write_text("# code")
+
+    for name in ("alpha", "beta"):
+        pkg = PackageInfo(
+            name=name,
+            version="1.0.0",
+            modules=[
+                ModuleInfo(name=f"{name}.core", functions=[FunctionInfo(name="f")])
+            ],
+        )
+        _c.save(pkg, src)
+
+    runner = CliRunner()
+    result = runner.invoke(main, ["cache", "clear", "alpha"])
+
+    assert result.exit_code == 0
+    assert "1" in result.output
+    assert "alpha" in result.output
+
+    remaining = _c.list_entries()
+    assert len(remaining) == 1
+    assert remaining[0].package == "beta"
+
+
+def test_cache_list_empty(tmp_path: Path, monkeypatch) -> None:
+    """``libctx cache list`` on empty cache shows message."""
+    monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path))
+    monkeypatch.setattr("libcontext.cache.sys.platform", "linux")
+
+    runner = CliRunner()
+    result = runner.invoke(main, ["cache", "list"])
+
+    assert result.exit_code == 0
+    assert "empty" in result.output.lower()
+
+
+def test_cache_list_shows_entries(tmp_path: Path, monkeypatch) -> None:
+    """``libctx cache list`` displays cached packages."""
+    monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path))
+    monkeypatch.setattr("libcontext.cache.sys.platform", "linux")
+
+    from libcontext import cache as _c
+    from libcontext.models import FunctionInfo, ModuleInfo, PackageInfo
+
+    src = tmp_path / "src"
+    src.mkdir()
+    (src / "mod.py").write_text("# code")
+
+    pkg = PackageInfo(
+        name="mypkg",
+        version="3.2.1",
+        modules=[ModuleInfo(name="mypkg.core", functions=[FunctionInfo(name="f")])],
+    )
+    _c.save(pkg, src)
+
+    runner = CliRunner()
+    result = runner.invoke(main, ["cache", "list"])
+
+    assert result.exit_code == 0
+    assert "mypkg" in result.output
+    assert "3.2.1" in result.output
+    assert "1 entries" in result.output
+
+
+# ---------------------------------------------------------------------------
+# _format_size / _format_age helpers
+# ---------------------------------------------------------------------------
+
+
+def test_format_size_bytes() -> None:
+    from libcontext.cli import _format_size
+
+    assert _format_size(500) == "500 B"
+
+
+def test_format_size_kilobytes() -> None:
+    from libcontext.cli import _format_size
+
+    assert _format_size(2048) == "2.0 kB"
+
+
+def test_format_size_megabytes() -> None:
+    from libcontext.cli import _format_size
+
+    assert _format_size(5 * 1024 * 1024) == "5.0 MB"
+
+
+def test_format_age_just_now() -> None:
+    import datetime
+
+    from libcontext.cli import _format_age
+
+    now = datetime.datetime.now(tz=datetime.timezone.utc).isoformat()
+    assert _format_age(now) == "just now"
+
+
+def test_format_age_minutes() -> None:
+    import datetime
+
+    from libcontext.cli import _format_age
+
+    ts = (
+        datetime.datetime.now(tz=datetime.timezone.utc) - datetime.timedelta(minutes=15)
+    ).isoformat()
+    assert _format_age(ts) == "15m ago"
+
+
+def test_format_age_hours() -> None:
+    import datetime
+
+    from libcontext.cli import _format_age
+
+    ts = (
+        datetime.datetime.now(tz=datetime.timezone.utc) - datetime.timedelta(hours=3)
+    ).isoformat()
+    assert _format_age(ts) == "3h ago"
+
+
+def test_format_age_days() -> None:
+    import datetime
+
+    from libcontext.cli import _format_age
+
+    ts = (
+        datetime.datetime.now(tz=datetime.timezone.utc) - datetime.timedelta(days=7)
+    ).isoformat()
+    assert _format_age(ts) == "7d ago"
+
+
+def test_format_age_invalid() -> None:
+    from libcontext.cli import _format_age
+
+    assert _format_age("not-a-timestamp") == "unknown age"
+    assert _format_age("") == "unknown age"
+
+
 # ---------------------------------------------------------------------------
 # diff subcommand
 # ---------------------------------------------------------------------------