release: v1.108.84 — install-mechanism-aware upgrade (#357)

pipx/uv venvs ship no pip module, so 'jcodemunch-mcp upgrade' died with
'No module named pip' and skipped the hook refresh. detect_install_mechanism()
now routes pip installs through in-process pip-install-U as before, and on
pipx/uv prints the exact upgrade command + refreshes hooks in-process (no pip).
Startup version-drift warning leads with 'init --hooks' (pip-free).

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

Author: jgravelle

CHANGELOG.md

@@ -2,6 +2,35 @@
 
 All notable changes to jcodemunch-mcp are documented here.
 
+## [1.108.84] - 2026-06-28 - Install-mechanism-aware `upgrade` (#357)
+
+`jcodemunch-mcp upgrade` shelled out to `python -m pip install -U` blindly.
+pipx- and uv-managed venvs ship no `pip` module, so the command died with
+`No module named pip` and bailed *before* refreshing hooks (reported by
+@zakblacki on a pipx install). Worse, the startup version-drift warning told
+the user to run `jcodemunch-mcp upgrade` to clear it — the exact command that
+fails on pip-less installs — so the nag never cleared.
+
+### Changed
+
+- **`upgrade` detects the install mechanism instead of guessing-and-running.**
+  New `detect_install_mechanism()` (path/env heuristic, no subprocess) returns
+  the mechanism (`pip`/`pipx`/`uv`/`uvx`/`venv`) and the exact upgrade command
+  for it. When `pip` is importable, the in-process `pip install -U` runs as
+  before. When it isn't (pipx/uv), the command no longer invokes a foreign
+  package manager — it prints the correct one (`pipx upgrade jcodemunch-mcp` /
+  `uv tool upgrade jcodemunch-mcp`) and still refreshes hooks/config
+  in-process, which needs no pip. A genuine pip *failure* (network/permissions)
+  now refreshes hooks anyway and preserves the non-zero exit code rather than
+  skipping the refresh.
+- **Startup version-drift warning leads with the pip-free command.** Now
+  recommends `jcodemunch-mcp init --hooks` (needs no pip) to clear the stale-hook
+  nag, noting `upgrade` also works on pip installs.
+
+New `cli/upgrade.py` helpers `_pip_available()` / `detect_install_mechanism()` /
+`_refresh_hooks()` / `_print_external_upgrade_hint()`. No INDEX_VERSION bump.
+New `tests/test_v1_108_84.py` (11).
+
 ## [1.108.83] - 2026-06-26 - Tame watch-all CPU under WSL (#356)
 
 `watch-all` pegged 15-30% CPU continuously on WSL (reported by @Blainexi). Root

CLAUDE.md

@@ -1,6 +1,7 @@
 # jcodemunch-mcp — Project Brief
 
 ## Current State
+- **Version:** 1.108.84 — Install-mechanism-aware `upgrade` (#357, reported by @zakblacki on a pipx install). `jcodemunch-mcp upgrade` ran `sys.executable -m pip install -U` blindly; pipx/uv venvs ship NO `pip` module → `No module named pip`, pip exited non-zero, and the command **bailed before refreshing hooks**. Compounding it: the startup version-drift warning (`server.py`) told the user to run `jcodemunch-mcp upgrade` to clear the stale-hook nag — the exact pip-less-failing command — so it never cleared. Fix (rewrote `cli/upgrade.py`): new `detect_install_mechanism()` (path/env heuristic, no subprocess) → `(mechanism, upgrade_command)` for pip/pipx/uv/uvx/venv. `_pip_available()` gates the in-process `pip install -U`: present → runs as before (a genuine pip *failure* now refreshes hooks anyway + preserves the non-zero rc, was: skip-and-bail); **absent → does NOT shell out to a foreign package manager** (honors jjg's stated "detect then tell, don't guess-and-run" stance from the issue thread), prints the exact command (`pipx upgrade` / `uv tool upgrade`), and refreshes hooks in-process via `init --hooks` (pip-free, stamps `last_init_version.txt` so the nag clears). The nag warning now leads with `init --hooks`. NO INDEX_VERSION bump. New `tests/test_v1_108_84.py` (11). Files: `cli/upgrade.py` (rewrite), `server.py` (warning text). Side issues answered in #357 reply (not bugs): `.pack/nodejs` migration warning = stale starter-pack index; `find_dead_code` `framework_warning` inflated dead-code % on a Node project because its entry-point heuristic looks for `main.py`/`app.py` (pass `entry_point_patterns` or reindex); real-time freshness = `watch-all`. See [[project_jmunch_console]].
 - **Version:** 1.108.83 — Tame `watch-all` CPU under WSL (#356, reported by @Blainexi). `watch-all` pegged 15-30% CPU non-stop on WSL. NOT a busy loop: **`watchfiles` auto-enables polling whenever it detects WSL** (inotify unreliable across the boundary, confirmed in watchfiles docs), and its default 300ms poll re-stats the whole watched tree several times/sec — multiplied across every indexed repo. `DefaultFilter` drops `node_modules`/`.git` *events* but the polling walk still stats them (structural cost). Fix: the `awatch` call now passes `poll_delay_ms=_watch_poll_delay_ms()` (resolves `JCODEMUNCH_WATCH_POLL_DELAY_MS` → `WATCHFILES_POLL_DELAY_MS` → `DEFAULT_WATCH_POLL_DELAY_MS=1000`; non-positive/garbage → default); ignored when native FS events are used (no-op off WSL). Plus a one-time WSL startup hint (`_is_wsl()`) naming the two levers: raise the poll delay, or set `WATCHFILES_FORCE_POLLING=false` for Linux-filesystem repos to use native inotify (~0 idle CPU); `/mnt/*` repos need polling. NO INDEX_VERSION bump. New `tests/test_v1_108_83.py` (11); `test_watch_all.py`/`test_watcher_lock.py` green. Files: `watcher.py`, `watch_all.py`. See [[project_jmunch_console]].
 - **Version:** 1.108.82 — Exclude `org_savings.db` from `list_repos`. The team-SKU org-rollup store (`org_savings.db`, written by `org/store.py`) sits in `~/.code-index/` next to per-repo index `.db` files, but `_NON_REPO_DB_FILES` only excluded `telemetry.db` → `list_repos` enumerated it as a phantom `local/org_savings` repo (sym 0, empty source_root, display==repo_id). In the jMunch Console it showed an un-removable card; `delete-index local/org_savings` failed (no matching `local-org_savings.db` index → non-zero exit), which the Console surfaced as the misleading "needs jcodemunch-mcp >= 1.108.50". Fix: `_NON_REPO_DB_FILES = frozenset({"telemetry.db", "org_savings.db"})` (1-line). NO INDEX_VERSION bump. New `tests/test_telemetry_db_skip.py::test_list_repos_skips_org_savings_db`; storage/sqlite_store suites green. Files: `storage/sqlite_store.py`. Console-side companion: the Console's delete-failure message now surfaces jcm's real error instead of the hard-coded version hint (jmunch-console). See [[project_jmunch_console]], [[project_org_rollup_sku]].
 - **Version:** 1.108.81 — Lazy git identity probe in `get_watch_status` / `list-repos`. `list-repos` (and `get_watch_status`) slowed to 60s+ on many-repo hosts because the per-folder loop resolved each repo's reindex-state key up front via `_reindex_key` → `_local_repo_id` → `resolve_index_identity` — a **git identity probe ≈1 subprocess/repo** (~0.2s each here, worse in worktree-heavy trees; cf. the #303 resolve_repo perf history). But reindex_state is **in-memory only** (populated by a watcher/server process); a cold `list-repos` CLI (the jMunch Console cockpit shells exactly this) has none, so every probe resolved a key only to read an empty default. Fix: new `reindex_state.has_any_reindex_state()` (`bool(_repo_states)` under lock); `get_watch_status` computes `track_reindex = has_any_reindex_state()` ONCE before the loop and skips `_reindex_key`/`get_reindex_status` entirely when False, substituting the default `{index_stale:False, reindex_in_progress:False, stale_since_ms:None}` per repo. **Output shape unchanged** (cold path already returned these defaults — just after paying for N git probes); a watcher/server process WITH state still resolves keys so #353 crash-loop visibility holds. `process_locks.inspect` (OpenProcess, ~0.01s/10) and `service_status` (~0.26s) were measured cheap; the git probe was the sole per-repo scaler. NO INDEX_VERSION bump. New `tests/test_v1_108_81.py` (2: probe skipped + get_reindex_status not consulted when no state; keys resolved when state present); `test_v1_108_78.py`/`test_watch_all.py`/`test_reindex_state.py`/`test_watcher_lock.py` still green. Files: `reindex_state.py`, `tools/get_watch_status.py`. Motivated by the jMunch Console showing fixtures because its 20s CLI timeout lost to this; see [[project_jmunch_console]].

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "jcodemunch-mcp"
-version = "1.108.83"
+version = "1.108.84"
 description = "Token-efficient MCP server for source code exploration via tree-sitter AST parsing"
 readme = "README.md"
 requires-python = ">=3.10"

src/jcodemunch_mcp/cli/upgrade.py

@@ -1,43 +1,78 @@
-"""``jcodemunch-mcp upgrade`` — pip install -U + refresh hooks/config.
+"""``jcodemunch-mcp upgrade`` — package upgrade + refresh hooks/config.
 
 Single command for the post-release path that previously required two
 steps (``pip install -U jcodemunch-mcp`` and ``jcodemunch-mcp init
 --hooks``). Picked up from issue #273: users on Copilot/parallel-session
 workflows kept missing the second step and ending up with stale hook
 templates pointing at older binaries.
+
+Install-mechanism aware (#357): a pipx- or uv-managed venv ships no
+``pip`` module, so the old ``python -m pip install -U`` died with
+``No module named pip`` and skipped the hook refresh entirely. We do NOT
+guess-and-run a foreign package manager; instead we detect the mechanism,
+print the exact upgrade command for it, and still refresh hooks/config
+in-process (which needs no pip).
 """
 
 from __future__ import annotations
 
+import importlib.util
+import os
 import shutil
 import subprocess
 import sys
 
 
-def run_upgrade(*, no_pip: bool = False, yes: bool = True) -> int:
-    """Run ``pip install -U jcodemunch-mcp`` then refresh hooks/config.
+def _pip_available() -> bool:
+    """True when ``pip`` is importable in the current interpreter.
 
-    Returns exit code (0 on success, non-zero on pip failure).
+    pipx and uv-tool venvs intentionally omit pip, so ``python -m pip``
+    fails with ``No module named pip`` rather than upgrading anything.
+    """
+    try:
+        return importlib.util.find_spec("pip") is not None
+    except (ImportError, ValueError):
+        return False
+
+
+def detect_install_mechanism() -> tuple[str, str | None]:
+    """Best-effort detection of how jcodemunch-mcp was installed.
+
+    Returns ``(mechanism, upgrade_command)`` where ``mechanism`` is one of
+    ``pip`` / ``pipx`` / ``uv`` / ``uvx`` / ``venv``, and ``upgrade_command``
+    is the exact shell command to upgrade the package outside this process
+    (or ``None`` for plain pip, where in-process ``pip install -U`` works).
+
+    Detection is path/env heuristic — it never runs a subprocess.
+    """
+    exe = (sys.executable or "").replace("\\", "/").lower()
+
+    # pipx: venvs live under .../pipx/venvs/<pkg>/...
+    if "/pipx/venvs/" in exe or "/pipx/venv/" in exe or os.environ.get("PIPX_HOME"):
+        return "pipx", "pipx upgrade jcodemunch-mcp"
+
+    # uv tool install: .../uv/tools/<pkg>/...
+    if "/uv/tools/" in exe:
+        return "uv", "uv tool upgrade jcodemunch-mcp"
+
+    # uvx ephemeral run: resolved out of the uv cache; nothing to "upgrade"
+    # persistently, so point at the @latest refresh form.
+    if "/uv/" in exe or "/.cache/uv/" in exe or "/uv/cache/" in exe:
+        return "uvx", "uvx jcodemunch-mcp@latest --version"
+
+    # Plain virtualenv without pip (rare) — caller must upgrade it themselves.
+    if not _pip_available():
+        return "venv", None
+
+    return "pip", None
+
+
+def _refresh_hooks(*, yes: bool = True) -> int:
+    """Refresh hook templates/config via ``init --hooks`` (no pip required).
+
+    Prefers the freshly-installed binary if it's on PATH, otherwise falls
+    back to the in-process module entry so a venv shim isn't bypassed.
     """
-    if not no_pip:
-        pip_args = [sys.executable, "-m", "pip", "install", "-U", "jcodemunch-mcp"]
-        print(f"$ {' '.join(pip_args)}")
-        try:
-            r = subprocess.run(pip_args, check=False)
-        except OSError as e:
-            print(f"  pip invocation failed: {e}", file=sys.stderr)
-            return 1
-        if r.returncode != 0:
-            print(
-                "  pip exited non-zero; skipping hook refresh. "
-                "Re-run with --no-pip after fixing the install.",
-                file=sys.stderr,
-            )
-            return r.returncode
-
-    # Run init in --yes mode to refresh hook templates non-interactively.
-    # Use the freshly-installed binary if it's on PATH, otherwise fall back
-    # to the in-process module entry so a venv shim doesn't get bypassed.
     exe = shutil.which("jcodemunch-mcp")
     if exe:
         init_cmd = [exe, "init", "--hooks"]
@@ -53,3 +88,73 @@ def run_upgrade(*, no_pip: bool = False, yes: bool = True) -> int:
         print(f"  init invocation failed: {e}", file=sys.stderr)
         return 1
     return r.returncode
+
+
+def _print_external_upgrade_hint(mechanism: str, command: str | None) -> None:
+    """Tell the user the exact command for their install mechanism."""
+    if command:
+        print(
+            f"pip is not available in this environment "
+            f"({mechanism}-managed install detected)."
+        )
+        print("To upgrade the package, run:")
+        print(f"    {command}")
+        print("Then restart your editor / MCP client so it relaunches the server.")
+    else:
+        print(
+            f"pip is not available in this environment "
+            f"({mechanism} install detected)."
+        )
+        print(
+            "Upgrade jcodemunch-mcp through whatever installed it, restart your "
+            "MCP client, then re-run `jcodemunch-mcp upgrade --no-pip` to refresh hooks."
+        )
+
+
+def run_upgrade(*, no_pip: bool = False, yes: bool = True) -> int:
+    """Upgrade jcodemunch-mcp (when possible) then refresh hooks/config.
+
+    Behavior by environment:
+
+    - **pip available** (default venv / system pip): runs
+      ``python -m pip install -U jcodemunch-mcp``; on a genuine pip failure
+      (network, permissions) the non-zero code is preserved but hooks are
+      still refreshed so a partial state can recover.
+    - **pip absent** (pipx / uv tool / uvx): does NOT shell out to a foreign
+      package manager. Prints the exact upgrade command for the detected
+      mechanism, then refreshes hooks/config in-process and returns that
+      refresh's exit code.
+
+    Returns an exit code (0 on success).
+    """
+    package_upgrade_rc = 0
+
+    if not no_pip:
+        if _pip_available():
+            pip_args = [sys.executable, "-m", "pip", "install", "-U", "jcodemunch-mcp"]
+            print(f"$ {' '.join(pip_args)}")
+            try:
+                r = subprocess.run(pip_args, check=False)
+            except OSError as e:
+                print(f"  pip invocation failed: {e}", file=sys.stderr)
+                package_upgrade_rc = 1
+            else:
+                if r.returncode != 0:
+                    print(
+                        "  pip exited non-zero; refreshing hooks anyway. "
+                        "Fix the package install, then re-run with --no-pip.",
+                        file=sys.stderr,
+                    )
+                    package_upgrade_rc = r.returncode
+        else:
+            mechanism, command = detect_install_mechanism()
+            _print_external_upgrade_hint(mechanism, command)
+
+    print("Refreshing hooks/config in-process (no pip required)...")
+    refresh_rc = _refresh_hooks(yes=yes)
+
+    # A genuine pip failure is a real error the caller should see; a
+    # pip-absent environment is not a failure (the package upgrade is the
+    # user's separate keystroke, which we've printed), so the hook-refresh
+    # result governs the exit code there.
+    return package_upgrade_rc or refresh_rc

src/jcodemunch_mcp/server.py

@@ -8416,7 +8416,8 @@ def main(argv: Optional[list[str]] = None):
                 logger.warning(
                     "jcodemunch-mcp upgraded %s -> %s but `init` has not been "
                     "re-run. Hook templates and config may be stale; run "
-                    "`jcodemunch-mcp upgrade` (or `init --hooks`) to refresh.",
+                    "`jcodemunch-mcp init --hooks` to refresh (needs no pip; "
+                    "`jcodemunch-mcp upgrade` also works on pip installs).",
                     _stamped,
                     _current_version,
                 )