codevira 1.6.0__py3-none-any.whl

mcp_server/crash_logger.py

@@ -0,0 +1,236 @@
+"""
+crash_logger.py — Crash-only logging with automatic secret sanitization.
+
+Captures unhandled exceptions and tool-level errors to a rotating log file.
+All log entries are sanitized to strip personal information, secrets, and
+credentials before writing to disk.
+
+Log location: ~/.codevira/logs/crashes.log
+Max size: 5 MB, rotated with 3 backups (20 MB total)
+"""
+from __future__ import annotations
+
+import logging
+import re
+import sys
+import threading
+import traceback
+from datetime import datetime, timezone
+from logging.handlers import RotatingFileHandler
+from pathlib import Path
+
+# ---------------------------------------------------------------------------
+# Secret patterns — matched and replaced BEFORE writing to disk.
+#
+# CodeVira is a code-indexing/memory tool. Crash tracebacks may contain
+# file paths, config values, or connection strings from the user's project.
+# We sanitize structural patterns (connection strings, key=value, PEM blocks)
+# rather than vendor-specific token formats — CodeVira never handles those.
+# ---------------------------------------------------------------------------
+_SECRET_PATTERNS: list[tuple[re.Pattern, str]] = [
+    # Private key PEM blocks
+    (re.compile(r'-----BEGIN\s+\w+\s+PRIVATE\s+KEY-----[\s\S]*?-----END\s+\w+\s+PRIVATE\s+KEY-----'), '***PRIVATE_KEY***'),
+    # Connection strings with embedded passwords (postgres://, mongodb://, redis://, amqp://, etc.)
+    (re.compile(r'(?i)(://[^:]*:)[^@]+(@)'), r'\1***@'),
+    # Private/internal IP addresses (RFC 1918)
+    (re.compile(r'\b(?:10\.\d{1,3}\.\d{1,3}\.\d{1,3}|172\.(?:1[6-9]|2\d|3[01])\.\d{1,3}\.\d{1,3}|192\.168\.\d{1,3}\.\d{1,3})\b'), '***INTERNAL_IP***'),
+
+    # ---- Generic keyword-value patterns (catch-all) ----
+
+    # key=value / key: value / key = value (in text and logs)
+    (re.compile(r'(?i)(api[_-]?key|token|secret|password|authorization|bearer|credential)\s*[:=]\s*\S+'), r'\1=***REDACTED***'),
+    # JSON-style: "password": "value" or 'password': 'value'
+    (re.compile(r"""(?i)(["'](?:password|secret|token|api_key|api-key|auth|credential)["'])\s*:\s*["'][^"']+["']"""), r'\1: "***REDACTED***"'),
+    # .env file values for known secret variable names
+    (re.compile(r'(?i)((?:DATABASE_URL|REDIS_URL|MONGO_URL|SECRET_KEY|PRIVATE_KEY|ACCESS_TOKEN|REFRESH_TOKEN|API_KEY|AUTH_TOKEN|ENCRYPTION_KEY)\s*=\s*)\S+'), r'\1***REDACTED***'),
+]
+
+# Home directory — replaced with ~ in all paths
+_HOME = str(Path.home())
+
+
+def _sanitize(text: str) -> str:
+    """Remove secrets, PII, and sensitive data from log text."""
+    # Replace home directory with ~ (hides username from paths)
+    text = text.replace(_HOME, "~")
+    # Apply all secret patterns
+    for pattern, replacement in _SECRET_PATTERNS:
+        text = pattern.sub(replacement, text)
+    # Strip environment variable dumps that might contain secrets
+    text = re.sub(
+        r'(?i)environ\s*\{[^}]{200,}\}',
+        'environ{***REDACTED_ENV***}',
+        text,
+    )
+    return text
+
+
+def _get_log_dir() -> Path:
+    """Return ~/.codevira/logs/, creating it if needed."""
+    log_dir = Path.home() / ".codevira" / "logs"
+    log_dir.mkdir(parents=True, exist_ok=True)
+    return log_dir
+
+
+# ---------------------------------------------------------------------------
+# Module-level logger — initialized once, thread-safe via lock.
+# ---------------------------------------------------------------------------
+_logger: logging.Logger | None = None
+_logger_lock = threading.Lock()
+
+
+def _get_logger() -> logging.Logger:
+    global _logger
+    if _logger is not None:
+        return _logger
+
+    with _logger_lock:
+        # Double-check after acquiring lock (another thread may have initialized)
+        if _logger is not None:
+            return _logger
+
+        logger = logging.getLogger("codevira.crash")
+        logger.setLevel(logging.ERROR)
+        logger.propagate = False  # Don't pollute stdout/stderr (MCP protocol)
+
+        log_path = _get_log_dir() / "crashes.log"
+        handler = RotatingFileHandler(
+            log_path,
+            maxBytes=5 * 1024 * 1024,  # 5 MB
+            backupCount=3,             # 20 MB total history
+            encoding="utf-8",
+        )
+        handler.setLevel(logging.ERROR)
+        handler.setFormatter(logging.Formatter("%(message)s"))
+        logger.addHandler(handler)
+
+        _logger = logger
+        return _logger
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def log_crash(
+    error: BaseException,
+    *,
+    context: str = "",
+    tool_name: str = "",
+    project_path: str = "",
+) -> None:
+    """
+    Log a crash to ~/.codevira/logs/crashes.log.
+
+    Only writes ERROR-level entries. All content is sanitized before writing.
+
+    Args:
+        error: The exception that was raised.
+        context: What was happening when the crash occurred (e.g. "server startup").
+        tool_name: MCP tool name if the crash happened during a tool call.
+        project_path: Project directory, if known.
+    """
+    try:
+        logger = _get_logger()
+        tb = traceback.format_exception(type(error), error, error.__traceback__)
+        tb_text = "".join(tb)
+
+        # Build structured log entry
+        lines = [
+            f"{'=' * 72}",
+            f"CRASH: {type(error).__name__}: {error}",
+            f"TIME:  {datetime.now(timezone.utc).isoformat()}",
+        ]
+        if context:
+            lines.append(f"WHERE: {context}")
+        if tool_name:
+            lines.append(f"TOOL:  {tool_name}")
+        if project_path:
+            lines.append(f"PROJECT: {project_path}")
+
+        # System info (non-sensitive)
+        lines.append(f"PYTHON: {sys.version.split()[0]}")
+        try:
+            from importlib.metadata import version as pkg_version
+            lines.append(f"CODEVIRA: {pkg_version('codevira')}")
+        except Exception:
+            pass
+
+        lines.append(f"TRACEBACK:\n{tb_text}")
+        lines.append("")  # blank line separator
+
+        entry = "\n".join(lines)
+        entry = _sanitize(entry)
+
+        logger.error(entry)
+    except Exception:
+        # Crash logger must never itself crash the server.
+        # Last resort: try stderr (won't break MCP protocol since
+        # MCP uses stdout only; stderr is for diagnostics).
+        try:
+            print(f"[codevira] crash logger failed: {error}", file=sys.stderr)
+        except Exception:
+            pass
+
+
+def get_crash_log_path() -> Path:
+    """Return the path to the crash log file."""
+    return _get_log_dir() / "crashes.log"
+
+
+def read_recent_crashes(limit: int = 20) -> str:
+    """
+    Read the most recent crash entries from the log file.
+
+    Returns a formatted string with up to `limit` most recent crashes.
+    Content is already sanitized (written sanitized to disk).
+    """
+    if limit < 1:
+        limit = 1
+
+    log_path = get_crash_log_path()
+    if not log_path.exists():
+        return "No crash log found. No crashes have been recorded."
+
+    text = log_path.read_text(encoding="utf-8", errors="replace")
+    if not text.strip():
+        return "Crash log is empty. No crashes have been recorded."
+
+    # Split on separator line and take the most recent entries
+    entries = text.split("=" * 72)
+    entries = [e.strip() for e in entries if e.strip()]
+
+    if not entries:
+        return "No crash entries found."
+
+    recent = entries[-limit:]
+    count_total = len(entries)
+
+    # Sanitize the header too (log_path contains home dir)
+    safe_path = str(log_path).replace(_HOME, "~")
+    header = f"Showing {len(recent)} of {count_total} total crashes"
+    header += f"\nLog file: {safe_path}\n"
+    header += f"Log size: {log_path.stat().st_size / 1024:.1f} KB\n"
+
+    body = ("\n" + "=" * 72 + "\n").join(recent)
+    return f"{header}\n{'=' * 72}\n{body}"
+
+
+def install_global_handler() -> None:
+    """
+    Install a global exception handler that logs unhandled exceptions.
+
+    Call this once at MCP server startup. The original excepthook is
+    preserved — this only adds logging, it doesn't suppress errors.
+    """
+    original_hook = sys.excepthook
+
+    def _crash_hook(exc_type, exc_value, exc_tb):
+        if exc_type is not KeyboardInterrupt:
+            log_crash(
+                exc_value,
+                context="unhandled exception (global handler)",
+            )
+        original_hook(exc_type, exc_value, exc_tb)
+
+    sys.excepthook = _crash_hook

