eulerian 0.1.0__tar.gz

eulerian-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Curtis Bangert
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

eulerian-0.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: eulerian
+Version: 0.1.0
+Summary: Standalone real-time code index — live local directories and registered git repos
+Keywords: code-navigation,mcp,tree-sitter,git-worktree,code-index,ai-agent
+Author: Curtis Bangert
+Author-email: Curtis Bangert <codecae@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Utilities
+Classifier: Topic :: Text Editors :: Integrated Development Environments (IDE)
+Requires-Dist: fastmcp>=3.2.0
+Requires-Dist: typer>=0.15.0
+Requires-Dist: tree-sitter>=0.21
+Requires-Dist: tree-sitter-python>=0.21
+Requires-Dist: rapidfuzz>=3.0.0
+Requires-Dist: watchfiles>=0.24.0
+Requires-Dist: rich>=14.0.0
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# eulerian
+
+Real-time code navigation for AI agents and editors. `eulerian` keeps a live
+symbol index — files, classes, functions, methods, constants, with line
+ranges — so an agent can jump straight to a definition instead of grepping
+or reading whole files.
+
+Two ways to point it at code:
+
+- **Local mode** — watch a real working directory. A filesystem watcher
+  re-parses files the moment they're saved; the index never goes stale and
+  there's no explicit re-index step.
+- **Repo mode** — register a git remote, check out a `(user, repo, ref)`
+  worktree, and browse it without touching your actual working tree.
+  Freshness is checked against the remote on each call instead of pushed
+  live, since nothing is editing the worktree directly.
+
+Both modes share one in-memory symbol index and the same tree-sitter parser.
+Python only for now (multi-language grammars are straightforward to add —
+see `parser.py`).
+
+## Install
+
+```bash
+uv tool install eulerian
+# or
+pip install eulerian
+```
+
+No other runtime dependencies beyond `tree-sitter`, `tree-sitter-python`,
+`rapidfuzz`, `watchfiles`, `fastmcp`, and `typer` — all pulled in
+automatically.
+
+## CLI
+
+```bash
+# Local mode: one-shot queries against a directory, no persistent watcher
+eulerian status [PATH]
+eulerian outline QUERY [PATH] [-k N]
+eulerian find SYMBOL [PATH]
+
+# Local mode: live watch + MCP server (stdio by default, for an MCP client)
+eulerian watch [PATH] [--http --host HOST --port PORT]
+
+# Repo mode: register, checkout, browse
+eulerian repo add URL
+eulerian repo list
+eulerian repo fetch REPO
+eulerian repo checkout REPO REF [--user NAME]
+eulerian repo outline REPO REF QUERY [--user NAME] [-k N]
+```
+
+## MCP server
+
+`eulerian watch [PATH]` starts a FastMCP server (stdio or `--http`) exposing:
+
+**Local mode** — `watch(path)`, `unwatch(path)`, `outline(query, paths, root, k, format)`,
+`find(symbol, root)`, `read(path, start, end, root)`, `status(root)`.
+
+**Repo mode** — `repo_add(url)`, `repo_fetch(repo)`, `repo_list()`, `repo_pubkey()`,
+`checkout(repo, ref, user)`, `checkout_close(repo, ref, user)`, `git_log(repo, ref, user, n)`,
+`repo_outline(repo, ref, query, paths, user, k, format, reset_head)`,
+`repo_read(repo, ref, path, user, start, end, segments, reset_head)`.
+
+Point any MCP-capable client (Claude Code, etc.) at `eulerian watch <path>`
+to get instant, line-precise code navigation without burning tool calls on
+`grep`/`read` round-trips.
+
+## Repo-mode configuration
+
+Bare clones and worktrees live under `~/.eulerian/` by default:
+
+| Env var | Default | Purpose |
+|---|---|---|
+| `EULERIAN_GIT_REPOS_PATH` | `~/.eulerian/repos/` | Bare clone + worktree storage |
+| `EULERIAN_GIT_SSH_KEY` | `~/.eulerian/ssh/id_ed25519` | Deploy key for private remotes |
+| `EULERIAN_GIT_WORKTREE_MAX_IDLE_SEC` | `3600` | Idle worktree eviction threshold |
+
+## Architecture
+
+```
+parser.py        tree-sitter Python parser -> Symbol / CallEdge / ImportEdge
+index.py         in-memory Index, keyed by an opaque handle, rapidfuzz search
+sources/local.py watchfiles watcher  -> handle = resolved root Path
+sources/repo.py  bare clone + worktree lifecycle -> handle = (user, repo, ref)
+mcp/             FastMCP server exposing both modes as tools
+cli.py           typer CLI
+```
+
+`Index` doesn't care what a handle is — local mode and repo mode just pick
+different shapes for it. Both feed the same `outline`/`find` query surface.

