release: v1.108.164 - path-shaped repo arg returns a routed error (#376)

resolve_repo split any repo containing "/" on the first separator and returned
the halves unvalidated, so repo="src/auth/service.ts" became owner="src",
name="auth/service.ts". Callers catch ValueError from the resolver, but that
pair then reached store.load_index and raised "Path separator in name" from
_safe_repo_component, outside every handler. An owner/name id can never carry a
second separator (the store rejects one at write time), so every such argument
was guaranteed to crash rather than route.

A post-split name that still contains a separator is now treated as a path. It
tries the existing path-resolution route first, which picks up bare relative
multi-segment paths that _looks_like_path is deliberately too conservative to
match, and otherwise raises an actionable error naming resolve_repo,
index_folder, and file_pattern= when the argument looks like a file. The
unindexed-path error routes through the same helper so both paths give one
message. Single-separator ids and every real owner/name are untouched.

Reported from a daily Ubuntu install; split out of #375.
New tests/test_v1_108_164.py (8). No schema/tool-count/INDEX_VERSION change.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: jgravelle

CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to jcodemunch-mcp are documented here.
 
+## [1.108.164] - 2026-07-23 - A path-shaped `repo` arg returns a routed error, not a raw storage crash (#376)
+
+### Fixed
+
+- **`resolve_repo` no longer hands the store an owner/name pair it must reject.**
+  An agent without a repo id at hand guesses a path. `tools/_utils.resolve_repo`
+  split any `repo` containing `/` on the FIRST separator and returned the halves
+  unvalidated, so `repo="src/auth/service.ts"` became
+  `owner="src"`, `name="auth/service.ts"`. Callers catch `ValueError` from the
+  resolver, but that pair then reached `store.load_index(owner, name)` and raised
+  `ValueError: Path separator in name` from `_safe_repo_component`, outside every
+  handler. An `owner/name` id can never legitimately carry a second separator
+  (the store rejects one at write time), so every such argument was guaranteed to
+  crash rather than route.
+
+  A post-split name that still contains a separator is now treated as a path.
+  It first tries the existing path-resolution route, which picks up bare relative
+  multi-segment paths (`apps/web/src`) that `_looks_like_path` is deliberately too
+  conservative to match, and otherwise raises an actionable error the callers
+  already surface in band. New `_path_shaped_repo_error` names `resolve_repo` and
+  `index_folder`, and — when the argument looks like a file — names `file_pattern=`,
+  which is what an agent passing `repo=<file>` usually meant. The unindexed-path
+  error in `_resolve_path_repo` routes through the same helper so both paths give
+  one message. Single-separator ids and every real `owner/name` are untouched.
+
+  Reported from a daily Ubuntu install; split out of #375. New
+  `tests/test_v1_108_164.py` (8). NO schema/tool-count/`INDEX_VERSION` change.
+
 ## [1.108.163] - 2026-07-23 - License-key transport hardening: key never rides the URL (audit WS-8)
 
 ### Security

pyproject.toml

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

src/jcodemunch_mcp/tools/_utils.py

@@ -73,6 +73,26 @@ def _looks_like_path(repo: str) -> bool:
         return False
 
 
+def _path_shaped_repo_error(repo: str) -> ValueError:
+    """Actionable error for a `repo` arg that is a path, not a repository id (#376).
+
+    Agents that don't have an owner/name id at hand guess a file or directory path.
+    Name the two calls that produce a real id, and — when the arg looks like a file —
+    the `file_pattern` arg they most likely wanted instead of a hard failure.
+    """
+    message = (
+        f"'{repo}' is a path, not a repository id. "
+        "Call resolve_repo(path) to get the repo id for a checkout, "
+        "or index_folder(path) to index it."
+    )
+    if Path(repo).suffix:
+        message += (
+            " To scope a search to one file, pass the repo id as 'repo' and the "
+            f"path as 'file_pattern' (file_pattern='{repo}')."
+        )
+    return ValueError(message)
+
+
 def _resolve_path_repo(repo: str, storage_path: Optional[str]) -> tuple[str, str]:
     """Map a filesystem path (repo='.', an absolute path) to its indexed repo id."""
     from .resolve_repo import _compute_repo_id  # noqa: PLC0415
@@ -97,10 +117,7 @@ def _resolve_path_repo(repo: str, storage_path: Optional[str]) -> tuple[str, str
                     return entry["repo"].split("/", 1)
             except OSError:
                 continue
-    raise ValueError(
-        f"Path '{repo}' is not an indexed repository. "
-        "Call resolve_repo(path) to check its status, or index_folder(path) to index it."
-    )
+    raise _path_shaped_repo_error(repo)
 
 
 def resolve_repo(repo: str, storage_path: Optional[str] = None) -> tuple[str, str]:
@@ -115,7 +132,18 @@ def resolve_repo(repo: str, storage_path: Optional[str] = None) -> tuple[str, st
         return _resolve_path_repo(repo, storage_path)
 
     if "/" in repo:
-        return repo.split("/", 1)
+        owner, name = repo.split("/", 1)
+        # A second separator means this was never an owner/name id — the store
+        # rejects separators in `name` at write time, so such a pair can only
+        # blow up in the storage layer, outside every caller's handler (#376).
+        # Treat it as a path: a bare relative path like 'src/auth' is exactly
+        # what _looks_like_path is too conservative to catch.
+        if "/" in name or "\\" in name:
+            try:
+                return _resolve_path_repo(repo, storage_path)
+            except ValueError:
+                raise _path_shaped_repo_error(repo) from None
+        return owner, name
 
     store = IndexStore(base_path=storage_path)
     mapping = _get_bare_name_map(store)

tests/test_v1_108_164.py

@@ -0,0 +1,111 @@
+"""v1.108.164: a path-shaped `repo` arg no longer escapes as a raw storage ValueError.
+
+Origin: #376 (split out of #375), reported from a daily Ubuntu install. An agent that
+doesn't have an owner/name id at hand guesses a path. A two-segment path split on the
+FIRST separator left a `name` still carrying one, which the store rejects at
+`_safe_repo_component` — outside every caller's handler, so it surfaced as a hard
+`ValueError: Path separator in name` instead of a routed tool error.
+"""
+
+from types import SimpleNamespace
+
+import pytest
+
+from jcodemunch_mcp.tools import _utils
+from jcodemunch_mcp.tools import resolve_repo as rr
+
+
+def _store_with(repos=(), present=False):
+    return SimpleNamespace(
+        inspect_index=lambda o, n: SimpleNamespace(index_present=present),
+        list_repos=lambda: list(repos),
+    )
+
+
+class TestMultiSegmentRepoArg:
+    def test_file_path_raises_actionable_error_not_storage_valueerror(
+        self, monkeypatch
+    ):
+        monkeypatch.setattr(rr, "_compute_repo_id", lambda p, store=None: "")
+        monkeypatch.setattr(
+            _utils, "IndexStore", lambda base_path=None: _store_with()
+        )
+        with pytest.raises(ValueError) as exc:
+            _utils.resolve_repo("src/auth/service.ts")
+        message = str(exc.value)
+        assert "Path separator in name" not in message
+        assert "is a path, not a repository id" in message
+        assert "resolve_repo" in message and "index_folder" in message
+
+    def test_file_shaped_arg_names_file_pattern(self, monkeypatch):
+        monkeypatch.setattr(rr, "_compute_repo_id", lambda p, store=None: "")
+        monkeypatch.setattr(
+            _utils, "IndexStore", lambda base_path=None: _store_with()
+        )
+        with pytest.raises(ValueError) as exc:
+            _utils.resolve_repo("src/auth/service.ts")
+        assert "file_pattern='src/auth/service.ts'" in str(exc.value)
+
+    def test_directory_shaped_arg_omits_the_file_pattern_hint(self, monkeypatch):
+        # No suffix means the agent meant a checkout, not a file to scope to.
+        monkeypatch.setattr(rr, "_compute_repo_id", lambda p, store=None: "")
+        monkeypatch.setattr(
+            _utils, "IndexStore", lambda base_path=None: _store_with()
+        )
+        with pytest.raises(ValueError) as exc:
+            _utils.resolve_repo("local/foo/bar")
+        assert "file_pattern" not in str(exc.value)
+
+    def test_backslash_tail_also_routed(self, monkeypatch):
+        monkeypatch.setattr(rr, "_compute_repo_id", lambda p, store=None: "")
+        monkeypatch.setattr(
+            _utils, "IndexStore", lambda base_path=None: _store_with()
+        )
+        with pytest.raises(ValueError) as exc:
+            _utils.resolve_repo("local/foo\\bar")
+        assert "is a path, not a repository id" in str(exc.value)
+
+    def test_relative_path_that_is_indexed_resolves(self, monkeypatch, tmp_path):
+        # 'apps/web/src' is too conservative for _looks_like_path, but if it really
+        # is an indexed checkout we should resolve it rather than error.
+        sub = tmp_path / "apps" / "web" / "src"
+        sub.mkdir(parents=True)
+        monkeypatch.chdir(tmp_path)
+        monkeypatch.setattr(rr, "_compute_repo_id", lambda p, store=None: "")
+        monkeypatch.setattr(
+            _utils,
+            "IndexStore",
+            lambda base_path=None: _store_with(
+                repos=[{"repo": "local/web", "source_root": str(sub)}]
+            ),
+        )
+        assert tuple(_utils.resolve_repo("apps/web/src")) == ("local", "web")
+
+
+class TestNoRegressionOnRealIds:
+    def test_owner_name_id_untouched(self):
+        assert tuple(_utils.resolve_repo("local/gin")) == ("local", "gin")
+
+    def test_single_slash_missing_repo_keeps_its_own_error_path(self, monkeypatch):
+        # One separator is a well-formed id shape; it must NOT be re-routed as a
+        # path, so the caller still gets the index-not-loadable error downstream.
+        monkeypatch.setattr(
+            _utils, "IndexStore", lambda base_path=None: _store_with()
+        )
+        assert tuple(_utils.resolve_repo("tools/agents.ts")) == (
+            "tools",
+            "agents.ts",
+        )
+
+
+class TestSearchSymbolsSurfacesItInBand:
+    def test_path_shaped_repo_returns_error_dict(self, monkeypatch):
+        from jcodemunch_mcp.tools.search_symbols import search_symbols
+
+        monkeypatch.setattr(rr, "_compute_repo_id", lambda p, store=None: "")
+        monkeypatch.setattr(
+            _utils, "IndexStore", lambda base_path=None: _store_with()
+        )
+        result = search_symbols(repo="src/auth/service.ts", query="login")
+        assert isinstance(result, dict)
+        assert "is a path, not a repository id" in result["error"]