fix: install to versioned cache path matching Claude Code's plugin system

The Python installer was copying files to ~/.claude/plugins/codebase-wizard/
but Claude Code loads plugins from the versioned cache directory:
  ~/.claude/plugins/cache/{marketplace}/{plugin}/{version}/

Changes:
- _resolve_dest() now returns the cache path for global installs
- install() reads version from source, cleans stale version dirs (update path)
- uninstall() removes the entire plugin/cache dir (all versions)
- status() checks the cache path for installed versions
- _register_installed_plugin() now receives and stores gitCommitSha
- Added _git_sha() helper to capture current HEAD SHA
- Added test_update_replaces_old_version to cover the update scenario
- Added PLUGIN_NAME constant; updated _register_plugin() signature

Result: ai-codebase-mentor install --for claude now writes the same registry
entries and installPath as Claude Code's /plugin UI install.

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

Author: RichardHightower

ai_codebase_mentor/converters/claude.py

@@ -1,18 +1,22 @@
 """Claude Code runtime installer for ai-codebase-mentor.
 
-Installs the Codebase Wizard plugin to the Claude Code plugin directories and
+Installs the Codebase Wizard plugin to the Claude Code plugin cache and
 registers it in all three Claude Code plugin registry files:
   - known_marketplaces.json  (registers "codebase-mentor" as a git marketplace)
   - installed_plugins.json   (registers the plugin under "codebase-wizard@codebase-mentor")
   - settings.json            (enables the plugin via enabledPlugins)
 
+Claude Code loads plugins from a versioned cache directory:
+  ~/.claude/plugins/cache/{marketplace}/{plugin}/{version}/
+
 Install destinations:
-  Global:  ~/.claude/plugins/codebase-wizard/
+  Global:  ~/.claude/plugins/cache/codebase-mentor/codebase-wizard/{version}/
   Project: ./plugins/codebase-wizard/
 """
 
 import json
 import shutil
+import subprocess
 import sys
 from datetime import datetime, timezone
 from pathlib import Path
@@ -22,32 +26,53 @@
 
 # Registry key used in installed_plugins.json and settings.json.
 # Format: "pluginname@marketplaceid" where marketplaceid is the key in known_marketplaces.json.
+PLUGIN_NAME = "codebase-wizard"
 PLUGIN_REGISTRY_KEY = "codebase-wizard@codebase-mentor"
 MARKETPLACE_ID = "codebase-mentor"
 MARKETPLACE_GIT_URL = "https://github.com/SpillwaveSolutions/codebase-mentor.git"
 
 
+def _git_sha() -> str:
+    """Return current HEAD commit SHA, or empty string if not in a git repo."""
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "HEAD"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+            check=False,
+        )
+        return result.stdout.strip() if result.returncode == 0 else ""
+    except Exception:
+        return ""
+
+
 class ClaudeInstaller(RuntimeInstaller):
     """Installs the Codebase Wizard plugin for Claude Code.
 
-    Copies the plugin tree and registers it in all three Claude Code registry
-    files so the plugin is discoverable without a marketplace server.
+    Copies the plugin tree to the versioned Claude Code cache directory and
+    registers it in all three Claude Code registry files so the plugin loads
+    on next session start.
 
-    Supports global install (~/.claude/plugins/) and per-project install
-    (./plugins/). Both are idempotent — calling install twice updates in place.
+    Supports global install (~/.claude/plugins/cache/.../version/) and
+    per-project install (./plugins/codebase-wizard/). Both are idempotent —
+    calling install again replaces the current version in place.
     """
 
     def install(self, source: Path, target: str = "global") -> None:
-        """Copy the plugin tree and register it with Claude Code.
+        """Copy the plugin tree to the Claude Code cache and register it.
 
         Writes three registry files so Claude Code loads the plugin:
           1. known_marketplaces.json — registers "codebase-mentor" git marketplace
           2. installed_plugins.json  — registers codebase-wizard@codebase-mentor
           3. settings.json           — enables the plugin
 
+        On update: removes old version directories from the cache before
+        installing the new version (avoids version directory accumulation).
+
         Args:
             source: Path to the bundled plugin directory (contains .claude-plugin/).