eulerian-0.1.0/README.md

@@ -0,0 +1,91 @@
+# eulerian
+
+Real-time code navigation for AI agents and editors. `eulerian` keeps a live
+symbol index — files, classes, functions, methods, constants, with line
+ranges — so an agent can jump straight to a definition instead of grepping
+or reading whole files.
+
+Two ways to point it at code:
+
+- **Local mode** — watch a real working directory. A filesystem watcher
+  re-parses files the moment they're saved; the index never goes stale and
+  there's no explicit re-index step.
+- **Repo mode** — register a git remote, check out a `(user, repo, ref)`
+  worktree, and browse it without touching your actual working tree.
+  Freshness is checked against the remote on each call instead of pushed
+  live, since nothing is editing the worktree directly.
+
+Both modes share one in-memory symbol index and the same tree-sitter parser.
+Python only for now (multi-language grammars are straightforward to add —
+see `parser.py`).
+
+## Install
+
+```bash
+uv tool install eulerian
+# or
+pip install eulerian
+```
+
+No other runtime dependencies beyond `tree-sitter`, `tree-sitter-python`,
+`rapidfuzz`, `watchfiles`, `fastmcp`, and `typer` — all pulled in
+automatically.
+
+## CLI
+
+```bash
+# Local mode: one-shot queries against a directory, no persistent watcher
+eulerian status [PATH]
+eulerian outline QUERY [PATH] [-k N]
+eulerian find SYMBOL [PATH]
+
+# Local mode: live watch + MCP server (stdio by default, for an MCP client)
+eulerian watch [PATH] [--http --host HOST --port PORT]
+
+# Repo mode: register, checkout, browse
+eulerian repo add URL
+eulerian repo list
+eulerian repo fetch REPO
+eulerian repo checkout REPO REF [--user NAME]
+eulerian repo outline REPO REF QUERY [--user NAME] [-k N]
+```
+
+## MCP server
+
+`eulerian watch [PATH]` starts a FastMCP server (stdio or `--http`) exposing:
+
+**Local mode** — `watch(path)`, `unwatch(path)`, `outline(query, paths, root, k, format)`,
+`find(symbol, root)`, `read(path, start, end, root)`, `status(root)`.
+
+**Repo mode** — `repo_add(url)`, `repo_fetch(repo)`, `repo_list()`, `repo_pubkey()`,
+`checkout(repo, ref, user)`, `checkout_close(repo, ref, user)`, `git_log(repo, ref, user, n)`,
+`repo_outline(repo, ref, query, paths, user, k, format, reset_head)`,
+`repo_read(repo, ref, path, user, start, end, segments, reset_head)`.
+
+Point any MCP-capable client (Claude Code, etc.) at `eulerian watch <path>`
+to get instant, line-precise code navigation without burning tool calls on
+`grep`/`read` round-trips.
+
+## Repo-mode configuration
+
+Bare clones and worktrees live under `~/.eulerian/` by default:
+
+| Env var | Default | Purpose |
+|---|---|---|
+| `EULERIAN_GIT_REPOS_PATH` | `~/.eulerian/repos/` | Bare clone + worktree storage |
+| `EULERIAN_GIT_SSH_KEY` | `~/.eulerian/ssh/id_ed25519` | Deploy key for private remotes |
+| `EULERIAN_GIT_WORKTREE_MAX_IDLE_SEC` | `3600` | Idle worktree eviction threshold |
+
+## Architecture
+
+```
+parser.py        tree-sitter Python parser -> Symbol / CallEdge / ImportEdge
+index.py         in-memory Index, keyed by an opaque handle, rapidfuzz search
+sources/local.py watchfiles watcher  -> handle = resolved root Path
+sources/repo.py  bare clone + worktree lifecycle -> handle = (user, repo, ref)
+mcp/             FastMCP server exposing both modes as tools
+cli.py           typer CLI
+```
+
+`Index` doesn't care what a handle is — local mode and repo mode just pick
+different shapes for it. Both feed the same `outline`/`find` query surface.

