navcode 0.1.0__py3-none-any.whl

navcode/__init__.py

@@ -0,0 +1,22 @@
+from navcode._bootstrap import ensure_model
+from loguru import logger
+from pathlib import Path
+
+__version__ = "0.1.0"
+
+ensure_model()
+
+
+def _setup_logging() -> None:
+    log_dir = Path.cwd() / ".codenav"
+    if log_dir.exists():
+        logger.add(
+            log_dir / "navcode.log",
+            rotation="5 MB",
+            retention="7 days",
+            level="INFO",
+            format="{time:YYYY-MM-DD HH:mm:ss} | {level} | {message}",
+        )
+
+
+_setup_logging()

navcode/_bootstrap.py

@@ -0,0 +1,122 @@
+"""Bootstrap utilities — ensures the ONNX embedding model is present on disk."""
+
+from pathlib import Path
+
+import httpx
+from loguru import logger
+from rich.console import Console
+from rich.panel import Panel
+from rich.progress import (
+    BarColumn,
+    DownloadColumn,
+    Progress,
+    TextColumn,
+    TimeRemainingColumn,
+    TransferSpeedColumn,
+)
+
+_HF_BASE: str = (
+    "https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main"
+)
+MODEL_URL: str = f"{_HF_BASE}/onnx/model_quantized.onnx"
+MODEL_PATH: Path = Path.home() / ".navcode" / "models" / "model_quantized.onnx"
+
+# Tokenizer files required by EmbeddingsEngine
+_TOKENIZER_FILES: list[str] = [
+    "tokenizer.json",
+    "tokenizer_config.json",
+    "vocab.txt",
+    "special_tokens_map.json",
+]
+
+_console = Console()
+
+
+def _download_file(url: str, dest: Path, label: str) -> None:
+    """Stream *url* to *dest* with a Rich progress bar.
+
+    Raises:
+        httpx.HTTPError: on any HTTP-level failure.
+    """
+    with httpx.stream("GET", url, follow_redirects=True, timeout=60) as response:
+        response.raise_for_status()
+        total = int(response.headers.get("content-length", 0)) or None
+
+        with Progress(
+            TextColumn(f"[bold blue]{label}[/bold blue]"),
+            BarColumn(),
+            DownloadColumn(),
+            TransferSpeedColumn(),
+            TimeRemainingColumn(),
+            console=_console,
+            transient=True,
+        ) as progress:
+            task = progress.add_task("download", total=total)
+            with dest.open("wb") as fh:
+                for chunk in response.iter_bytes(chunk_size=8192):
+                    fh.write(chunk)
+                    progress.update(task, advance=len(chunk))
+
+
+def ensure_model() -> None:
+    """Ensure the quantised ONNX embedding model exists locally.
+
+    If the model file is already present at ``~/.navcode/models/model_quantized.onnx``
+    this function returns immediately.  On first run it streams the file from
+    HuggingFace, displaying a Rich progress bar.  Network failures are caught,
+    shown as a Rich warning panel, and silently swallowed so the rest of navcode
+    can still load (the model will be re-attempted on ``navcode init``).
+    """
+    if MODEL_PATH.exists():
+        logger.debug("ONNX model already present at {}", MODEL_PATH)
+    else:
+        MODEL_PATH.parent.mkdir(parents=True, exist_ok=True)
+        logger.info("ONNX model not found — downloading from HuggingFace…")
+
+        try:
+            _download_file(MODEL_URL, MODEL_PATH, "Downloading model")
+            logger.info("Model saved to {}", MODEL_PATH)
+        except httpx.HTTPError as exc:
+            _console.print(
+                Panel(
+                    f"[yellow]navcode[/yellow] could not download the embedding model.\n"
+                    f"[dim]{exc}[/dim]\n\n"
+                    "navcode will still load — the model will be downloaded on first "
+                    "[cyan]navcode init[/cyan].",
+                    title="[bold yellow]⚠ Model download skipped[/bold yellow]",
+                    border_style="yellow",
+                )
+            )
+            logger.warning("Model download failed: {}", exc)
+
+    # Ensure tokenizer files are present alongside the model
+    _ensure_tokenizer_files()
+
+
+def _ensure_tokenizer_files() -> None:
+    """Download any missing tokenizer files from HuggingFace."""
+    models_dir = MODEL_PATH.parent
+    models_dir.mkdir(parents=True, exist_ok=True)
+
+    for filename in _TOKENIZER_FILES:
+        dest = models_dir / filename
+        if dest.exists():
+            logger.debug("Tokenizer file already present: {}", filename)
+            continue
+
+        url = f"{_HF_BASE}/{filename}"
+        logger.info("Tokenizer file not found — downloading: {}", filename)
+        try:
+            _download_file(url, dest, f"Downloading {filename}")
+            logger.info("Saved {}", dest)
+        except httpx.HTTPError as exc:
+            _console.print(
+                Panel(
+                    f"[yellow]navcode[/yellow] could not download [cyan]{filename}[/cyan].\n"
+                    f"[dim]{exc}[/dim]\n\n"
+                    "Semantic search may be unavailable until this file is present.",
+                    title="[bold yellow]⚠ Tokenizer file download skipped[/bold yellow]",
+                    border_style="yellow",
+                )
+            )
+            logger.warning("Tokenizer file download failed ({}): {}", filename, exc)