-            target: "global" → ~/.claude/plugins/codebase-wizard/
+            target: "global" → ~/.claude/plugins/cache/codebase-mentor/codebase-wizard/{version}/
                     "project" → ./plugins/codebase-wizard/
 
         Raises:
@@ -56,55 +81,93 @@ def install(self, source: Path, target: str = "global") -> None:
         if not source.exists():
             raise RuntimeError(f"Plugin source directory not found: {source}")
 
-        destination = self._resolve_dest(target)
+        version = _read_version(source) or "1.0.0"
+        destination = self._resolve_dest(target, version)
+
+        # Remove stale version directories before installing (handles updates).
+        if target == "global":
+            cache_plugin_dir = destination.parent
+            if cache_plugin_dir.exists():
+                for stale in cache_plugin_dir.iterdir():
+                    if stale.is_dir() and stale != destination:
+                        shutil.rmtree(stale, ignore_errors=True)
 
         try:
             if destination.exists():
                 shutil.rmtree(destination)
+            destination.parent.mkdir(parents=True, exist_ok=True)
             shutil.copytree(source, destination)
         except OSError as e:
             raise RuntimeError(f"Failed to install to {destination}: {e}") from e
 
         if target == "global":
-            version = _read_version(destination) or "1.0.0"
-            self._register_plugin(destination, version)
+            self._register_plugin(destination, version, _git_sha())
 
     def uninstall(self, target: str = "global") -> None:
-        """Remove the installed plugin directory and unregister it.
+        """Remove the installed plugin and unregister it.
+
+        For global installs, removes the entire plugin directory from the
+        cache (all versions) and cleans up all three registry files.
 
         Args:
             target: "global" or "project" — same scope as install().
 
         Never raises. No-op if the plugin is not installed.
         """
-        destination = self._resolve_dest(target)
-        if not destination.exists():
-            return
-        try:
-            shutil.rmtree(destination)
-        except OSError as e:
-            raise RuntimeError(f"Failed to uninstall from {destination}: {e}") from e
-
         if target == "global":
+            cache_plugin_dir = (
+                Path.home()
+                / ".claude"
+                / "plugins"
+                / "cache"
+                / MARKETPLACE_ID
+                / PLUGIN_NAME
+            )
+            if cache_plugin_dir.exists():
+                try:
+                    shutil.rmtree(cache_plugin_dir)
+                except OSError as e:
+                    raise RuntimeError(
+                        f"Failed to uninstall from {cache_plugin_dir}: {e}"
+                    ) from e
             self._unregister_plugin()
+        else:
+            destination = Path.cwd() / "plugins" / PLUGIN_NAME
+            if not destination.exists():
+                return
+            try:
+                shutil.rmtree(destination)
+            except OSError as e:
+                raise RuntimeError(f"Failed to uninstall from {destination}: {e}") from e
 
     def status(self) -> dict:
         """Report current install state for both global and project installs.
 