mcp_server/data/__init__.py

@@ -0,0 +1 @@
+# This file makes mcp_server/data a Python package so setuptools includes it.

mcp_server/data/agents/builder.md

@@ -0,0 +1,84 @@
+# Builder Agent
+
+## Role
+Run static analysis and architecture verification. Zero AI tokens for the checks themselves.
+AI tokens used only if violations are found and need explaining.
+
+---
+
+## When You Are Invoked
+
+After Tester passes (or in parallel with Tester for medium/large changes).
+
+---
+
+## Command Sequence
+
+```bash
+# 1. Lint — fast, always run
+ruff check src/   # or: eslint src/, go vet ./..., cargo clippy
+
+# 2. Type check — run on changed files/modules
+mypy src/services/ src/schemas/   # or: tsc --noEmit, go build ./...
+
+# 3. Architecture verification — if your project has an architecture checker
+python scripts/verify_architecture.py  # optional: only if this script exists
+
+# 4. Syntax check for any new files
+python -m py_compile <new_file.py>   # or equivalent for your language
+```
+
+Adapt the above commands to your project's toolchain.
+
+---
+
+## Failure Handling
+
+### Lint violations
+- Auto-fixable: note them, suggest `ruff check --fix` (or equivalent)
+- Non-auto-fixable: report with line number and rule ID
+
+### Type errors
+- Type mismatch — check if a field needs `Optional` or a union type
+- Missing stub — acceptable if third-party, just note it
+- Cannot find module — check import path
+
+### Architecture violations (if checker exists)
+- **Always block on these** — import violations are CI failures
+- Report the exact import, the rule it violates, and the correct pattern
+
+---
+
+## New Files
+
+When a new file was created in this session, check if it was registered in the graph:
+```
+get_node(new_file_path)
+```
+If not found → remind the Developer agent to call `add_node()` before closing the changeset.
+
+---
+
+## Output Format
+
+```
+BUILD: <files checked>
+STATUS: CLEAN | WARNINGS | VIOLATIONS
+
+Violations (if any):
+- LINT: <file>:<line> <rule_id> — <message>
+- TYPE: <file>:<line> — <message>
+- ARCH: <file> imports <other_file> — violates <rule>
+
+Auto-fixable: <yes/no>
+Block merge: <yes if ARCH violations or type errors; no for lint warnings>
+New files registered in graph: <yes/no — remind developer if no>
+```
+
+---
+
+## What You Do NOT Do
+
+- Do NOT refactor code to fix style issues (that's over-engineering)
+- Do NOT add type annotations to code you didn't change
+- Do NOT run the full type check on the entire codebase — only changed modules

mcp_server/data/agents/developer.md

@@ -0,0 +1,111 @@
+# Developer Agent
+
+## Role
+Write code changes. You are the execution engine.
+You receive a task, orient via MCP tools, then write precise targeted changes.
+
+---
+
+## Session Start Protocol (MANDATORY — do not skip)
+
+```
+1. list_open_changesets()
+   → If any open: review them first. Pick up unfinished work before starting new.
+
+2. get_roadmap()
+   → Confirm current phase and next_action align with the task.
+
+3. search_decisions(task_keywords)
+   → Check if this has been decided before. E.g. search_decisions("threshold") before
+     changing any threshold values.
+
+4. For EACH file mentioned in the task:
+   get_node(file_path)
+   → Read: role, rules, do_not_revert, stability, index_status
+   → If index_status.stale: refresh_index([file_path])
+
+5. For EACH file you will MODIFY:
+   get_impact(file_path)
+   → Read: blast_radius, affected_files, high_risk_files, tests_to_run
+
+6. search_codebase(task_description)
+   → Find existing patterns. NEVER rewrite what already exists.
+
+7. IF modifying 2+ files:
+   start_changeset(id, description, files)
+```
+
+---
+
+## Coding Rules
+
+- Follow `rules/` standards — especially `coding-standards.md`
+- **Never** modify files with `do_not_revert: true` without explicit permission
+- If a file has `rules` in its graph node — read them before writing a single line
+
+---
+
+## Efficiency Rules
+
+- Read only the files you NEED, not everything you CAN
+- `get_node()` replaces reading the file for orientation
+- `search_codebase()` replaces grepping for patterns
+- `get_impact()` replaces manual import tracing
+- `search_decisions()` replaces re-reading past sessions to recall a decision
+- If you catch yourself reading a file just to understand it — use MCP first
+
+---
+
+## Adding New Files
+
+When creating a new file, register it in the graph immediately:
+```
+add_node(
+  file_path="src/services/new_service.py",
+  role="Service that handles X",
+  layer="services",
+  node_type="file",
+  stability="low",
+  key_functions=["process", "validate"],
+  connects_to=[{"target": "src/core/event_bus.py", "edge": "depends_on"}]
+)
+```
+This ensures future agents can find it via `get_node()` and `get_impact()`.
+
+---
+
+## Session End Protocol (MANDATORY)
+
+```
+1. IF changeset active:
+   - For each file completed: update_changeset_progress(id, file)
+   - If all files done: complete_changeset(id, decisions=[...])
+   - If session ending early: update_changeset_progress(id, last_file, blocker="reason")
+
+2. For each file modified:
+   update_node(file_path, {
+     "last_changed_by": "Phase N — brief description of what changed",
+     "new_rules": ["any new invariants discovered"],
+     "new_connections": [{"target": "other/file.py", "edge": "depends_on"}],
+     "key_functions": ["new_public_fn"],
+     "stability": "high",
+     "new_tests": ["tests/unit/test_new.py"],
+   })
+
+3. update_next_action("exact description of what needs to happen next")
+
+4. If new work was discovered:
+   add_phase(phase=N, name="...", description="...", priority="medium")
+```
+
+---
+
+## Playbook References
+
+| Task type | Read this rule file |
+|---|---|
+| Adding an MCP tool | `rules/coding-standards.md` + `rules/testing-standards.md` |
+| Adding a service | `rules/resilience-observability.md` |
+| Modifying imports | Review your project's layer/import rules |
+| Writing tests | `rules/testing-standards.md` |
+| Committing | `rules/git_commits.md` |

mcp_server/data/agents/documenter.md

@@ -0,0 +1,138 @@
+# Documenter Agent
+
+## Role
+Write session state back to the project memory. Runs at the END of every session.
+Minimal AI tokens — mostly structured YAML writes via MCP tools.
+
+---
+
+## When You Are Invoked
+
+Always. Last agent in every pipeline, regardless of task type.
+
+---
+
+## MCP Tools Used
+
+```
+complete_changeset(id, decisions)       → if a changeset was active
+update_node(file_path, changes)         → for each file modified
+update_next_action(next_action)         → always
+update_phase_status(status)             → if phase status changed
+add_phase(phase, name, description)     → if new follow-up work was discovered
+complete_phase(phase_number, decisions) → if the current phase is fully done
+write_session_log(...)                  → always, at the very end
+```
+
+---
+
+## Session End Protocol
+
+### 1. Complete Active Changeset (if any)
+```
+complete_changeset(
+  changeset_id="<id>",
+  decisions=[
+    "brief statement of each key decision made",
+    "e.g. 'threshold set to 0.85 based on empirical testing'"
+  ]
+)
+```
+Only call if ALL files in the changeset are done.
+If session ending early with unfinished files:
+```
+update_changeset_progress(id, last_file_done, blocker="reason session ended")
+```
+
+### 2. Update Each Modified Graph Node
+```
+update_node(
+  file_path="<relative path>",
+  changes={
+    "last_changed_by": "Phase N — brief description",
+    "new_rules": ["any NEW invariant discovered during this session"],
+    "new_connections": [{"target": "other/file.py", "edge": "depends_on"}],
+    "key_functions": ["new_function_added"],
+    "stability": "high",      # only if stability changed
+    "new_tests": ["tests/unit/test_new.py"],
+    "do_not_revert": True     # only if a critical decision was made
+  }
+)
+```
+
+### 3. Update Roadmap
+
+Always update next action:
+```
+update_next_action(
+  "Exact description of what needs to happen next — specific enough for a fresh agent"
+)
+```
+
+If this session unblocked or started the current phase:
+```
+update_phase_status(status="in_progress")
+```
+
+If new work was discovered during this session:
+```
+add_phase(
+  phase=N,
+  name="Discovered work item",
+  description="Why this is needed and what it involves",
+  priority="medium"
+)
+```
+
+If the current phase is fully complete:
+```
+complete_phase(
+  phase_number=N,
+  key_decisions=["decision 1", "decision 2"]
+)
+```
+
+### 4. Write Session Log via MCP
+```
+write_session_log(
+  session_id="<first 8 chars of a UUID>",
+  task="<developer's original prompt>",
+  phase="<current phase number>",
+  files_changed=["src/services/generator.py"],
+  decisions=[
+    {
+      "file_path": "src/services/generator.py",
+      "decision": "key decision 1",
+      "context": "Why we made this decision"
+    }
+  ],
+  next_steps=["<what the next agent should do>"]
+)
+```
+
+This writes to SQLite Memory and feeds `search_decisions()`.
+
+---
+
+## Log Directory Convention
+
+```
+.codevira/logs/
+  2025-01-15/
+    session-a1b2c3d4.yaml
+    session-e5f6g7h8.yaml
+  2025-01-16/
+    session-...yaml
+```
+
+One directory per day, one file per session.
+
+---
+
+## What You Do NOT Do
+
+- Do NOT rewrite or summarize code
+- Do NOT add comments or docstrings
+- Do NOT update files not in the changeset
+- Do NOT write verbose prose — keep decisions concise (1 sentence each)
+- Do NOT write the session log manually — always use `write_session_log()` MCP tool

mcp_server/data/agents/orchestrator.md

@@ -0,0 +1,96 @@
+# Orchestrator — Agent Routing Logic
+
+## Purpose
+Determine which agents to invoke based on the nature of the developer's prompt.
+This is not a separate process — it is the decision logic that any agent (Claude Code, Cursor, Windsurf)
+should follow at the start of a session before doing any work.
+
+---
+
+## Step 1: Classify the Task
+
+Read the developer prompt and classify it:
+
+| Signal | Task Type |
+|---|---|
+| "fix", "bug", "broken", "error" | `small_fix` or `medium_change` |
+| "add", "implement", "new feature" | `medium_change` or `large_change` |
+| "refactor", "restructure", "redesign" | `large_change` |
+| "review", "audit", "check" | `parallel_review` |
+| "explain", "what does", "how does" | `research` (no code changes) |
+| Affects 1 file, stability=high | `small_fix` |
+| Affects 2–4 files | `medium_change` |
+| Affects 5+ files or crosses service boundaries | `large_change` |
+
+---
+
+## Step 2: Select Agent Pipeline
+
+### `small_fix` (1 file, low blast radius)
+```
+Developer → Tester → Documenter
+```
+Token budget: ~900 overhead
+
+### `medium_change` (2–4 files, known blast radius)
+```
+Developer → Reviewer → Tester → Builder → Documenter
+```
+Token budget: ~1,400 overhead
+
+### `large_change` (phase-level, cross-service, or uncertain scope)
+```
+Planner → Developer → Reviewer → Tester → Builder → Documenter
+```
+Token budget: ~2,000 overhead
+
+### `parallel_review` (audit a module or multiple files)
+```
+[Agent A: file group 1] + [Agent B: file group 2]  ← parallel
+→ Documenter
+```
+Token budget: ~800 per parallel agent
+
+### `research` (no code changes)
+```
+No agents — just MCP tool calls:
+  get_node() + get_impact() + search_codebase() + search_decisions()
+```
+Token budget: ~400
+
+---
+
+## Step 3: MCP Tools Per Stage
+
+Every agent in the pipeline calls only the MCP tools it needs:
+
+| Agent | MCP Tools | Shell Commands |
+|---|---|---|
+| Planner | get_full_roadmap, get_impact, list_nodes, search_codebase, search_decisions, add_phase | — |
+| Developer | list_open_changesets, get_roadmap, get_node, get_impact, search_codebase, search_decisions, start_changeset, refresh_index, add_node | — |
+| Reviewer | get_node, get_playbook | — |
+| Tester | get_node (for tests field), list_nodes | project test command |
+| Builder | — | linter, type checker, optional architecture verifier |
+| Documenter | complete_changeset, update_node, update_next_action, update_phase_status, add_phase, write_session_log | — |
+
+---
+
+## Step 4: Reviewer Trigger Conditions
+
+Reviewer is NOT always needed. Trigger it when ANY of:
+- The file's graph node has `stability: high`
+- The file's graph node has `do_not_revert: true`
+- The file's graph node has non-empty `rules`
+- The change affects a schema or event payload
+- The change touches `.codevira/graph/` or `.codevira/roadmap.yaml`
+
+Skip reviewer for: scaffolding, new test files, config-only changes, docs.
+
+---
+
+## Escalation Rule
+
+If at any point the blast radius (`get_impact` result) returns more files than expected for the task type, escalate:
+- `small_fix` → blast_radius > 3 → escalate to `medium_change`
+- `medium_change` → blast_radius > 7 → escalate to `large_change`
+- `large_change` → blast_radius > 15 → stop, call `get_roadmap` and document the scope before proceeding