navcode/adapters/__init__.py

@@ -0,0 +1,36 @@
+"""navcode agent adapters — one per supported AI coding agent."""
+
+from navcode.adapters.claude import ClaudeAdapter
+from navcode.adapters.cursor import CursorAdapter
+from navcode.adapters.codex import CodexAdapter
+from navcode.adapters.copilot import CopilotAdapter
+from navcode.adapters.bob import BobAdapter
+from navcode.adapters.kimi import KimiAdapter
+from navcode.adapters.antigravity import AntigravityAdapter
+from navcode.adapters.windsurf import WindsurfAdapter
+from navcode.adapters.continue_ import ContinueAdapter
+
+ALL_ADAPTERS = {
+    "claude":      ClaudeAdapter,
+    "cursor":      CursorAdapter,
+    "codex":       CodexAdapter,
+    "copilot":     CopilotAdapter,
+    "bob":         BobAdapter,
+    "kimi":        KimiAdapter,
+    "antigravity": AntigravityAdapter,
+    "windsurf":    WindsurfAdapter,
+    "continue":    ContinueAdapter,
+}
+
+__all__ = [
+    "ClaudeAdapter",
+    "CursorAdapter",
+    "CodexAdapter",
+    "CopilotAdapter",
+    "BobAdapter",
+    "KimiAdapter",
+    "AntigravityAdapter",
+    "WindsurfAdapter",
+    "ContinueAdapter",
+    "ALL_ADAPTERS",
+]

navcode/adapters/antigravity.py

@@ -0,0 +1,31 @@
+"""Antigravity adapter."""
+
+from pathlib import Path
+
+from navcode.adapters.base import BaseAdapter
+
+
+class AntigravityAdapter(BaseAdapter):
+
+    NAME = "Antigravity"
+    BINARY = "antigravity"
+    CONFIG_DIR = "~/.antigravity"
+    PROJECT_DIR = ".antigravity"
+    PROCESS_NAME = "antigravity"
+    INSTRUCTION_FILE = ".antigravity/instructions.md"
+
+    def install(self) -> None:
+        self._write_instruction_file(
+            self.project_root / ".antigravity" / "instructions.md",
+            self._instruction_content(),
+        )
+        self._inject_mcp_config(
+            Path.home() / ".antigravity" / "mcp.json"
+        )
+
+    def is_detected(self) -> bool:
+        return (
+            self._detect_binary()
+            or self._detect_config_dir()
+            or self._detect_project_dir()
+        )

navcode/adapters/base.py

@@ -0,0 +1,100 @@
+"""Abstract base class for all navcode agent adapters."""
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+
+class BaseAdapter(ABC):
+
+    # Override these in every adapter
+    NAME: str = ""
+    BINARY: str = ""
+    CONFIG_DIR: str = ""
+    PROJECT_DIR: str = ""
+    PROCESS_NAME: str | None = None
+    INSTRUCTION_FILE: str = ""
+
+    def __init__(self, project_root: Path):
+        self.project_root = project_root
+        self.codenav_dir = project_root / ".codenav"
+
+    @abstractmethod
+    def install(self) -> None:
+        """Create all required files for this agent."""
+        pass
+
+    @abstractmethod
+    def is_detected(self) -> bool:
+        """Return True if this agent is installed on the system."""
+        pass
+
+    def _write_instruction_file(self, path: Path, content: str) -> None:
+        """Write instruction file, create parent dirs if needed."""
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(content, encoding="utf-8")
+
+    def _inject_mcp_config(self, config_path: Path) -> None:
+        """Inject navcode MCP entry into agent JSON config."""
+        import json
+
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+
+        existing = {}
+        if config_path.exists():
+            try:
+                existing = json.loads(config_path.read_text())
+            except json.JSONDecodeError:
+                pass
+
+        existing.setdefault("mcpServers", {})
+        existing["mcpServers"]["navcode"] = {
+            "command": "navcode",
+            "args": ["mcp-serve"],
+            "cwd": str(self.project_root),
+        }
+        config_path.write_text(
+            json.dumps(existing, indent=2),
+            encoding="utf-8",
+        )
+
+    def _detect_binary(self) -> bool:
+        import shutil
+
+        return shutil.which(self.BINARY) is not None
+
+    def _detect_config_dir(self) -> bool:
+        return Path.home().joinpath(
+            self.CONFIG_DIR.lstrip("~/")
+        ).exists()
+
+    def _detect_project_dir(self) -> bool:
+        return (self.project_root / self.PROJECT_DIR).exists()
+
+    def _instruction_content(self) -> str:
+        return f"""# navcode — Active
+
+## Rules for {self.NAME}
+
+NEVER use read_file or list_directory to explore the codebase.
+ALWAYS start every task with navcode_get_context(task=<your task>).
+Work ONLY within files and symbols navcode returns.
+If you need more: call navcode_expand_context(file_path, reason).
+
+## Available MCP Tools
+
+| Tool | When to use |
+|---|---|
+| navcode_get_context(task) | FIRST call — always |
+| navcode_expand_context(file, reason) | Need more from one file |
+| navcode_get_callers(function) | Understand blast radius |
+| navcode_get_deps(file) | See what a file imports |
+| navcode_search(query) | Find where something is defined |
+| navcode_get_structure() | Architectural overview |
+| navcode_stats() | Index health check |
+
+## Why
+navcode has pre-indexed this codebase.
+Using it saves 80-90% tokens vs raw file reads.
+
+Built by Nythris Studio
+"""