-        Checks global location first, then project. Returns the first found.
+        For global installs, checks the cache directory for any installed version.
+        Returns the first found.
 
         Returns:
             {"installed": bool, "location": str | None, "version": str | None}
         """
-        global_dest = Path.home() / ".claude" / "plugins" / "codebase-wizard"
-        if global_dest.exists():
-            return {
-                "installed": True,
-                "location": str(global_dest),
-                "version": _read_version(global_dest),
-            }
-
-        project_dest = Path.cwd() / "plugins" / "codebase-wizard"
+        cache_plugin_dir = (
+            Path.home()
+            / ".claude"
+            / "plugins"
+            / "cache"
+            / MARKETPLACE_ID
+            / PLUGIN_NAME
+        )
+        if cache_plugin_dir.exists():
+            versions = sorted(d for d in cache_plugin_dir.iterdir() if d.is_dir())
+            if versions:
+                latest = versions[-1]
+                return {
+                    "installed": True,
+                    "location": str(latest),
+                    "version": _read_version(latest),
+                }
+
+        project_dest = Path.cwd() / "plugins" / PLUGIN_NAME
         if project_dest.exists():
             return {
                 "installed": True,
@@ -114,20 +177,30 @@ def status(self) -> dict:
 
         return {"installed": False, "location": None, "version": None}
 
-    def _resolve_dest(self, target: str) -> Path:
-        """Resolve the install destination based on target scope."""
+    def _resolve_dest(self, target: str, version: str = "1.0.0") -> Path:
+        """Resolve the install destination based on target scope and version."""
         if target == "global":
-            return Path.home() / ".claude" / "plugins" / "codebase-wizard"
-        return Path.cwd() / "plugins" / "codebase-wizard"
+            return (
+                Path.home()
+                / ".claude"
+                / "plugins"
+                / "cache"
+                / MARKETPLACE_ID
+                / PLUGIN_NAME
+                / version
+            )
+        return Path.cwd() / "plugins" / PLUGIN_NAME
 
     # ------------------------------------------------------------------ #
     # Registry helpers                                                     #
     # ------------------------------------------------------------------ #
 
-    def _register_plugin(self, install_path: Path, version: str) -> None:
+    def _register_plugin(
+        self, install_path: Path, version: str, git_sha: str = ""
+    ) -> None:
         """Register the plugin in all three Claude Code registry files."""
         self._register_marketplace()
-        self._register_installed_plugin(install_path, version)
+        self._register_installed_plugin(install_path, version, git_sha)
         self._enable_plugin()
 
     def _register_marketplace(self) -> None:
@@ -156,7 +229,9 @@ def _register_marketplace(self) -> None:
             path.parent.mkdir(parents=True, exist_ok=True)
             path.write_text(json.dumps(data, indent=4) + "\n", encoding="utf-8")
 
-    def _register_installed_plugin(self, install_path: Path, version: str) -> None:
+    def _register_installed_plugin(
+        self, install_path: Path, version: str, git_sha: str = ""
+    ) -> None:
         """Write or update the plugin entry in installed_plugins.json."""
         path = Path.home() / ".claude" / "plugins" / "installed_plugins.json"
         data: dict = {"version": 2, "plugins": {}}
@@ -184,7 +259,7 @@ def _register_installed_plugin(self, install_path: Path, version: str) -> None:
                 "version": version,
                 "installedAt": installed_at,
                 "lastUpdated": now,
-                "gitCommitSha": "",
+                "gitCommitSha": git_sha,
             }
         ]
         path.parent.mkdir(parents=True, exist_ok=True)
@@ -212,7 +287,6 @@ def _enable_plugin(self) -> None:
 
     def _unregister_plugin(self) -> None:
         """Remove the plugin entry from installed_plugins.json and settings.json."""
-        # Remove from installed_plugins.json
         installed_path = Path.home() / ".claude" / "plugins" / "installed_plugins.json"
         if installed_path.exists():
             try:
@@ -224,7 +298,6 @@ def _unregister_plugin(self) -> None:
             except (json.JSONDecodeError, OSError):
                 pass
 
-        # Remove from settings.json enabledPlugins
         settings_path = Path.home() / ".claude" / "settings.json"
         if settings_path.exists():
             try:

tests/test_claude_installer.py

@@ -6,12 +6,25 @@
 
 import pytest
 
-from ai_codebase_mentor.converters.claude import ClaudeInstaller, PLUGIN_REGISTRY_KEY
+from ai_codebase_mentor.converters.claude import (
+    ClaudeInstaller,
+    MARKETPLACE_ID,
+    PLUGIN_NAME,
+    PLUGIN_REGISTRY_KEY,
+)
 
 # Path to the real plugin source (relative to project root)
 REAL_PLUGIN_SOURCE = Path(__file__).parent.parent / "plugins" / "codebase-wizard"
 
 
+def _global_cache_path(tmp_path: Path, version: str = "1.0.0") -> Path:
+    """Return the expected global install cache path for tests."""
+    return (
+        tmp_path / "home" / ".claude" / "plugins" / "cache"
+        / MARKETPLACE_ID / PLUGIN_NAME / version
+    )
+
+
 @pytest.fixture
 def source_plugin_dir(tmp_path):
     """Copy the real plugin source to a temp dir so tests don't touch the repo."""
