codevira 1.6.0__py3-none-any.whl

mcp_server/data/rules/master_rule.md

@@ -0,0 +1,187 @@
+---
+trigger: always_on
+---
+
+# MASTER RULESET FOR AI CODE AGENTS (AUTHORITATIVE, NON-DILUTING)
+
+This document defines HOW the AI code agent must behave.
+It does NOT replace or override any existing rules.
+It unifies them into a single, enforceable operating contract.
+
+────────────────────────────────────────
+0. CORE MENTAL MODEL (NON-NEGOTIABLE)
+────────────────────────────────────────
+
+INTENT and REALITY are different.
+
+- INTENT is decided consciously and preserved.
+- REALITY is executed factually and recorded.
+- CODE is only allowed to freeze when both are aligned.
+
+LLM reasons
+→ System decides
+→ Code enforces
+→ Graph / Roadmap preserves intent
+→ Session Logs preserve truth
+→ FAQ preserves explanation
+→ Git freezes verified state
+
+────────────────────────────────────────
+1. AUTOMATED MEMORY & KNOWLEDGE SYSTEM (CODEVIRA)
+────────────────────────────────────────
+
+### A. ARCHITECTURAL MEMORY (INTENT)
+Tools: `update_node()`, `add_phase()`, `complete_phase()`, `update_next_action()`
+Storage: `.codevira/graph/` and `.codevira/roadmap.yaml`
+
+Purpose:
+- Preserve architectural intent and direction via Graph Rules.
+- Capture final decisions as `key_decisions` in Roadmap phases.
+- Record "never do this again" invariants as `rules` on specific file nodes.
+
+Rules:
+- Graph Rules and the Roadmap represent the "Project Law."
+- Any architectural change:
+  - MUST be explicitly approved by the user.
+  - MUST be persisted via `update_node` (new rules) or `complete_phase` (decisions).
+  - MUST be logically linked in the session log.
+
+---
+
+### B. EXECUTION MEMORY (TRUTH)
+Tool: `write_session_log()`
+Storage: `.codevira/logs/` (YAML)
+
+Purpose:
+- Preserve factual reality of what happened in each session.
+- Prevent "token re-discovery" in future sessions.
+
+Must record:
+- The Evolution: What was suggested vs. what was actually built.
+- The "Wrong" Paths: Rejected ideas and failed attempts.
+- The "Why": Underlying logic and trade-offs.
+- The "What": Precise technical changes.
+
+Rules:
+- Every session MUST end with a `write_session_log` call.
+- If it is not logged in the codevira history → it does not exist.
+
+---
+
+### C. FAQ / USER KNOWLEDGE
+File: `docs/FAQ.md`
+
+Purpose:
+- Human-readable explanation of complex behaviors and non-obvious trade-offs.
+
+Update FAQ whenever:
+- A behavior or workflow is finalized.
+- A technical limitation is accepted.
+- A previous decision is reversed.
+
+ENFORCEMENT:
+- If behavior changed but FAQ is not updated → WORK IS INCOMPLETE.
+- Agent MUST STOP.
+- No further coding, execution, or commits allowed.
+
+────────────────────────────────────────
+2. AGENT BEHAVIOR RULES
+────────────────────────────────────────
+
+1. READ BEFORE ACT
+   Always review project memory (roadmap, graph nodes) before doing anything.
+   If missing, outdated, or unclear → STOP and ask.
+
+2. INTENT ≠ REALITY
+   - Intent → memory/roadmap
+   - Reality → session logs
+   Never mix them.
+
+3. NO DRIFT
+   Do NOT introduce new tools, APIs, architectures, or patterns
+   unless explicitly requested.
+
+4. NO GUESSING
+   If ambiguous, unsafe, or conflicting → FAIL FAST and explain risk.
+
+5. SMALL & REVERSIBLE
+   - Minimal diffs only
+   - Wrap, don't rewrite
+   - Refactors only for correctness
+   - Schema, memory, persistence, telemetry changes are NEVER assumed reversible
+
+6. EXECUTION SAFETY
+   - Unsafe or unvalidated output must NEVER reach execution layers
+   - Compiler / validator rules override LLM output
+
+7. NO SILENT FALLBACKS
+   Any fallback, heuristic, bypass, or degraded mode MUST be:
+   - Explicit
+   - Logged
+   - Visible to the user
+
+────────────────────────────────────────
+3. CONFLICT RULE (ABSOLUTE)
+────────────────────────────────────────
+
+If a request conflicts with documented architectural decisions:
+- STOP immediately
+- Explain the conflict
+- Cite the violated rule
+- DO NOT implement
+
+────────────────────────────────────────
+4. CHANGE MANAGEMENT RULE
+────────────────────────────────────────
+
+Whenever behavior, logic, or architecture changes:
+
+1. Log the change in session log
+2. If intent changed → update memory ONLY after user approval
+3. Update FAQ explaining:
+   - What changed
+   - Why it changed
+   - Impact and trade-offs
+
+Skipping any step = incomplete work.
+
+────────────────────────────────────────
+5. GIT COMMIT RULES (GATEKEEPER ONLY)
+────────────────────────────────────────
+
+Commits DO NOT decide intent.
+Commits ONLY freeze verified state.
+
+### A. COMMIT AUTHORITY
+- NEVER commit unless the user explicitly commands it.
+
+### B. PRE-COMMIT CHECKS (ALL REQUIRED)
+Before committing, verify:
+
+- Session log entries exist for all work
+- Memory changes (if any) were explicitly approved
+- FAQ updated if decision/behavior changed
+- Docs updated if applicable
+- No partial or inconsistent state remains
+
+If any check fails → DO NOT COMMIT.
+
+### C. COMMIT MESSAGE REQUIREMENTS
+- One-line commits are NOT allowed
+- Commit message MUST explain:
+  - Context
+  - What changed
+  - Why it changed
+  - Decisions reinforced or changed
+  - Docs updated
+
+Commits are permanent explanation, not just history.
+
+────────────────────────────────────────
+FINAL RULE (NEVER VIOLATE)
+────────────────────────────────────────
+
+If future you cannot answer:
+"WHAT did we do, WHY did we do it, and WHAT changed?"
+
+Then the agent has failed — even if the code works.