navcode/adapters/bob.py

@@ -0,0 +1,33 @@
+"""IBM Bob adapter."""
+
+from pathlib import Path
+
+from navcode.adapters.base import BaseAdapter
+
+
+class BobAdapter(BaseAdapter):
+
+    NAME = "IBM Bob"
+    BINARY = "bob"
+    CONFIG_DIR = "~/.bob"
+    PROJECT_DIR = ".bob"
+    PROCESS_NAME = "bob-agent"
+    INSTRUCTION_FILE = ".bob/instructions.md"
+
+    def install(self) -> None:
+        # 1. Write .bob/instructions.md
+        self._write_instruction_file(
+            self.project_root / ".bob" / "instructions.md",
+            self._instruction_content(),
+        )
+        # 2. Inject MCP into ~/.bob/mcp.json
+        self._inject_mcp_config(
+            Path.home() / ".bob" / "mcp.json"
+        )
+
+    def is_detected(self) -> bool:
+        return (
+            self._detect_binary()
+            or self._detect_config_dir()
+            or self._detect_project_dir()
+        )

navcode/adapters/claude.py

@@ -0,0 +1,33 @@
+"""Claude Code adapter."""
+
+from pathlib import Path
+
+from navcode.adapters.base import BaseAdapter
+
+
+class ClaudeAdapter(BaseAdapter):
+
+    NAME = "Claude Code"
+    BINARY = "claude"
+    CONFIG_DIR = "~/.claude"
+    PROJECT_DIR = "CLAUDE.md"
+    PROCESS_NAME = None
+    INSTRUCTION_FILE = "CLAUDE.md"
+
+    def install(self) -> None:
+        # 1. Write CLAUDE.md to project root
+        self._write_instruction_file(
+            self.project_root / "CLAUDE.md",
+            self._instruction_content(),
+        )
+        # 2. Inject MCP into ~/.claude/mcp.json
+        self._inject_mcp_config(
+            Path.home() / ".claude" / "mcp.json"
+        )
+
+    def is_detected(self) -> bool:
+        return (
+            self._detect_binary()
+            or self._detect_config_dir()
+            or self._detect_project_dir()
+        )

navcode/adapters/codex.py

@@ -0,0 +1,33 @@
+"""Codex CLI adapter."""
+
+from pathlib import Path
+
+from navcode.adapters.base import BaseAdapter
+
+
+class CodexAdapter(BaseAdapter):
+
+    NAME = "Codex CLI"
+    BINARY = "codex"
+    CONFIG_DIR = "~/.codex"
+    PROJECT_DIR = "AGENTS.md"
+    PROCESS_NAME = None
+    INSTRUCTION_FILE = "AGENTS.md"
+
+    def install(self) -> None:
+        # 1. Write AGENTS.md
+        self._write_instruction_file(
+            self.project_root / "AGENTS.md",
+            self._instruction_content(),
+        )
+        # 2. Inject MCP into ~/.codex/config.json
+        self._inject_mcp_config(
+            Path.home() / ".codex" / "config.json"
+        )
+
+    def is_detected(self) -> bool:
+        return (
+            self._detect_binary()
+            or self._detect_config_dir()
+            or self._detect_project_dir()
+        )

navcode/adapters/continue_.py