@@ -33,12 +46,9 @@ def installer(tmp_path, monkeypatch):
 
 
 def test_global_install_copies_plugin_json(installer, source_plugin_dir, tmp_path):
-    """install(source, 'global') copies plugin.json to ~/.claude/plugins/codebase-wizard/."""
+    """install(source, 'global') copies plugin.json to the versioned cache directory."""
     installer.install(source_plugin_dir, "global")
-    dest_manifest = (
-        tmp_path / "home" / ".claude" / "plugins" / "codebase-wizard"
-        / ".claude-plugin" / "plugin.json"
-    )
+    dest_manifest = _global_cache_path(tmp_path) / ".claude-plugin" / "plugin.json"
     assert dest_manifest.exists(), f"plugin.json not found at {dest_manifest}"
 
 
@@ -59,11 +69,16 @@ def test_global_install_is_idempotent(installer, source_plugin_dir):
 
 
 def test_global_uninstall_removes_directory(installer, source_plugin_dir, tmp_path):
-    """uninstall('global') removes ~/.claude/plugins/codebase-wizard/ entirely."""
+    """uninstall('global') removes the entire plugin directory from the cache."""
     installer.install(source_plugin_dir, "global")
     installer.uninstall("global")
-    dest = tmp_path / "home" / ".claude" / "plugins" / "codebase-wizard"
-    assert not dest.exists(), f"Expected directory to be removed: {dest}"
+    cache_plugin_dir = (
+        tmp_path / "home" / ".claude" / "plugins" / "cache"
+        / MARKETPLACE_ID / PLUGIN_NAME
+    )
+    assert not cache_plugin_dir.exists(), (
+        f"Expected cache plugin directory to be removed: {cache_plugin_dir}"
+    )
 
 
 def test_project_uninstall_removes_directory(installer, source_plugin_dir, tmp_path):
@@ -80,10 +95,10 @@ def test_uninstall_when_not_installed_is_noop(installer):
 
 
 def test_status_after_global_install(installer, source_plugin_dir, tmp_path):
-    """status() returns installed=True with correct location and version after global install."""
+    """status() returns installed=True with the cache path and version after global install."""
     installer.install(source_plugin_dir, "global")
     result = installer.status()
-    expected_location = str(tmp_path / "home" / ".claude" / "plugins" / "codebase-wizard")
+    expected_location = str(_global_cache_path(tmp_path))
     assert result["installed"] is True
     assert result["location"] == expected_location
     assert result["version"] == "1.0.0"
@@ -112,10 +127,12 @@ def test_install_registers_in_installed_plugins_json(installer, source_plugin_di
     )
     entry = data["plugins"][PLUGIN_REGISTRY_KEY][0]
     assert entry["scope"] == "user"
-    assert "installPath" in entry
+    assert "cache" in entry["installPath"], "installPath should use cache directory"
+    assert MARKETPLACE_ID in entry["installPath"], "installPath should include marketplace ID"
     assert entry["version"] == "1.0.0"
     assert "installedAt" in entry
     assert "lastUpdated" in entry
+    assert "gitCommitSha" in entry
 
 
 def test_install_enables_plugin_in_settings_json(installer, source_plugin_dir, tmp_path):
@@ -157,3 +174,19 @@ def test_uninstall_removes_registration(installer, source_plugin_dir, tmp_path):
         assert PLUGIN_REGISTRY_KEY not in data.get("enabledPlugins", {}), (
             f"'{PLUGIN_REGISTRY_KEY}' still in settings.json enabledPlugins after uninstall"
         )
+
+
+def test_update_replaces_old_version(installer, source_plugin_dir, tmp_path):
+    """Installing a new version removes the old version directory from cache."""
+    # Simulate an older version already installed
+    old_version_dir = _global_cache_path(tmp_path, "0.9.0")
+    old_version_dir.mkdir(parents=True)
+    (old_version_dir / "old-marker.txt").touch()
+
+    installer.install(source_plugin_dir, "global")
+
+    # Old version dir should be gone
+    assert not old_version_dir.exists(), "Old version directory should be removed on update"
+    # New version should be installed
+    new_version_dir = _global_cache_path(tmp_path, "1.0.0")
+    assert new_version_dir.exists(), "New version directory should exist after install"