mcp_server/data/rules/multi-language.md

@@ -0,0 +1,19 @@
+# Multi-Language Project Rules
+
+## TypeScript / TSX
+- When adding a new module, re-export it from the barrel `index.ts`.
+- Prefer `export function` over `export default` for named symbols.
+- Use JSDoc `/** */` comments for public APIs — they are extracted by the indexer.
+- When adding React components, co-locate styles and tests in the same directory.
+
+## Go
+- Exported symbols start with an uppercase letter. Name unexported helpers with lowercase.
+- When adding a new HTTP handler, register it in the router (e.g., `routes.go`).
+- Follow the `func (s *Server) handleX(w http.ResponseWriter, r *http.Request)` pattern.
+- Add a `// Package <name>` doc comment at the top of each package's primary file.
+
+## Rust
+- When adding a new module, declare it in `mod.rs` or `lib.rs` with `pub mod <name>;`.
+- Use `///` doc comments for public APIs — they are extracted by the indexer.
+- Prefer `pub fn` for the public API surface; keep internals private by default.
+- When adding a trait, provide a default implementation where sensible.

mcp_server/data/rules/persistence.md

@@ -0,0 +1,21 @@
+---
+trigger: always_on
+---
+
+# Artifact and State Persistence Rule
+
+## Objective
+To ensure all project intelligence, planning, and task data are stored locally within the project workspace for version control and persistence, rather than the IDE's temporary internal environment.
+
+## Mandatory Procedures
+1. **Automated State Tracking**: Every time a decision is finalized or a phase is completed, use Codevira's roadmap tools (`complete_phase()`, `add_phase()`) to persist the data locally.
+2. **Local Repository Truth**: Use `.codevira/` instead of any IDE temporary internal environment.
+3. **Session Handover**: At the start of every session, you must call `get_roadmap()` and `get_full_roadmap()` to synchronize your internal state with the files stored on disk.
+4. **No Temporary-Only Storage**: Do not finalize a task until the corresponding documentation (FAQ, Roadmap, Logs) has been committed to the local project file system.
+
+## Directory Structure
+Ensure the following structure is maintained:
+- `[project-root]/rules/` (Architectural Rules)
+- `[project-root]/.codevira/graph/` (File context and rules)
+- `[project-root]/.codevira/logs/` (Session truth history)
+- `[project-root]/.codevira/roadmap.yaml` (Project planning and status)