@@ -0,0 +1,31 @@
+"""Continue adapter."""
+
+from pathlib import Path
+
+from navcode.adapters.base import BaseAdapter
+
+
+class ContinueAdapter(BaseAdapter):
+
+    NAME = "Continue"
+    BINARY = "continue"
+    CONFIG_DIR = "~/.continue"
+    PROJECT_DIR = ".continue"
+    PROCESS_NAME = None
+    INSTRUCTION_FILE = ".continue/navcode.md"
+
+    def install(self) -> None:
+        self._write_instruction_file(
+            self.project_root / ".continue" / "navcode.md",
+            self._instruction_content(),
+        )
+        self._inject_mcp_config(
+            Path.home() / ".continue" / "config.json"
+        )
+
+    def is_detected(self) -> bool:
+        return (
+            self._detect_binary()
+            or self._detect_config_dir()
+            or self._detect_project_dir()
+        )

navcode/adapters/copilot.py

@@ -0,0 +1,24 @@
+"""GitHub Copilot adapter."""
+
+from navcode.adapters.base import BaseAdapter
+
+
+class CopilotAdapter(BaseAdapter):
+
+    NAME = "GitHub Copilot"
+    BINARY = "gh"
+    CONFIG_DIR = "~/.config/gh"
+    PROJECT_DIR = ".github"
+    PROCESS_NAME = None
+    INSTRUCTION_FILE = ".github/copilot-instructions.md"
+
+    def install(self) -> None:
+        # Write .github/copilot-instructions.md
+        self._write_instruction_file(
+            self.project_root / ".github" / "copilot-instructions.md",
+            self._instruction_content(),
+        )
+        # No MCP config for Copilot yet
+
+    def is_detected(self) -> bool:
+        return self._detect_binary() or self._detect_project_dir()

navcode/adapters/cursor.py

@@ -0,0 +1,33 @@
+"""Cursor adapter."""
+
+from pathlib import Path
+
+from navcode.adapters.base import BaseAdapter
+
+
+class CursorAdapter(BaseAdapter):
+
+    NAME = "Cursor"
+    BINARY = "cursor"
+    CONFIG_DIR = "~/.cursor"
+    PROJECT_DIR = ".cursor"
+    PROCESS_NAME = "cursor"
+    INSTRUCTION_FILE = ".cursor/rules/navcode.md"
+
+    def install(self) -> None:
+        # 1. Write .cursor/rules/navcode.md
+        self._write_instruction_file(
+            self.project_root / ".cursor" / "rules" / "navcode.md",
+            self._instruction_content(),
+        )
+        # 2. Inject MCP into .cursor/mcp.json
+        self._inject_mcp_config(
+            self.project_root / ".cursor" / "mcp.json"
+        )
+
+    def is_detected(self) -> bool:
+        return (
+            self._detect_binary()
+            or self._detect_config_dir()
+            or self._detect_project_dir()
+        )

navcode/adapters/kimi.py

@@ -0,0 +1,31 @@
+"""Kimi Code adapter."""
+
+from pathlib import Path
+
+from navcode.adapters.base import BaseAdapter
+
+
+class KimiAdapter(BaseAdapter):
+
+    NAME = "Kimi Code"
+    BINARY = "kimi"
+    CONFIG_DIR = "~/.kimi"
+    PROJECT_DIR = "KIMI.md"
+    PROCESS_NAME = None
+    INSTRUCTION_FILE = "KIMI.md"
+
+    def install(self) -> None:
+        self._write_instruction_file(
+            self.project_root / "KIMI.md",
+            self._instruction_content(),
+        )
+        self._inject_mcp_config(
+            Path.home() / ".kimi" / "mcp.json"
+        )
+
+    def is_detected(self) -> bool:
+        return (
+            self._detect_binary()
+            or self._detect_config_dir()
+            or self._detect_project_dir()
+        )

navcode/adapters/windsurf.py

@@ -0,0 +1,29 @@
+"""Windsurf adapter."""
+
+from navcode.adapters.base import BaseAdapter
+
+
+class WindsurfAdapter(BaseAdapter):
+
+    NAME = "Windsurf"
+    BINARY = "windsurf"
+    CONFIG_DIR = "~/.codeium/windsurf"
+    PROJECT_DIR = ".windsurf"
+    PROCESS_NAME = "windsurf"
+    INSTRUCTION_FILE = ".windsurf/rules/navcode.md"
+
+    def install(self) -> None:
+        self._write_instruction_file(
+            self.project_root / ".windsurf" / "rules" / "navcode.md",
+            self._instruction_content(),
+        )
+        self._inject_mcp_config(
+            self.project_root / ".windsurf" / "mcp.json"
+        )
+
+    def is_detected(self) -> bool:
+        return (
+            self._detect_binary()
+            or self._detect_config_dir()
+            or self._detect_project_dir()
+        )