crumbs-cli 0.3.0__tar.gz → 0.3.2__tar.gz

{crumbs_cli-0.3.0 → crumbs_cli-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crumbs-cli
-Version: 0.3.0
+Version: 0.3.2
 Summary: Local, token-efficient cross-repo context for LLMs. CLI + MCP server.
 Author: crumbs
 License: MIT
@@ -46,10 +46,15 @@ can open *just that slice* of a file rather than the whole thing.
 
 ## Install
 
+The distribution is named `crumbs-cli`; it provides the `crumbs` command.
+
 ```bash
-pip install -e .        # provides the `crumbs` command
-# or run without installing:
-python3 -m crumbs --help
+pipx install crumbs-cli       # isolated, on your PATH (recommended)
+# or, no install at all:
+uvx --from crumbs-cli crumbs --help
+# or, from a clone:
+pip install -e .              # dev install
+python3 -m crumbs --help      # run without installing
 ```
 
 ## Usage
@@ -66,6 +71,39 @@ crumbs remove my-web                       # drop a repo from the index
 
 A repo can be referenced by name, id, or path.
 
+## Use with Claude Code (MCP)
+
+crumbs ships an MCP server (`crumbs mcp`) so an MCP host — Claude Code, Claude
+Desktop, or any MCP client — can call it as native tools. It speaks the MCP wire
+protocol over stdio with **zero dependencies** (no SDK).
+
+**One-command install (Claude Code plugin):**
+
+```shell
+/plugin marketplace add crumbs1505/crumbs
+/plugin install crumbs@crumbs
+```
+
+This bundles the MCP server and a skill; repo paths are auto-indexed on first
+use. See [`plugin/`](plugin/) for details.
+
+**Manual registration** (e.g. in a project `.mcp.json` or your Claude Code config):
+
+```jsonc
+{
+  "mcpServers": {
+    "crumbs": { "command": "uvx", "args": ["--from", "crumbs-cli", "crumbs", "mcp"] }
+  }
+}
+```
+
+`uvx` fetches and runs crumbs on demand, so nothing needs to be installed first.
+(If you installed via `pipx`, use `"command": "crumbs", "args": ["mcp"]` instead.)
+
+The server exposes five model-controlled tools — `crumbs_map`, `crumbs_search`,
+`crumbs_context`, `crumbs_index`, `crumbs_list` — and auto-indexes a repo path on
+first use, so there is no manual setup step.
+
 ## Workflow with Claude
 
 1. `crumbs index` the repos you work across (once, or on a `crumbs refresh` cron).
@@ -105,6 +143,25 @@ safely.
 python3 -m unittest discover -s tests -v
 ```
 
+## Releasing
+
+Releases are published to [PyPI](https://pypi.org/project/crumbs-cli/) automatically by
+CI ([`.github/workflows/publish.yml`](.github/workflows/publish.yml)) whenever a version
+tag is pushed. To cut a release:
+
+1. Bump the version in **all three** places: `pyproject.toml`, `crumbs/__init__.py`,
+   and `plugin/.claude-plugin/plugin.json` (keep them in sync).
+2. Commit the bump and push to `main`.
+3. Tag and push it:
+
+   ```bash
+   git tag v0.3.1 && git push origin v0.3.1
+   ```
+
+CI then builds the sdist + wheel, runs `twine check`, and publishes to PyPI via
+[Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC — no token stored
+in the repo). PyPI versions are immutable, so every release needs a new version number.
+
 ## License
 
 MIT

{crumbs_cli-0.3.0 → crumbs_cli-0.3.2}/README.md

@@ -22,10 +22,15 @@ can open *just that slice* of a file rather than the whole thing.
 
 ## Install
 
+The distribution is named `crumbs-cli`; it provides the `crumbs` command.
+
 ```bash
-pip install -e .        # provides the `crumbs` command
-# or run without installing:
-python3 -m crumbs --help
+pipx install crumbs-cli       # isolated, on your PATH (recommended)
+# or, no install at all:
+uvx --from crumbs-cli crumbs --help
+# or, from a clone:
+pip install -e .              # dev install
+python3 -m crumbs --help      # run without installing
 ```
 
 ## Usage
@@ -42,6 +47,39 @@ crumbs remove my-web                       # drop a repo from the index
 
 A repo can be referenced by name, id, or path.
 
+## Use with Claude Code (MCP)
+
+crumbs ships an MCP server (`crumbs mcp`) so an MCP host — Claude Code, Claude
+Desktop, or any MCP client — can call it as native tools. It speaks the MCP wire
+protocol over stdio with **zero dependencies** (no SDK).
+
+**One-command install (Claude Code plugin):**
+
+```shell
+/plugin marketplace add crumbs1505/crumbs
+/plugin install crumbs@crumbs
+```
+
+This bundles the MCP server and a skill; repo paths are auto-indexed on first
+use. See [`plugin/`](plugin/) for details.
+
+**Manual registration** (e.g. in a project `.mcp.json` or your Claude Code config):
+
+```jsonc
+{
+  "mcpServers": {
+    "crumbs": { "command": "uvx", "args": ["--from", "crumbs-cli", "crumbs", "mcp"] }
+  }
+}
+```
+
+`uvx` fetches and runs crumbs on demand, so nothing needs to be installed first.
+(If you installed via `pipx`, use `"command": "crumbs", "args": ["mcp"]` instead.)
+
+The server exposes five model-controlled tools — `crumbs_map`, `crumbs_search`,
+`crumbs_context`, `crumbs_index`, `crumbs_list` — and auto-indexes a repo path on
+first use, so there is no manual setup step.
+
 ## Workflow with Claude
 
 1. `crumbs index` the repos you work across (once, or on a `crumbs refresh` cron).
@@ -81,6 +119,25 @@ safely.
 python3 -m unittest discover -s tests -v
 ```
 
+## Releasing
+
+Releases are published to [PyPI](https://pypi.org/project/crumbs-cli/) automatically by
+CI ([`.github/workflows/publish.yml`](.github/workflows/publish.yml)) whenever a version
+tag is pushed. To cut a release:
+
+1. Bump the version in **all three** places: `pyproject.toml`, `crumbs/__init__.py`,
+   and `plugin/.claude-plugin/plugin.json` (keep them in sync).
+2. Commit the bump and push to `main`.
+3. Tag and push it:
+
+   ```bash
+   git tag v0.3.1 && git push origin v0.3.1
+   ```
+
+CI then builds the sdist + wheel, runs `twine check`, and publishes to PyPI via
+[Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC — no token stored
+in the repo). PyPI versions are immutable, so every release needs a new version number.
+
 ## License
 
 MIT

{crumbs_cli-0.3.0 → crumbs_cli-0.3.2}/crumbs/__init__.py

@@ -6,4 +6,4 @@ crumbs to understand many repos at once without reading -- and paying tokens for
 -- the entire source tree.
 """
 
-__version__ = "0.3.0"
+__version__ = "0.3.2"

{crumbs_cli-0.3.0 → crumbs_cli-0.3.2}/crumbs/indexer.py

@@ -54,6 +54,43 @@ def _git_info(root: Path) -> Dict[str, str]:
     return info
 
 
+def newest_mtime(root: Path) -> float:
+    """Most recent mtime among indexable files (cheap, stat-only walk).
+
+    Uses the same directory/file filters as :func:`index_repo` so the set of
+    files considered matches what would actually be indexed.
+    """
+    newest = 0.0
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS and not d.startswith(".") or d in (".github",)]
+        for fn in filenames:
+            if fn in SKIP_FILES:
+                continue
+            try:
+                m = (Path(dirpath) / fn).stat().st_mtime
+            except OSError:
+                continue
+            if m > newest:
+                newest = m
+    return newest
+
+
+def is_stale(data: Dict[str, Any]) -> bool:
+    """True if the repo on disk has changed since it was last indexed.
+
+    Returns ``True`` for unreadable/missing metadata so callers re-index;
+    returns ``False`` if the path no longer exists (nothing to refresh from).
+    """
+    path = data.get("path")
+    indexed_at = data.get("indexed_at")
+    if not path or indexed_at is None:
+        return True
+    root = Path(path)
+    if not root.is_dir():
+        return False
+    return newest_mtime(root) > indexed_at
+
+
 def index_repo(path: str, name: Optional[str] = None) -> Dict[str, Any]:
     """Index a repository at ``path`` and persist its crumbs.
 

{crumbs_cli-0.3.0 → crumbs_cli-0.3.2}/crumbs/mcp.py

@@ -75,9 +75,20 @@ def _tool_list(args: Dict[str, Any]) -> str:
 
 
 def _resolve_or_index(selector: str) -> Optional[str]:
-    """Resolve a repo selector; if it's an unindexed path, index it first."""
+    """Resolve a repo selector, indexing (or re-indexing when stale) as needed.
+
+    An already-indexed repo is rebuilt if its source has changed since the last
+    index, so map/search/context never serve an out-of-date crumb map.
+    """
     rid = store.resolve(selector)
     if rid:
+        data = store.load_repo(rid)
+        if data and not indexer.is_stale(data):
+            return rid
+        try:
+            indexer.index_repo(data["path"] if data else selector)
+        except (NotADirectoryError, FileNotFoundError, KeyError):
+            pass  # keep the existing (possibly stale) index rather than failing
         return rid
     try:
         indexer.index_repo(selector)

{crumbs_cli-0.3.0 → crumbs_cli-0.3.2}/crumbs_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crumbs-cli
-Version: 0.3.0
+Version: 0.3.2
 Summary: Local, token-efficient cross-repo context for LLMs. CLI + MCP server.
 Author: crumbs
 License: MIT
@@ -46,10 +46,15 @@ can open *just that slice* of a file rather than the whole thing.
 
 ## Install
 
+The distribution is named `crumbs-cli`; it provides the `crumbs` command.
+
 ```bash
-pip install -e .        # provides the `crumbs` command
-# or run without installing:
-python3 -m crumbs --help
+pipx install crumbs-cli       # isolated, on your PATH (recommended)
+# or, no install at all:
+uvx --from crumbs-cli crumbs --help
+# or, from a clone:
+pip install -e .              # dev install
+python3 -m crumbs --help      # run without installing
 ```
 
 ## Usage
@@ -66,6 +71,39 @@ crumbs remove my-web                       # drop a repo from the index
 
 A repo can be referenced by name, id, or path.
 
+## Use with Claude Code (MCP)
+
+crumbs ships an MCP server (`crumbs mcp`) so an MCP host — Claude Code, Claude
+Desktop, or any MCP client — can call it as native tools. It speaks the MCP wire
+protocol over stdio with **zero dependencies** (no SDK).
+
+**One-command install (Claude Code plugin):**
+
+```shell
+/plugin marketplace add crumbs1505/crumbs
+/plugin install crumbs@crumbs
+```
+
+This bundles the MCP server and a skill; repo paths are auto-indexed on first
+use. See [`plugin/`](plugin/) for details.
+
+**Manual registration** (e.g. in a project `.mcp.json` or your Claude Code config):
+
+```jsonc
+{
+  "mcpServers": {
+    "crumbs": { "command": "uvx", "args": ["--from", "crumbs-cli", "crumbs", "mcp"] }
+  }
+}
+```
+
+`uvx` fetches and runs crumbs on demand, so nothing needs to be installed first.
+(If you installed via `pipx`, use `"command": "crumbs", "args": ["mcp"]` instead.)
+
+The server exposes five model-controlled tools — `crumbs_map`, `crumbs_search`,
+`crumbs_context`, `crumbs_index`, `crumbs_list` — and auto-indexes a repo path on
+first use, so there is no manual setup step.
+
 ## Workflow with Claude
 
 1. `crumbs index` the repos you work across (once, or on a `crumbs refresh` cron).
@@ -105,6 +143,25 @@ safely.
 python3 -m unittest discover -s tests -v
 ```
 
+## Releasing
+
+Releases are published to [PyPI](https://pypi.org/project/crumbs-cli/) automatically by
+CI ([`.github/workflows/publish.yml`](.github/workflows/publish.yml)) whenever a version
+tag is pushed. To cut a release:
+
+1. Bump the version in **all three** places: `pyproject.toml`, `crumbs/__init__.py`,
+   and `plugin/.claude-plugin/plugin.json` (keep them in sync).
+2. Commit the bump and push to `main`.
+3. Tag and push it:
+
+   ```bash
+   git tag v0.3.1 && git push origin v0.3.1
+   ```
+
+CI then builds the sdist + wheel, runs `twine check`, and publishes to PyPI via
+[Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC — no token stored
+in the repo). PyPI versions are immutable, so every release needs a new version number.
+
 ## License
 
 MIT

{crumbs_cli-0.3.0 → crumbs_cli-0.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "crumbs-cli"
-version = "0.3.0"
+version = "0.3.2"
 description = "Local, token-efficient cross-repo context for LLMs. CLI + MCP server."
 readme = "README.md"
 requires-python = ">=3.8"

{crumbs_cli-0.3.0 → crumbs_cli-0.3.2}/tests/test_crumbs.py

@@ -118,6 +118,35 @@ class TestIndexAndQuery(unittest.TestCase):
         self.assertIn("demo", out)
 
 
+class TestStaleness(unittest.TestCase):
+    def setUp(self):
+        self.repo = Path(tempfile.mkdtemp(prefix="stale-repo-"))
+        make_repo(self.repo)
+        self.data = indexer.index_repo(str(self.repo), name="stale")
+
+    def test_fresh_index_is_not_stale(self):
+        self.assertFalse(indexer.is_stale(self.data))
+
+    def test_new_file_marks_index_stale(self):
+        # Write a file whose mtime is newer than the recorded index time.
+        new_file = self.repo / "src" / "added.py"
+        new_file.write_text("def freshly_added():\n    return 1\n")
+        os.utime(new_file, (self.data["indexed_at"] + 10, self.data["indexed_at"] + 10))
+        self.assertTrue(indexer.is_stale(self.data))
+
+    def test_map_auto_reindexes_when_stale(self):
+        new_file = self.repo / "src" / "later.py"
+        new_file.write_text("def added_later():\n    return 2\n")
+        os.utime(new_file, (self.data["indexed_at"] + 10, self.data["indexed_at"] + 10))
+        # crumbs_map should detect staleness and pick up the new symbol.
+        out = mcp._tool_map({"repo": str(self.repo)})
+        self.assertIn("added_later", out)
+
+    def test_missing_path_is_not_stale(self):
+        ghost = dict(self.data, path="/nonexistent/path/xyz")
+        self.assertFalse(indexer.is_stale(ghost))
+
+
 class TestMCP(unittest.TestCase):
     @classmethod
     def setUpClass(cls):