mcp_server/data/rules/resilience-observability.md

@@ -0,0 +1,17 @@
+# Rule 009: Resilience and Observability
+
+## 1. Fault Tolerance
+
+- **Retries**: Use exponential backoff for transient failures (git subprocess calls, file I/O).
+- **Timeouts**: Every subprocess call MUST have a defined timeout (e.g., `timeout=3` for git commands).
+- **Graceful Degradation**: When optional dependencies are missing (chromadb, tree-sitter), tools MUST continue with reduced functionality rather than crashing.
+
+## 2. Observability
+
+- **Structured Logging**: Use Python `logging` module with context metadata rather than raw print statements.
+- **Crash Logging**: All unhandled exceptions are captured to `~/.codevira/logs/crashes.log` with automatic sanitization of sensitive data (connection strings, passwords, private IPs).
+
+## 3. Security
+
+- **Crash logs MUST NOT contain PII**: The crash logger sanitizes connection strings, key=value secrets, and home directory paths before writing to disk.
+- **MCP tool responses MUST NOT expose raw secrets**: Connection strings, API keys, and tokens MUST be masked before returning to the AI agent.

mcp_server/data/rules/smoke-testing.md

@@ -0,0 +1,48 @@
+# Rule 013: Smoke Testing & Edge Case Hardening
+
+## Objective
+To ensure the system remains robust under extreme conditions, invalid inputs, and infrastructure failures. All major features MUST be accompanied by a comprehensive "Smoke Test" suite that covers positive, negative, and boundary scenarios.
+
+## 1. The Smoke Test Manifesto
+Smoke tests are NOT unit tests. They verify end-to-end system health and resilience.
+- **Fail Fast**: If a smoke test fails, the build/deployment MUST abort.
+- **Infrastructure Aware**: Tests must gracefully handle simulation vs. production providers.
+- **State Neutral**: Tests must clean up after themselves or use isolated namespaces.
+
+## 2. Mandatory Edge Case Coverage
+Every Smoke Test suite MUST include the following scenarios:
+
+### A. Input Extremes
+- **Empty/Whitespace**: "", "   ", "\n"
+- **Massive Input**: 100KB+ queries or payloads.
+- **Unicode/Multilingual**: Emoji, non-Latin scripts (CJK, Cyrillic, Hindi).
+- **Special Characters**: SQL injection characters (', ", ;, --), control characters.
+
+### B. Parameter Boundaries
+- **Limits**: limit=0, limit=-1, limit=999999999
+- **Thresholds**: Below 0.0, above 1.0, exactly 0 or 1.
+- **Timeframes**: Distant past (1970), far future (2099), current second.
+
+### C. Infrastructure Resilience (Chaos)
+- **Closed Circuit**: Normal operation.
+- **Open Circuit**: System must return InfrastructureError or graceful fallback, NOT hang.
+- **Retry Success**: System must succeed on 2nd or 3rd attempt if initial call fails.
+- **Latency**: System must handle slow response times (timeouts).
+
+### D. Idempotency & Concurrency
+- **Double-Run**: Executing the same command twice must produce identical results/state.
+- **Race conditions**: Concurrent writes to the same entity/pattern must be protected by locks.
+
+## 3. Implementation Standard
+1. **Verification Scripts**: Use scripts/verify_<feature>.py.
+2. **Rich Feedback**: Use core.logging and rich for clear PASS/FAIL reporting.
+3. **Exit Codes**: Return non-zero exit code on any failure.
+
+## 5. Verification Etiquette & Safety
+
+- **Non-Destructive by Default**: Smoke tests MUST NOT perform destructive actions (like `shutdown`) as part of a shared suite (`verify_all.py`) unless explicitly marked as a "Final/Clean-up" step.
+- **Reentrant-Proof**: If a test creates data, it should use a unique `id` or cleanup after itself to avoid failing on a second run.
+- **Authentication Resilience**: 
+    - Health checks should remain public.
+    - Data APIs should require auth but the test suite MUST handle missing secrets gracefully (warn/skip rather than fail) to allow for basic health verification.
+- **Connectivity Check**: Before running complex API tests, the suite MUST verify that the target service is actually online.

mcp_server/data/rules/testing-standards.md

@@ -0,0 +1,23 @@
+# Rule 006: Testing Standards
+
+## 1. Test Categories
+
+| Category | Location | Purpose | I/O |
+|----------|----------|---------|-----|
+| Unit | `tests/` | Isolated functions, 1:1 per source file | None |
+| Integration | `tests/integration/` | Cross-module flows | Real |
+| E2E | `tests/e2e/` | Full system verify | Real |
+
+## 2. Test Coverage Requirements
+- Every new MCP tool MUST have corresponding unit tests.
+- Every new module MUST have a matching `tests/test_<module>.py` file.
+
+## 3. Test Naming & Structure
+
+- **Naming Pattern**: `test_<action>_<condition>_<expected_result>`.
+- **Example**: `test_search_with_empty_query_returns_empty_list()`.
+
+## 4. Verification Policy
+- "If it'\''s not tested, it doesn'\''t exist."
+- All new features MUST include at least unit tests.
+- Infrastructure changes MUST include contract tests.

mcp_server/detect.py

@@ -0,0 +1,284 @@
+"""
+detect.py — Zero-config project auto-detection.
+
+Detects language, source directories, file extensions, and project name
+from project markers (package.json, go.mod, Cargo.toml, etc.) with zero
+interactive prompts. Supports 15+ languages.
+"""
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Language marker map — checked in order, first match wins
+# ---------------------------------------------------------------------------
+
+LANGUAGE_MARKERS: list[tuple[str, str]] = [
+    ("Cargo.toml", "rust"),
+    ("go.mod", "go"),
+    ("tsconfig.json", "typescript"),
+    ("pyproject.toml", "python"),
+    ("setup.py", "python"),
+    ("setup.cfg", "python"),
+    ("requirements.txt", "python"),
+    ("pom.xml", "java"),
+    ("build.gradle.kts", "kotlin"),
+    ("build.gradle", "java"),
+    ("Gemfile", "ruby"),
+    ("Package.swift", "swift"),
+    ("composer.json", "php"),
+    ("CMakeLists.txt", "cpp"),
+    # package.json last — needs disambiguation between TS and JS
+    ("package.json", "_js_or_ts"),
+]
+
+# ---------------------------------------------------------------------------
+# Per-language conventions
+# ---------------------------------------------------------------------------
+
+LANGUAGE_DIRS: dict[str, list[str]] = {
+    "python": ["src", "lib", "app"],
+    "typescript": ["src", "lib", "app", "pages", "components"],
+    "javascript": ["src", "lib", "app", "pages", "components"],
+    "go": ["cmd", "pkg", "internal"],
+    "rust": ["src"],
+    "java": ["src/main/java", "src"],
+    "kotlin": ["src/main/kotlin", "src"],
+    "ruby": ["lib", "app"],
+    "csharp": ["src"],
+    "cpp": ["src", "include", "lib"],
+    "c": ["src", "include", "lib"],
+    "swift": ["Sources", "src"],
+    "php": ["src", "app", "lib"],
+}
+
+LANGUAGE_EXTENSIONS: dict[str, list[str]] = {
+    "python": [".py"],
+    "typescript": [".ts", ".tsx"],
+    "javascript": [".js", ".jsx"],
+    "go": [".go"],
+    "rust": [".rs"],
+    "java": [".java"],
+    "kotlin": [".kt", ".kts"],
+    "ruby": [".rb"],
+    "csharp": [".cs"],
+    "cpp": [".cpp", ".cc", ".cxx", ".h", ".hpp"],
+    "c": [".c", ".h"],
+    "swift": [".swift"],
+    "php": [".php"],
+    "solidity": [".sol"],
+    "vue": [".vue"],
+}
+
+# Reverse map: extension → language (for fallback scanning)
+_EXT_TO_LANG: dict[str, str] = {}
+for _lang, _exts in LANGUAGE_EXTENSIONS.items():
+    for _ext in _exts:
+        if _ext not in _EXT_TO_LANG:  # first language wins
+            _EXT_TO_LANG[_ext] = _lang
+
+
+# ---------------------------------------------------------------------------
+# Detection functions
+# ---------------------------------------------------------------------------
+
+def detect_language(root: Path) -> str:
+    """Detect primary language from project markers. Falls back to file extension scan."""
+    root = root.resolve()
+
+    for marker, lang in LANGUAGE_MARKERS:
+        if (root / marker).exists():
+            if lang == "_js_or_ts":
+                return _disambiguate_js_ts(root)
+            return lang
+
+    # Fallback: scan files 2 levels deep, count extensions
+    return _scan_dominant_language(root)
+
+
+def _disambiguate_js_ts(root: Path) -> str:
+    """Determine if a package.json project is TypeScript or JavaScript."""
+    if (root / "tsconfig.json").exists():
+        return "typescript"
+
+    # Check for any .ts/.tsx files in first 2 levels
+    for depth_glob in ["*.ts", "*.tsx", "*/*.ts", "*/*.tsx", "*/*/*.ts"]:
+        if list(root.glob(depth_glob)):
+            return "typescript"
+
+    return "javascript"
+
+
+def _scan_dominant_language(root: Path, max_depth: int = 2) -> str:
+    """Scan file extensions to find the dominant language.
+
+    Uses gitignore-aware discovery when pathspec is available, falls back
+    to a simple depth-limited walk otherwise.
+    """
+    try:
+        from mcp_server.gitignore import discover_source_files, infer_language_from_files
+        files = discover_source_files(root)
+        lang = infer_language_from_files(files)
+        if lang != "unknown":
+            return lang
+    except Exception:
+        pass
+
+    # Legacy fallback: depth-limited walk
+    from collections import Counter
+
+    counts: Counter[str] = Counter()
+    skip_dirs = {".git", ".codevira", "node_modules", "__pycache__", ".venv",
+                 "venv", ".tox", "dist", "build", "target", ".next", ".nuxt"}
+
+    for path in root.rglob("*"):
+        try:
+            rel = path.relative_to(root)
+        except ValueError:
+            continue
+        if len(rel.parts) > max_depth + 1:
+            continue
+        if any(part in skip_dirs for part in rel.parts):
+            continue
+        if path.is_file() and path.suffix in _EXT_TO_LANG:
+            counts[_EXT_TO_LANG[path.suffix]] += 1
+
+    if counts:
+        return counts.most_common(1)[0][0]
+
+    return "python"  # ultimate fallback
+
+
+
+# Top-level directories that never contain user code
+_SKIP_DIRS: set[str] = {
+    "node_modules", ".git", ".codevira", "__pycache__", ".venv", "venv",
+    "env", ".env", ".tox", "dist", "build", "target", ".next", ".nuxt",
+    ".turbo", ".cache", "coverage", ".nyc_output", "htmlcov", ".pytest_cache",
+    ".mypy_cache", ".ruff_cache", ".eggs", "*.egg-info", "vendor",
+    ".idea", ".vscode", "__snapshots__", ".storybook", "storybook-static",
+    "public", "static", "assets", "migrations", "fixtures",
+}
+
+
+def detect_watched_dirs(root: Path, language: str) -> list[str]:
+    """
+    Detect source directories by scanning the actual project.
+
+    Strategy:
+      1. Use gitignore-aware discovery to find all source files.
+      2. Extract unique top-level directories that contain source files.
+      3. Fall back to convention list if nothing found.
+      4. Ultimate fallback: ["."]
+    """
+    # Try gitignore-aware discovery first
+    try:
+        from mcp_server.gitignore import discover_source_files
+        extensions = set(LANGUAGE_EXTENSIONS.get(language, [".py"]))
+        files = discover_source_files(root)
+        # Filter to language-appropriate files for better dir detection
+        lang_files = [f for f in files if f.suffix.lower() in extensions]
+        if not lang_files:
+            lang_files = files  # fall through to all files if none match
+
+        # Extract unique top-level dirs relative to project root
+        top_dirs: set[str] = set()
+        for f in lang_files:
+            try:
+                rel = f.relative_to(root)
+                if len(rel.parts) > 1:
+                    top_dirs.add(rel.parts[0])
+            except ValueError:
+                pass
+
+        # Filter out noise dirs
+        found = sorted(
+            d for d in top_dirs
+            if not d.startswith(".") and d not in _SKIP_DIRS and not d.endswith("-info")
+        )
+        if found:
+            return found
+    except Exception:
+        pass
+
+    # Legacy fallback: scan top-level dirs manually
+    extensions = set(LANGUAGE_EXTENSIONS.get(language, [".py"]))
+    found_legacy: list[str] = []
+
+    try:
+        for entry in sorted(root.iterdir()):
+            if not entry.is_dir():
+                continue
+            name = entry.name
+            if name.startswith(".") or name in _SKIP_DIRS or name.endswith("-info"):
+                continue
+            if _dir_has_sources(entry, extensions, max_depth=6):
+                found_legacy.append(name)
+    except PermissionError:
+        pass
+
+    if found_legacy:
+        return found_legacy
+
+    # Convention fallback
+    candidates = LANGUAGE_DIRS.get(language, [])
+    convention = [d for d in candidates if (root / d).is_dir()]
+    if convention:
+        return convention
+
+    return ["."]
+
+
+def _dir_has_sources(path: Path, extensions: set[str], max_depth: int) -> bool:
+    """Return True if path contains at least one file with a matching extension."""
+    if max_depth == 0:
+        return False
+    try:
+        for entry in path.iterdir():
+            if entry.is_file() and entry.suffix in extensions:
+                return True
+            if entry.is_dir() and not entry.name.startswith(".") and entry.name not in _SKIP_DIRS:
+                if _dir_has_sources(entry, extensions, max_depth - 1):
+                    return True
+    except PermissionError:
+        pass
+    return False
+
+
+def language_extensions(language: str) -> list[str]:
+    """Get file extensions for a language."""
+    return LANGUAGE_EXTENSIONS.get(language, [".py"])
+
+
+def auto_detect_project(root: Path) -> dict:
+    """
+    Auto-detect everything needed for codevira init — zero prompts.
+
+    Returns:
+        {
+            "name": str,
+            "language": str,
+            "watched_dirs": list[str],
+            "file_extensions": list[str],
+            "collection_name": str,
+        }
+    """
+    root = root.resolve()
+    name = root.name
+    language = detect_language(root)
+    watched_dirs = detect_watched_dirs(root, language)
+    extensions = language_extensions(language)
+    collection_name = name.lower().replace("-", "_").replace(" ", "_").replace(".", "_")
+
+    logger.info("Auto-detected: language=%s, dirs=%s, exts=%s", language, watched_dirs, extensions)
+
+    return {
+        "name": name,
+        "language": language,
+        "watched_dirs": watched_dirs,
+        "file_extensions": extensions,
+        "collection_name": collection_name,
+    }