swarph-cli 0.23.0__tar.gz → 0.24.0__tar.gz

{swarph_cli-0.23.0/src/swarph_cli.egg-info → swarph_cli-0.24.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: swarph-cli
-Version: 0.23.0
+Version: 0.24.0
 Summary: The `swarph` binary — a multi-LLM CLI and mesh-gateway client + bundled server (`swarph gateway`): one-shot prompts across providers, interactive `chat`, multi-provider `spawn` (claude/codex/antigravity via a ProviderMembrane with subprocess billing-scrub), `mesh` send/inbox/register, `brain-ask` over the swarph-brain (gbrain) semantic memory, git-backed `assisted_memory`, session `import`, and a stranded-session `watchdog`.
 Author: Pierre Samson, Claude Opus
 License: MIT
@@ -72,6 +72,7 @@ This is one of three repos in the v0.3.x architecture:
 swarph "prompt"          one-shot against any provider (claude/openai/gemini/deepseek/grok)
 swarph chat              interactive REPL — multi-turn, slash commands, live provider switch
 swarph brain-ask "<q>"   search the swarph-brain (gbrain) memory — $0 cited answer or raw chunks
+swarph codegraph "<q>"   structural code search — find where a symbol is defined / what calls it
 swarph brain serve       run the gbrain HTTP brain server (the $0 semantic memory)
 swarph gateway serve     run the bundled mesh-gateway server (the mesh's coordination/DM hub)
 swarph service serve     stand up a $0 subscription-LLM HTTP lane (claude/codex/gemini)
@@ -117,6 +118,19 @@ $ swarph brain serve --gbrain-bin /opt/gbrain        # explicit binary (else GBR
 
 Defaults are loopback bind (expose a tailnet IP explicitly) and a **1-year token TTL** — a short TTL silently 401s long-lived mesh cells, a lesson learned the hard way. If `gbrain` isn't on `PATH` the verb prints an install hint and exits `2`; `brain-ask` still queries any already-running brain.
 
+### `swarph codegraph` (v0.24.0)
+
+Structural code search over a local **CodeGraph** index — the *what-where* hemisphere of the swarph brain. Ask in natural language where a function/class/symbol is **defined** or what **calls** it; get ranked hits with file:line, signature, and caller count.
+
+```bash
+$ swarph codegraph "which function escapes special characters for HTML"
+$ swarph codegraph "cron expression validator" --json --limit 5
+```
+
+It queries a locally-built index at `~/.swarph/codegraph/index.db` (override with `--index` or `SWARPH_CODEGRAPH_INDEX`); the index is built out-of-band from your repos (tree-sitter → SQLite FTS5, BM25-ranked). If no index is present the verb simply returns no matches — it never touches the network and never reads code it wasn't pointed at. Results are scoped by an owner-allowlist gate (`--caller-cell` / `SWARPH_CELL`, default: your cell): public repos are always visible; private repos are visible to the owning cell.
+
+The same capability is exposed as an **MCP tool** — running `swarph mcp-server` publishes `swarph_codegraph_query` alongside `swarph_search`/`swarph_add`/`swarph_describe`, so any MCP host's agent auto-discovers it and can reach for code-structure lookups while reading, writing, or debugging code. (Why a tool and not an always-on retrieval lane? Because *intent* to consult code structure lives with the calling agent — which already knows it's working on code — not in a similarity score.)
+
 ### `swarph gateway`
 
 The **mesh-gateway** is the coordination/DM server every other verb talks to — the peer registry, the DM inbox/outbox, feature aggregation with allowlist + caps, and lane/service control. It used to be a separate deployment; it's now bundled, so any host can stand one up with a single command. It pairs with the client verbs (`mesh`, `spawn`, `daemon`, `watchdog`) and with `brain-ask`/gbrain to form the mesh's coordination plane.

{swarph_cli-0.23.0 → swarph_cli-0.24.0}/README.md

@@ -27,6 +27,7 @@ This is one of three repos in the v0.3.x architecture:
 swarph "prompt"          one-shot against any provider (claude/openai/gemini/deepseek/grok)
 swarph chat              interactive REPL — multi-turn, slash commands, live provider switch
 swarph brain-ask "<q>"   search the swarph-brain (gbrain) memory — $0 cited answer or raw chunks
+swarph codegraph "<q>"   structural code search — find where a symbol is defined / what calls it
 swarph brain serve       run the gbrain HTTP brain server (the $0 semantic memory)
 swarph gateway serve     run the bundled mesh-gateway server (the mesh's coordination/DM hub)
 swarph service serve     stand up a $0 subscription-LLM HTTP lane (claude/codex/gemini)
@@ -72,6 +73,19 @@ $ swarph brain serve --gbrain-bin /opt/gbrain        # explicit binary (else GBR
 
 Defaults are loopback bind (expose a tailnet IP explicitly) and a **1-year token TTL** — a short TTL silently 401s long-lived mesh cells, a lesson learned the hard way. If `gbrain` isn't on `PATH` the verb prints an install hint and exits `2`; `brain-ask` still queries any already-running brain.
 
+### `swarph codegraph` (v0.24.0)
+
+Structural code search over a local **CodeGraph** index — the *what-where* hemisphere of the swarph brain. Ask in natural language where a function/class/symbol is **defined** or what **calls** it; get ranked hits with file:line, signature, and caller count.
+
+```bash
+$ swarph codegraph "which function escapes special characters for HTML"
+$ swarph codegraph "cron expression validator" --json --limit 5
+```
+
+It queries a locally-built index at `~/.swarph/codegraph/index.db` (override with `--index` or `SWARPH_CODEGRAPH_INDEX`); the index is built out-of-band from your repos (tree-sitter → SQLite FTS5, BM25-ranked). If no index is present the verb simply returns no matches — it never touches the network and never reads code it wasn't pointed at. Results are scoped by an owner-allowlist gate (`--caller-cell` / `SWARPH_CELL`, default: your cell): public repos are always visible; private repos are visible to the owning cell.
+
+The same capability is exposed as an **MCP tool** — running `swarph mcp-server` publishes `swarph_codegraph_query` alongside `swarph_search`/`swarph_add`/`swarph_describe`, so any MCP host's agent auto-discovers it and can reach for code-structure lookups while reading, writing, or debugging code. (Why a tool and not an always-on retrieval lane? Because *intent* to consult code structure lives with the calling agent — which already knows it's working on code — not in a similarity score.)
+
 ### `swarph gateway`
 
 The **mesh-gateway** is the coordination/DM server every other verb talks to — the peer registry, the DM inbox/outbox, feature aggregation with allowlist + caps, and lane/service control. It used to be a separate deployment; it's now bundled, so any host can stand one up with a single command. It pairs with the client verbs (`mesh`, `spawn`, `daemon`, `watchdog`) and with `brain-ask`/gbrain to form the mesh's coordination plane.

{swarph_cli-0.23.0 → swarph_cli-0.24.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "swarph-cli"
-version = "0.23.0"
+version = "0.24.0"
 description = "The `swarph` binary — a multi-LLM CLI and mesh-gateway client + bundled server (`swarph gateway`): one-shot prompts across providers, interactive `chat`, multi-provider `spawn` (claude/codex/antigravity via a ProviderMembrane with subprocess billing-scrub), `mesh` send/inbox/register, `brain-ask` over the swarph-brain (gbrain) semantic memory, git-backed `assisted_memory`, session `import`, and a stranded-session `watchdog`."
 readme = "README.md"
 license = { text = "MIT" }

{swarph_cli-0.23.0 → swarph_cli-0.24.0}/src/swarph_cli/__init__.py

@@ -16,6 +16,6 @@ The architecture splits CLI from substrate so:
 
 from __future__ import annotations
 
-__version__ = "0.23.0"
+__version__ = "0.24.0"
 
 __all__ = ["__version__"]

{swarph_cli-0.23.0 → swarph_cli-0.24.0}/src/swarph_cli/chain_token.py

@@ -21,6 +21,10 @@ def sign_chain_token(secret: str, chain_id: str, depth: int, jti: str) -> str:
 
 
 def verify_chain_token(secret: str, token: str) -> Optional[dict]:
+    # token is opaque untrusted input (network / mesh DM); a non-str value has no
+    # .split and would AttributeError past the except below. Guard explicitly.
+    if not isinstance(token, str):
+        return None
     try:
         body_s, sig_s = token.split(".", 1)
         payload = _unb64(body_s)
@@ -31,8 +35,8 @@ def verify_chain_token(secret: str, token: str) -> Optional[dict]:
         if not isinstance(d, dict) or {"chain_id", "depth", "jti"} - d.keys():
             return None
         return {"chain_id": d["chain_id"], "depth": int(d["depth"]), "jti": d["jti"]}
-    except (ValueError, TypeError, KeyError, json.JSONDecodeError):
-        # the known malformed-input paths (split / b64 / json / int / dict). Fail
-        # safe to None. NOT a bare `Exception`: an unexpected error should surface
-        # as a bug, not silently masquerade as "invalid token".
+    except (ValueError, TypeError, KeyError, AttributeError, json.JSONDecodeError):
+        # the known malformed-input paths (split / b64 / json / int / dict /
+        # non-str secret). Fail safe to None. NOT a bare `Exception`: an
+        # unexpected error should surface as a bug, not masquerade as "invalid".
         return None

swarph_cli-0.24.0/src/swarph_cli/commands/codegraph.py

@@ -0,0 +1,194 @@
+"""``swarph codegraph`` — on-demand STRUCTURAL code search over a LOCAL
+derived index.
+
+Self-contained port: this module does NOT depend on the local-only
+``codegraph_index`` package. The query/text-search/sensitivity logic below
+is ported verbatim (imports adapted only) so swarph-cli — a PUBLIC PyPI
+package — stays free of any dependency on that local tool.
+
+Retrieval is a TOOL an agent invokes when it needs to find where a symbol
+is defined or what calls it, not a per-prompt fusion lane — the intent to
+consult code structure comes from the caller.
+
+Fail-safe (A2): the query path is READ-ONLY, never raises, never hangs.
+A missing index file, a corrupt db, a malformed FTS5 MATCH string, or a
+locked db all resolve to ``[]`` — never an exception.
+
+Sensitivity gate (A8): ``_visible_repos`` decides which repos a caller may
+see BEFORE any row is read — public repos are always visible; private
+repos require the caller's cell to be present in ``allowlist[repo]``. The
+default allowlist (``_local_allowlist``) is operate-what-you-own: the
+local caller sees every repo present in its own index.
+
+Usage:
+  swarph codegraph "which function renders the thing"
+  swarph codegraph "cron expression validator" --json --limit 5
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sqlite3
+
+DEFAULT_INDEX = os.path.expanduser("~/.swarph/codegraph/index.db")
+# NOTE: named DEFAULT_CALLER_CELL, not "*_CALLER" — this is an A8 caller-CELL
+# identity (sensitivity-gate scoping), not a SwarphCall `role.subrole.specific`
+# caller tag, and must NOT trip the repo-wide caller-convention meta-guard
+# (tests/test_caller_meta_guard.py) which validates every `*_CALLER` constant
+# against that unrelated dotted-slug convention.
+DEFAULT_CALLER_CELL = "lab-ovh"
+
+# --- textsearch (ported verbatim from codegraph_index/textsearch.py) ------
+
+_STOP = {"the", "a", "an", "is", "are", "was", "how", "does", "do", "of", "to", "in", "on", "for", "and", "or",
+         "what", "which", "where", "when", "that", "this", "it", "its", "with", "by", "from", "get", "set"}
+
+
+def _tokens(nl: str) -> list:
+    """Sanitized content-tokens (lowercased, punctuation-stripped, stopwords
+    dropped, order-preserving de-dupe)."""
+    toks = re.findall(r"[A-Za-z0-9]+", (nl or "").lower())
+    toks = [t for t in toks if len(t) > 1 and t not in _STOP]
+    return list(dict.fromkeys(toks))  # dedupe, preserve first-seen order
+
+
+def _sanitize_query(nl: str) -> str:
+    """Turn free-text NL into an FTS5 MATCH string: OR-joined terms,
+    punctuation stripped, stopwords dropped, order-preserving de-dupe.
+    Empty input -> "" (caller must treat that as "no query", never issue a
+    MATCH on an empty string)."""
+    return " OR ".join(_tokens(nl))
+
+
+# --- connection (ported from codegraph_index/schema.py, read-only) --------
+
+def _connect(index_path: str, timeout_ms: int = 100) -> sqlite3.Connection:
+    con = sqlite3.connect(f"file:{index_path}?mode=ro", uri=True, timeout=timeout_ms / 1000)
+    con.execute(f"PRAGMA busy_timeout={timeout_ms}")  # A2: bound the wait, never block
+    return con
+
+
+# --- sensitivity (ported verbatim from codegraph_index/sensitivity.py) ----
+
+def _visible_repos(con, caller_cell: str, allowlist: dict) -> set:
+    out = set()
+    for name, vis in con.execute("SELECT name, visibility FROM repos"):
+        if vis == "public" or caller_cell in allowlist.get(name, []):
+            out.add(name)
+    return out
+
+
+# --- query (ported verbatim from codegraph_index/query.py) ----------------
+
+def structural_query(term, *, index_path, caller_cell, limit=8, allowlist=None) -> list:
+    """Ranked structural search. A8-gated, A2 fail-safe: any sqlite3.Error
+    (missing index, corrupt db, malformed MATCH, locked db) -> []."""
+    if allowlist is None:
+        allowlist = _local_allowlist(index_path, caller_cell)
+    try:
+        con = _connect(index_path)
+    except sqlite3.Error:
+        return []
+    try:
+        allowed = _visible_repos(con, caller_cell, allowlist)  # A8: gate BEFORE any row leaves
+        if not allowed:
+            return []
+        match = _sanitize_query(term)
+        if not match:
+            return []
+        qmarks = ",".join("?" * len(allowed))
+        rows = con.execute(
+            f"SELECT s.id,s.repo,s.name,s.kind,s.file_path,s.start_line,s.qualified_name,s.docstring,s.signature, "
+            f"bm25(symbols_fts, 10.0, 4.0, 1.0, 2.0) AS score "
+            f"FROM symbols_fts f JOIN symbols s ON s.id=f.rowid "
+            f"WHERE symbols_fts MATCH ? AND s.repo IN ({qmarks}) "
+            # 'import' nodes are references, never the *definition* a "which
+            # symbol implements X" query wants — same principle as the
+            # already-excluded 'file' kind.
+            f"AND s.kind NOT IN ('file','import') AND s.name NOT LIKE 'test\\_%' ESCAPE '\\' "
+            # test-file filter ANCHORED to a path segment/basename-start — an unanchored
+            # '%test_%' would blackhole real files like workers/backtest_engine.py (contains
+            # the substring 'test_'). Basename-after-a-slash starting test_, OR root-level test_*.
+            f"AND s.file_path NOT LIKE '%/tests/%' "
+            f"AND s.file_path NOT LIKE '%/test\\_%' ESCAPE '\\' "
+            f"AND s.file_path NOT LIKE 'test\\_%' ESCAPE '\\' "
+            f"ORDER BY bm25(symbols_fts, 10.0, 4.0, 1.0, 2.0) LIMIT ?",
+            [match, *sorted(allowed), limit]).fetchall()
+        out = []
+        for sid, repo, name, kind, fp, line, qualified_name, docstring, signature, score in rows:
+            # Only real call edges count as "callers" — the derived index carries CodeGraph's
+            # verbatim edge kinds (contains/imports/decorates/references/calls/...), and counting
+            # all of them would pollute the blast-radius number. 'calls' (plural) is CodeGraph's
+            # actual call-edge kind.
+            callers = con.execute(
+                "SELECT COUNT(*) FROM edges WHERE dst_symbol=? AND edge_type='calls'", (sid,)
+            ).fetchone()[0]
+            out.append({"repo": repo, "name": name, "kind": kind,
+                        "file_path": fp, "start_line": line, "callers": callers, "score": score,
+                        "qualified_name": qualified_name or "", "docstring": docstring or "",
+                        "signature": signature or ""})
+        return out
+    # OperationalError (lock/busy, or a malformed FTS5 MATCH query string) OR DatabaseError
+    # (corrupt/non-sqlite file) — both are sqlite3.Error siblings — fail safe (A2), never raise/hang.
+    except sqlite3.Error:
+        return []
+    finally:
+        try:
+            con.close()
+        except Exception:
+            pass
+
+
+def _local_allowlist(index_path: str, caller_cell: str) -> dict:
+    """Operate-what-you-own: the operator of the LOCAL index sees every repo
+    in it. A8's cross-cell scoping still applies to the caller_cell identity;
+    here the caller is the local operator, so grant it each repo present.
+    Fail-safe: unreadable index -> empty allowlist (structural_query then
+    returns [] via its own A8 gate)."""
+    try:
+        # A2: bound the connect + wait so a locked db can never hang the
+        # default query path (mirrors _connect's busy_timeout guarantee).
+        con = sqlite3.connect(f"file:{index_path}?mode=ro", uri=True, timeout=0.1)
+        con.execute("PRAGMA busy_timeout=100")
+        repos = [r[0] for r in con.execute("SELECT name FROM repos")]
+        con.close()
+    except sqlite3.Error:
+        return {}
+    return {r: [caller_cell] for r in repos}
+
+
+def format_human(rows, term) -> str:
+    if not rows:
+        return f"No structural matches for: {term!r}"
+    lines = [f"Structural matches for {term!r} ({len(rows)}):"]
+    for i, r in enumerate(rows, 1):
+        loc = f"{r['file_path']}:{r['start_line']}"
+        n = r["callers"]
+        callers = f"  ({n} caller{'s' if n != 1 else ''})" if n else ""
+        lines.append(f"{i}. {r['name']}  [{r['kind']}]  {r['repo']}  {loc}{callers}")
+        if r["signature"]:
+            lines.append(f"     {r['signature']}")
+        if r["docstring"]:
+            first = r["docstring"].strip().splitlines()[0][:100] if r["docstring"].strip() else ""
+            if first:
+                lines.append(f"     {first}")
+    return "\n".join(lines)
+
+
+def run_codegraph(argv) -> int:
+    ap = argparse.ArgumentParser(
+        prog="swarph codegraph",
+        description="On-demand structural code search: find where a symbol is defined or what calls it, "
+                    "across the indexed repos. Natural-language query.")
+    ap.add_argument("query", help="natural-language query, e.g. 'which function escapes HTML'")
+    ap.add_argument("--index", default=DEFAULT_INDEX, help=f"index db (default {DEFAULT_INDEX})")
+    ap.add_argument("--caller-cell", default=DEFAULT_CALLER_CELL, help="A8 caller identity (default lab-ovh)")
+    ap.add_argument("--limit", type=int, default=8)
+    ap.add_argument("--json", action="store_true", help="machine-readable JSON output")
+    a = ap.parse_args(argv)
+    rows = structural_query(a.query, index_path=a.index, caller_cell=a.caller_cell, limit=a.limit)
+    print(json.dumps(rows, indent=2) if a.json else format_human(rows, a.query))
+    return 0

{swarph_cli-0.23.0 → swarph_cli-0.24.0}/src/swarph_cli/commands/mcp_server.py

@@ -11,12 +11,14 @@ A host mounts it with a stdio server entry, e.g. in ``.mcp.json`` /
     {"mcpServers": {"swarph": {"command": "swarph",
                                "args": ["mcp-server"]}}}
 
-Three tools are exposed, each backed by a plain, unit-testable helper so the
+Four tools are exposed, each backed by a plain, unit-testable helper so the
 tool LOGIC is tested without spinning up the stdio transport:
 
-* ``swarph_search(query)`` → :func:`_search` — metaedge.surf semantic search.
-* ``swarph_add(uri)``      → :func:`_add`    — trust-gated + scanned install.
-* ``swarph_describe(uri)`` → :func:`_describe` — parse a URI, no install.
+* ``swarph_search(query)``           → :func:`_search` — metaedge.surf semantic search.
+* ``swarph_add(uri)``                → :func:`_add`    — trust-gated + scanned install.
+* ``swarph_describe(uri)``           → :func:`_describe` — parse a URI, no install.
+* ``swarph_codegraph_query(query)``  → :func:`_codegraph_query` — structural code
+  search (definitions + call sites) over the local codegraph index.
 
 The MCP Python SDK (``mcp``) is an OPTIONAL extra. :func:`run_mcp_server`
 fails gracefully with a ``pip install swarph-cli[mcp]`` hint when it's absent;
@@ -33,6 +35,7 @@ import urllib.error
 import urllib.request
 
 from swarph_cli.commands import add
+from swarph_cli.commands import codegraph
 
 # --------------------------------------------------------------------------- #
 # Config
@@ -47,6 +50,12 @@ _DEFAULT_METAEDGE_URL = "https://metaedge.surf"
 #: of truth feeds every ``swarph_search`` call.
 _METAEDGE_URL = os.environ.get("SWARPH_METAEDGE_URL", _DEFAULT_METAEDGE_URL)
 
+#: Module-level local codegraph index path the FastMCP tool wrapper reads.
+#: Overridable via ``SWARPH_CODEGRAPH_INDEX`` (mirrors ``codegraph.DEFAULT_INDEX``).
+_CODEGRAPH_INDEX = os.path.expanduser(
+    os.environ.get("SWARPH_CODEGRAPH_INDEX", "~/.swarph/codegraph/index.db")
+)
+
 
 def _metaedge_token() -> str | None:
     """Optional bearer token for the search face (``SWARPH_METAEDGE_TOKEN``)."""
@@ -131,6 +140,46 @@ def _describe(uri: str) -> dict:
     }
 
 
+def _codegraph_query(query: str, *, limit: int = 8) -> list[dict]:
+    """Structural code search over the local codegraph index (Task 1).
+
+    Delegates to :func:`codegraph.structural_query` against the module-level
+    ``_CODEGRAPH_INDEX`` path, using ``SWARPH_CELL`` (else
+    ``codegraph.DEFAULT_CALLER_CELL``) as the A8 caller identity and the
+    default operate-what-you-own allowlist (``allowlist=None``).
+
+    NEVER raises — any exception (missing index, corrupt db, bad query, or
+    anything else) is swallowed and returns ``[]`` so the MCP host always
+    gets a clean empty result rather than a transport error.
+
+    Returns COMPACT rows only — score/qualified_name/docstring are dropped
+    to keep the tool output tight for the calling agent.
+    """
+    try:
+        caller_cell = os.environ.get("SWARPH_CELL", codegraph.DEFAULT_CALLER_CELL)
+        rows = codegraph.structural_query(
+            query,
+            index_path=_CODEGRAPH_INDEX,
+            caller_cell=caller_cell,
+            limit=limit,
+            allowlist=None,
+        )
+        return [
+            {
+                "name": r["name"],
+                "kind": r["kind"],
+                "repo": r["repo"],
+                "file_path": r["file_path"],
+                "start_line": r["start_line"],
+                "signature": r["signature"],
+                "callers": r["callers"],
+            }
+            for r in rows
+        ]
+    except Exception:
+        return []
+
+
 # --------------------------------------------------------------------------- #
 # FastMCP server — thin @tool wrappers over the helpers above
 # --------------------------------------------------------------------------- #
@@ -160,6 +209,11 @@ try:
         """Parse a swarph:// URI and show what it points at, without installing."""
         return _describe(uri)
 
+    @mcp.tool()
+    def swarph_codegraph_query(query: str) -> list[dict]:
+        """Find where a function/class/method/symbol is DEFINED, or what CALLS it, across the indexed code repositories. Use this whenever you are reading, writing, debugging, or navigating code and need to locate a definition or trace call relationships by natural-language description (e.g. 'which function escapes HTML', 'where is the retry-parse helper defined', 'what calls the circuit breaker'). Returns ranked symbols with file path, line, signature, and caller count."""
+        return _codegraph_query(query)
+
 except ImportError:  # pragma: no cover - exercised only when SDK absent
     mcp = None
 
@@ -183,7 +237,8 @@ def run_mcp_server(argv) -> int:
         prog="swarph mcp-server",
         description=(
             "Run an MCP (stdio) server exposing swarph_search / swarph_add / "
-            "swarph_describe so any MCP host's AI gets the swarph toolbelt."
+            "swarph_describe / swarph_codegraph_query so any MCP host's AI "
+            "gets the swarph toolbelt."
         ),
     )
     parser.add_argument(

{swarph_cli-0.23.0 → swarph_cli-0.24.0}/src/swarph_cli/main.py

@@ -101,6 +101,7 @@ _VERB_HANDLERS: dict[str, str] = {
     "lane": "swarph_cli.commands.lane.run_lane",
     "install-multiplexer": "swarph_cli.commands.install_multiplexer.run_install_multiplexer",
     "highlight": "swarph_cli.commands.highlight.run_highlight",
+    "codegraph": "swarph_cli.commands.codegraph.run_codegraph",
     # Future: "list-peers", "list-adapters", etc.
 }
 

{swarph_cli-0.23.0 → swarph_cli-0.24.0/src/swarph_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: swarph-cli
-Version: 0.23.0
+Version: 0.24.0
 Summary: The `swarph` binary — a multi-LLM CLI and mesh-gateway client + bundled server (`swarph gateway`): one-shot prompts across providers, interactive `chat`, multi-provider `spawn` (claude/codex/antigravity via a ProviderMembrane with subprocess billing-scrub), `mesh` send/inbox/register, `brain-ask` over the swarph-brain (gbrain) semantic memory, git-backed `assisted_memory`, session `import`, and a stranded-session `watchdog`.
 Author: Pierre Samson, Claude Opus
 License: MIT
@@ -72,6 +72,7 @@ This is one of three repos in the v0.3.x architecture:
 swarph "prompt"          one-shot against any provider (claude/openai/gemini/deepseek/grok)
 swarph chat              interactive REPL — multi-turn, slash commands, live provider switch
 swarph brain-ask "<q>"   search the swarph-brain (gbrain) memory — $0 cited answer or raw chunks
+swarph codegraph "<q>"   structural code search — find where a symbol is defined / what calls it
 swarph brain serve       run the gbrain HTTP brain server (the $0 semantic memory)
 swarph gateway serve     run the bundled mesh-gateway server (the mesh's coordination/DM hub)
 swarph service serve     stand up a $0 subscription-LLM HTTP lane (claude/codex/gemini)
@@ -117,6 +118,19 @@ $ swarph brain serve --gbrain-bin /opt/gbrain        # explicit binary (else GBR
 
 Defaults are loopback bind (expose a tailnet IP explicitly) and a **1-year token TTL** — a short TTL silently 401s long-lived mesh cells, a lesson learned the hard way. If `gbrain` isn't on `PATH` the verb prints an install hint and exits `2`; `brain-ask` still queries any already-running brain.
 
+### `swarph codegraph` (v0.24.0)
+
+Structural code search over a local **CodeGraph** index — the *what-where* hemisphere of the swarph brain. Ask in natural language where a function/class/symbol is **defined** or what **calls** it; get ranked hits with file:line, signature, and caller count.
+
+```bash
+$ swarph codegraph "which function escapes special characters for HTML"
+$ swarph codegraph "cron expression validator" --json --limit 5
+```
+
+It queries a locally-built index at `~/.swarph/codegraph/index.db` (override with `--index` or `SWARPH_CODEGRAPH_INDEX`); the index is built out-of-band from your repos (tree-sitter → SQLite FTS5, BM25-ranked). If no index is present the verb simply returns no matches — it never touches the network and never reads code it wasn't pointed at. Results are scoped by an owner-allowlist gate (`--caller-cell` / `SWARPH_CELL`, default: your cell): public repos are always visible; private repos are visible to the owning cell.
+
+The same capability is exposed as an **MCP tool** — running `swarph mcp-server` publishes `swarph_codegraph_query` alongside `swarph_search`/`swarph_add`/`swarph_describe`, so any MCP host's agent auto-discovers it and can reach for code-structure lookups while reading, writing, or debugging code. (Why a tool and not an always-on retrieval lane? Because *intent* to consult code structure lives with the calling agent — which already knows it's working on code — not in a similarity score.)
+
 ### `swarph gateway`
 
 The **mesh-gateway** is the coordination/DM server every other verb talks to — the peer registry, the DM inbox/outbox, feature aggregation with allowlist + caps, and lane/service control. It used to be a separate deployment; it's now bundled, so any host can stand one up with a single command. It pairs with the client verbs (`mesh`, `spawn`, `daemon`, `watchdog`) and with `brain-ask`/gbrain to form the mesh's coordination plane.

{swarph_cli-0.23.0 → swarph_cli-0.24.0}/src/swarph_cli.egg-info/SOURCES.txt

@@ -28,6 +28,7 @@ src/swarph_cli/commands/brain_ask.py
 src/swarph_cli/commands/cell.py
 src/swarph_cli/commands/channel.py
 src/swarph_cli/commands/chat.py
+src/swarph_cli/commands/codegraph.py
 src/swarph_cli/commands/compress.py
 src/swarph_cli/commands/daemon.py
 src/swarph_cli/commands/event.py
@@ -94,6 +95,8 @@ tests/test_channel_command.py
 tests/test_chat_command.py
 tests/test_claude_parser.py
 tests/test_claude_tmux_template.py
+tests/test_codegraph_command.py
+tests/test_codegraph_mcp.py
 tests/test_compress_caller_convention.py
 tests/test_compress_command.py
 tests/test_compress_levers.py

{swarph_cli-0.23.0 → swarph_cli-0.24.0}/tests/test_chain_token.py

@@ -25,3 +25,10 @@ def test_wrong_secret_rejected():
 def test_malformed_never_raises():
     for bad in ["", "nodot", "a.b.c", "!!.??", "x."]:
         assert verify_chain_token(SECRET, bad) is None
+
+def test_non_str_token_fails_safe_not_raises():
+    # opaque tokens arrive from untrusted input (network / mesh DM); a non-str
+    # value (None, bytes, int) must fail safe to None, never AttributeError out
+    # of the caller. Regression for the gateway-copy fix that lagged the CLI.
+    for bad in [None, 123, b"a.b", ["a", "b"], {"chain_id": "x"}]:
+        assert verify_chain_token(SECRET, bad) is None

swarph_cli-0.24.0/tests/test_codegraph_command.py

@@ -0,0 +1,107 @@
+# tests/test_codegraph_command.py
+"""Tests for `swarph codegraph` — self-contained structural code search over a
+LOCAL codegraph index. All fixture data is SYNTHETIC (invented repos/symbols) —
+this module ships in the public swarph-cli package, so no real repo names,
+symbol names, or fleet topology may appear here."""
+import os
+import sqlite3
+
+import pytest
+
+from swarph_cli.commands import codegraph as cg
+
+
+def _tiny(tmp_path):
+    # synthetic fixture — NO real repo/symbol names
+    p = os.path.join(tmp_path, "i.db")
+    c = sqlite3.connect(p)
+    c.executescript(
+        "CREATE TABLE repos(name TEXT PRIMARY KEY, slug TEXT, path TEXT, visibility TEXT, indexed_at TEXT);"
+        "CREATE TABLE symbols(id INTEGER PRIMARY KEY, repo TEXT, name TEXT, kind TEXT, file_path TEXT, start_line INTEGER,"
+        " qualified_name TEXT, docstring TEXT, signature TEXT, name_search TEXT);"
+        "CREATE TABLE edges(src_symbol INTEGER, dst_symbol INTEGER, edge_type TEXT, repo TEXT);"
+        "CREATE VIRTUAL TABLE symbols_fts USING fts5(name_search, qualified_name, docstring, signature,"
+        " content='symbols', content_rowid='id', tokenize=\"porter unicode61 separators '_.'\");")
+    c.execute("INSERT INTO repos VALUES('alpha','o/alpha','/a','public','t')")
+    c.execute("INSERT INTO repos VALUES('beta','o/beta','/b','private','t')")
+    c.execute("INSERT INTO symbols(id,repo,name,kind,file_path,start_line,qualified_name,docstring,signature,name_search)"
+              " VALUES(1,'alpha','renderThing','function','ui.js',3,'ui.renderThing','renders the thing','function renderThing(x)','renderThing render thing')")
+    c.execute("INSERT INTO symbols(id,repo,name,kind,file_path,start_line,qualified_name,docstring,signature,name_search)"
+              " VALUES(2,'beta','secretOp','function','s.py',9,'b.secretOp','does a secret op','def secretOp(x)','secretOp secret op')")
+    c.execute("INSERT INTO symbols_fts(rowid,name_search,qualified_name,docstring,signature) SELECT id,name_search,qualified_name,docstring,signature FROM symbols")
+    c.commit()
+    c.close()
+    return p
+
+
+def test_structural_query_finds_symbol_by_natural_language(tmp_path):
+    index_path = _tiny(tmp_path)
+    rows = cg.structural_query(
+        "which function renders the thing",
+        index_path=index_path, caller_cell="local", limit=8,
+    )
+    names = [r["name"] for r in rows]
+    assert "renderThing" in names
+
+
+def test_structural_query_missing_index_returns_empty_list(tmp_path):
+    missing = os.path.join(tmp_path, "nope.db")
+    rows = cg.structural_query(
+        "renders the thing", index_path=missing, caller_cell="local", limit=8,
+    )
+    assert rows == []
+
+
+def test_a8_default_allowlist_sees_private_repo(tmp_path):
+    # operate-what-you-own: local caller with default allowlist sees the
+    # private 'beta' symbol from its own index.
+    index_path = _tiny(tmp_path)
+    rows = cg.structural_query(
+        "secret op", index_path=index_path, caller_cell="local", limit=8,
+    )
+    names = [r["name"] for r in rows]
+    assert "secretOp" in names
+
+
+def test_a8_empty_allowlist_hides_private_but_shows_public(tmp_path):
+    index_path = _tiny(tmp_path)
+    rows = cg.structural_query(
+        "secret op", index_path=index_path, caller_cell="someone-else",
+        limit=8, allowlist={},
+    )
+    names = [r["name"] for r in rows]
+    assert "secretOp" not in names
+
+    rows2 = cg.structural_query(
+        "renders the thing", index_path=index_path, caller_cell="someone-else",
+        limit=8, allowlist={},
+    )
+    names2 = [r["name"] for r in rows2]
+    assert "renderThing" in names2
+
+
+def test_sanitize_query_empty_string(tmp_path):
+    assert cg._sanitize_query("") == ""
+
+
+def test_format_human_no_matches():
+    assert "No structural matches" in cg.format_human([], "x")
+
+
+def test_main_routes_codegraph_verb():
+    # `swarph codegraph "..."` dispatches through main._VERB_HANDLERS
+    from swarph_cli import main
+    assert main._VERB_HANDLERS["codegraph"] == "swarph_cli.commands.codegraph.run_codegraph"
+
+
+def test_run_codegraph_cli_smoke(tmp_path, capsys):
+    # End-to-end argparse wiring: --index/--caller-cell/--json all reach
+    # structural_query and a JSON-decodable result comes back on stdout.
+    index_path = _tiny(tmp_path)
+    rc = cg.run_codegraph(
+        ["renders the thing", "--index", str(index_path), "--caller-cell", "local", "--json"]
+    )
+    assert rc == 0
+    import json
+    out = json.loads(capsys.readouterr().out)
+    assert any(r["name"] == "renderThing" for r in out)