eulerian-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "eulerian"
+version = "0.1.0"
+description = "Standalone real-time code index — live local directories and registered git repos"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Curtis Bangert", email = "codecae@gmail.com" }
+]
+keywords = ["code-navigation", "mcp", "tree-sitter", "git-worktree", "code-index", "ai-agent"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Utilities",
+    "Topic :: Text Editors :: Integrated Development Environments (IDE)",
+]
+requires-python = ">=3.13"
+dependencies = [
+    "fastmcp>=3.2.0",
+    "typer>=0.15.0",
+    "tree-sitter>=0.21",
+    "tree-sitter-python>=0.21",
+    "rapidfuzz>=3.0.0",
+    "watchfiles>=0.24.0",
+    "rich>=14.0.0",
+]
+
+[project.scripts]
+eulerian = "eulerian.cli:app"
+
+[build-system]
+requires = ["uv_build>=0.11.0,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.commitizen]
+name = "cz_conventional_commits"
+version_scheme = "semver"
+version_provider = "pep621"
+tag_format = "eulerian-v$version"
+allowed_scopes = ["eulerian"]

eulerian-0.1.0/src/eulerian/__init__.py

@@ -0,0 +1 @@
+"""eulerian — standalone real-time code index for local directories and git repos."""

eulerian-0.1.0/src/eulerian/cli.py

@@ -0,0 +1,197 @@
+"""eulerian CLI — watch, outline, find, status, repo."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+app = typer.Typer(
+    name="eulerian",
+    help="Real-time code index for local directories and git repos.",
+    no_args_is_help=True,
+)
+console = Console()
+
+
+@app.command()
+def watch(
+    path: Path = typer.Argument(
+        Path("."), help="Directory to watch (default: current directory)"
+    ),
+    http: bool = typer.Option(
+        False, "--http", help="Serve MCP over HTTP instead of stdio"
+    ),
+    host: str = typer.Option("0.0.0.0", "--host", help="Bind host (http mode only)"),
+    port: int = typer.Option(8090, "--port", help="Bind port (http mode only)"),
+) -> None:
+    """Start watching a directory and serve the MCP server (stdio or http).
+
+    Performs a full scan immediately, then keeps the index live via a
+    filesystem watcher for the lifetime of this process.
+    """
+    import asyncio
+
+    from .sources import local as _local
+    from .state import index
+    from .mcp.server import server as mcp_server
+
+    root = path.expanduser().resolve()
+    if not root.is_dir():
+        console.print(f"[red]Not a directory:[/red] {root}")
+        raise typer.Exit(1)
+
+    watcher = _local.watch_root(index, root)
+    console.print(
+        f"[green]eulerian[/green] watching {watcher.root} ({watcher.symbol_count} symbols)"
+    )
+
+    if http:
+        console.print(f"  MCP (http) listening on {host}:{port}")
+        asyncio.run(mcp_server.run_http_async(host=host, port=port))
+    else:
+        asyncio.run(mcp_server.run_stdio_async())
+
+
+@app.command()
+def outline(
+    query: str = typer.Argument(..., help="Symbol name or file path fragment"),
+    path: Path = typer.Argument(
+        Path("."), help="Directory to search (default: current directory)"
+    ),
+    k: int = typer.Option(20, help="Max results"),
+) -> None:
+    """One-shot fuzzy symbol search — parses path, searches, exits. No persistent watcher."""
+    from .index import Index
+
+    root = path.expanduser().resolve()
+    idx = Index()
+    idx.full_scan(root, root)
+    symbols = idx.outline(root, query, k)
+    if not symbols:
+        console.print(f"[dim]No symbols found for[/dim] {query!r}")
+        return
+    for s in symbols:
+        console.print(
+            f"  [cyan]{s.name}[/cyan] [L{s.start}-{s.end}] ({s.kind})  [dim]{s.file}[/dim]"
+        )
+
+
+@app.command()
+def find(
+    symbol: str = typer.Argument(..., help="Symbol name or substring"),
+    path: Path = typer.Argument(
+        Path("."), help="Directory to search (default: current directory)"
+    ),
+) -> None:
+    """One-shot symbol lookup by name — parses path, searches, exits."""
+    from .index import Index
+
+    root = path.expanduser().resolve()
+    idx = Index()
+    idx.full_scan(root, root)
+    symbols = idx.find(root, symbol)
+    if not symbols:
+        console.print(f"[dim]No symbol found matching[/dim] {symbol!r}")
+        return
+    for s in symbols:
+        console.print(
+            f"  [cyan]{s.name}[/cyan] [L{s.start}-{s.end}]  [dim]{s.file}[/dim]"
+        )
+
+
+@app.command()
+def status(
+    path: Path = typer.Argument(
+        Path("."), help="Directory to scan (default: current directory)"
+    ),
+) -> None:
+    """One-shot scan summary — files indexed, symbol count, by kind."""
+    from .parser import parse_directory
+
+    root = path.expanduser().resolve()
+    result = parse_directory(root)
+    by_kind: dict[str, int] = {}
+    for s in result.symbols:
+        by_kind[s.kind] = by_kind.get(s.kind, 0) + 1
+    console.print(f"[bold]{root}[/bold]")
+    console.print(
+        f"  files indexed: {result.files_indexed}  skipped: {result.files_skipped}"
+    )
+    for kind, count in sorted(by_kind.items()):
+        console.print(f"  {kind}: {count}")
+
+
+# ---------------------------------------------------------------------------
+# repo subcommands — operate on the persistent registry/worktree pool
+# ---------------------------------------------------------------------------
+
+repo_app = typer.Typer(
+    name="repo", help="Registered-git-repo worktree management.", no_args_is_help=True
+)
+app.add_typer(repo_app)
+
+
+@repo_app.command("add")
+def repo_add_cmd(url: str = typer.Argument(..., help="Git remote URL")) -> None:
+    """Clone url as a bare clone and register it."""
+    from .sources import repo as _repo
+
+    result = _repo.repo_add(url)
+    console.print(json.dumps(result, indent=2))
+
+
+@repo_app.command("list")
+def repo_list_cmd() -> None:
+    """List all registered repos."""
+    from .sources import repo as _repo
+
+    console.print(json.dumps(_repo.repo_list(), indent=2))
+
+
+@repo_app.command("fetch")
+def repo_fetch_cmd(
+    repo: str = typer.Argument(..., help="Registered repo name or URL"),
+) -> None:
+    """Fetch the latest refs for a registered repo."""
+    from .sources import repo as _repo
+
+    console.print(json.dumps(_repo.repo_fetch(repo), indent=2))
+
+
+@repo_app.command("checkout")
+def repo_checkout_cmd(
+    repo: str = typer.Argument(..., help="Registered repo name or URL"),
+    ref: str = typer.Argument(..., help="Branch, tag, or commit hash"),
+    user: str = typer.Option("default", "--user", "-u"),
+) -> None:
+    """Create or reuse a worktree for repo+ref."""
+    from .index import Index
+    from .sources import repo as _repo
+
+    idx = Index()
+    console.print(json.dumps(_repo.code_checkout(idx, repo, ref, user), indent=2))
+
+
+@repo_app.command("outline")
+def repo_outline_cmd(
+    repo: str = typer.Argument(...),
+    ref: str = typer.Argument(...),
+    query: str = typer.Argument(...),
+    user: str = typer.Option("default", "--user", "-u"),
+    k: int = typer.Option(20),
+) -> None:
+    """Fuzzy symbol search over a checked-out worktree (checkout first)."""
+    from .index import Index
+    from .sources import repo as _repo
+
+    idx = Index()
+    symbols, warnings = _repo.query_outline(idx, user, repo, ref, query, k)
+    for s in symbols:
+        console.print(
+            f"  [cyan]{s.name}[/cyan] [L{s.start}-{s.end}] ({s.kind})  [dim]{s.file}[/dim]"
+        )
+    for w in warnings:
+        console.print(f"[yellow]WARNING:[/yellow] {w}")

eulerian-0.1.0/src/eulerian/index.py

@@ -0,0 +1,127 @@
+"""In-memory symbol index, keyed by an opaque handle.
+
+A handle is whatever the caller wants — a resolved local root path, or a
+(user, repo, ref) tuple for repo-mode. The index itself doesn't care; it
+just holds a symbol list per handle and answers outline/find/read-adjacent
+queries against it. Local-mode and repo-mode sources both populate the same
+index through full_scan/update_file/remove_file.
+"""
+
+from __future__ import annotations
+
+import threading
+from pathlib import Path
+from typing import Hashable
+
+from rapidfuzz import fuzz, process
+
+from .parser import (
+    Symbol,
+    build_module_map,
+    parse_directory,
+    parse_file,
+    walk_python_files,
+)
+
+Handle = Hashable
+
+
+class Index:
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._symbols: dict[Handle, list[Symbol]] = {}
+        self._roots: dict[Handle, Path] = {}
+        self._module_maps: dict[Handle, dict[str, str]] = {}
+
+    def full_scan(self, handle: Handle, root: Path) -> int:
+        """Walk + parse everything under root, replacing any existing index for handle."""
+        result = parse_directory(root)
+        module_map = build_module_map(root, walk_python_files(root))
+        with self._lock:
+            self._symbols[handle] = result.symbols
+            self._roots[handle] = root
+            self._module_maps[handle] = module_map
+        return len(result.symbols)
+
+    def update_file(self, handle: Handle, path: Path) -> None:
+        """Re-parse a single file and replace its symbols in the index."""
+        root = self._roots.get(handle)
+        if root is None:
+            return
+        try:
+            rel = str(path.relative_to(root)).replace("\\", "/")
+        except ValueError:
+            return
+        file_result = parse_file(path, root, self._module_maps.get(handle))
+        with self._lock:
+            existing = self._symbols.get(handle, [])
+            kept = [s for s in existing if s.file != rel]
+            self._symbols[handle] = kept + (
+                [] if file_result.skipped else file_result.symbols
+            )
+
+    def remove_file(self, handle: Handle, path: Path) -> None:
+        """Drop all symbols for a deleted file."""
+        root = self._roots.get(handle)
+        if root is None:
+            return
+        try:
+            rel = str(path.relative_to(root)).replace("\\", "/")
+        except ValueError:
+            return
+        with self._lock:
+            existing = self._symbols.get(handle)
+            if existing is not None:
+                self._symbols[handle] = [s for s in existing if s.file != rel]
+
+    def evict(self, handle: Handle) -> None:
+        with self._lock:
+            self._symbols.pop(handle, None)
+            self._roots.pop(handle, None)
+            self._module_maps.pop(handle, None)
+
+    def has(self, handle: Handle) -> bool:
+        with self._lock:
+            return handle in self._symbols
+
+    def get_root(self, handle: Handle) -> Path | None:
+        return self._roots.get(handle)
+
+    def get_symbols(self, handle: Handle) -> list[Symbol] | None:
+        with self._lock:
+            symbols = self._symbols.get(handle)
+            return list(symbols) if symbols is not None else None
+
+    def outline(self, handle: Handle, query: str, k: int = 20) -> list[Symbol]:
+        """Fuzzy lexical search over symbol names and file paths."""
+        symbols = self.get_symbols(handle) or []
+        if not symbols:
+            return []
+        choices = [f"{s.name} {s.file}" for s in symbols]
+        results = process.extract(
+            query, choices, scorer=fuzz.WRatio, limit=k, score_cutoff=35
+        )
+        return [symbols[idx] for _, _, idx in results]
+
+    def outline_paths(
+        self, handle: Handle, paths: list[str]
+    ) -> tuple[list[Symbol], list[str]]:
+        """Exact-file symbol outline lookup for a batch of paths, bypassing fuzzy search."""
+        symbols = self.get_symbols(handle) or []
+        by_file: dict[str, list[Symbol]] = {}
+        for s in symbols:
+            by_file.setdefault(s.file, []).append(s)
+
+        matched: list[Symbol] = []
+        warnings: list[str] = []
+        for p in paths:
+            if p in by_file:
+                matched.extend(by_file[p])
+            else:
+                warnings.append(f"no symbols found for path: {p!r}")
+        return matched, warnings
+
+    def find(self, handle: Handle, symbol: str) -> list[Symbol]:
+        """Substring match by symbol name."""
+        symbols = self.get_symbols(handle) or []
+        return [s for s in symbols if symbol in s.name]

eulerian-0.1.0/src/eulerian/mcp/__init__.py

@@ -0,0 +1 @@
+"""eulerian MCP server package."""

eulerian-0.1.0/src/eulerian/mcp/_instance.py

@@ -0,0 +1,14 @@
+"""FastMCP singleton — leaf module with no package imports."""
+
+from fastmcp import FastMCP
+
+server = FastMCP(
+    name="eulerian",
+    instructions=(
+        "Real-time code navigation. Local mode: call watch(path) once, then "
+        "outline/find/read against it — the index reflects on-disk edits "
+        "instantly, no re-indexing calls needed. Repo mode: repo_add a git "
+        "remote, checkout a ref, then repo_outline/repo_read against it — "
+        "freshness is checked against the remote on each call."
+    ),
+)

eulerian-0.1.0/src/eulerian/mcp/server.py

@@ -0,0 +1,7 @@
+"""FastMCP server entry point — importing tools registers their @server.tool() decorators."""
+
+from __future__ import annotations
+
+from ._instance import server  # noqa: F401 — re-exported; callers do `from .mcp.server import server`
+
+from . import tools  # noqa: F401, E402