tzero-mcp 10.7.0 → 10.7.1

package/src/tzero_deps.py

@@ -0,0 +1,287 @@
+# -*- coding: utf-8 -*-
+"""T-Zero dependency bootstrap and environment doctor (standard library only).
+
+* ``ensure_dependencies()`` runs before anything else is imported. If a required package is
+  missing or older than the minimum version, it is installed with pip (quietly, to stderr only,
+  so the MCP stdio protocol on stdout is never disturbed).
+* ``run_doctor()`` powers ``python main.py --doctor``: it checks Python, packages, tkinter, git
+  and the OS keyring and prints an easy-to-read report.
+
+Set ``TZERO_NO_AUTO_INSTALL=1`` to disable automatic installation (the tool then only tells you
+what is missing). Frozen builds (the .exe) never install anything.
+
+Developer: Toprak Ahmet Aydoğmuş (Siber Akademi)
+"""
+
+import importlib
+import importlib.util
+import os
+import re
+import shutil
+import subprocess
+import sys
+from typing import List, NamedTuple, Optional, Tuple
+
+OPT_OUT_ENV = "TZERO_NO_AUTO_INSTALL"
+MIN_PYTHON = (3, 9)
+
+
+class Dependency(NamedTuple):
+    import_name: str   # name used in `import x`
+    dist_name: str     # name on PyPI / importlib.metadata
+    min_version: str   # minimum acceptable version
+    purpose: str
+
+    @property
+    def spec(self) -> str:
+        return f"{self.dist_name}>={self.min_version}"
+
+
+REQUIRED: List[Dependency] = [
+    Dependency("requests", "requests", "2.28.0", "AI provider HTTP calls"),
+    Dependency("keyring", "keyring", "23.13.1", "OS credential storage"),
+    Dependency("darkdetect", "darkdetect", "0.8.0", "OS theme detection"),
+    Dependency("pygments", "pygments", "2.14.0", "syntax highlighting"),
+    Dependency("PIL", "Pillow", "9.0.0", "icon and image generation"),
+]
+MCP_DEPENDENCY = Dependency("mcp", "mcp", "1.0.0", "Model Context Protocol server")
+
+
+def _version_tuple(version: str) -> Tuple[int, ...]:
+    parts: List[int] = []
+    for token in re.split(r"[.\-+]", version):
+        match = re.match(r"\d+", token)
+        if not match:
+            break
+        parts.append(int(match.group()))
+    return tuple(parts)
+
+
+def installed_version(dep: Dependency) -> Optional[str]:
+    """Returns the installed version string, or None when the distribution is unknown."""
+    try:
+        from importlib import metadata
+        return metadata.version(dep.dist_name)
+    except Exception:
+        return None
+
+
+def check_dependency(dep: Dependency) -> Tuple[str, Optional[str]]:
+    """Returns (status, version) where status is 'ok', 'outdated' or 'missing'."""
+    try:
+        found = importlib.util.find_spec(dep.import_name) is not None
+    except (ImportError, ValueError):
+        found = False
+    if not found:
+        return "missing", None
+    version = installed_version(dep)
+    if version and _version_tuple(version) < _version_tuple(dep.min_version):
+        return "outdated", version
+    return "ok", version
+
+
+def _err(message: str) -> None:
+    if sys.stderr is not None and hasattr(sys.stderr, "write"):
+        try:
+            sys.stderr.write(message + "\n")
+            sys.stderr.flush()
+        except Exception:
+            pass
+
+
+def ensure_dependencies(include_mcp: bool = False) -> bool:
+    """Makes sure required packages are present, installing them when allowed.
+
+    Returns True when everything needed is available afterwards.
+    """
+    if sys.version_info < MIN_PYTHON:
+        _err(f"[T-Zero] Python {MIN_PYTHON[0]}.{MIN_PYTHON[1]}+ is required "
+             f"(found {sys.version_info.major}.{sys.version_info.minor}).")
+        return False
+    if getattr(sys, "frozen", False):  # PyInstaller build: dependencies are bundled
+        return True
+
+    ensure_scripts_in_path(quiet=True)
+    deps = list(REQUIRED) + ([MCP_DEPENDENCY] if include_mcp else [])
+    problems = [d for d in deps if check_dependency(d)[0] != "ok"]
+    if not problems:
+        return True
+
+    specs = [d.spec for d in problems]
+    manual = f'"{sys.executable}" -m pip install ' + " ".join(f'"{s}"' for s in specs)
+    if os.environ.get(OPT_OUT_ENV) == "1":
+        _err("[T-Zero] Missing or outdated packages: " + ", ".join(specs))
+        _err(f"[T-Zero] Automatic install is disabled ({OPT_OUT_ENV}=1). Run:\n  {manual}")
+        return False
+
+    _err("[T-Zero] Installing missing or outdated packages: " + ", ".join(specs))
+    try:
+        proc = subprocess.run(
+            [sys.executable, "-m", "pip", "install", "--disable-pip-version-check", "--quiet", *specs],
+            capture_output=True, text=True, timeout=900,
+        )
+    except (OSError, subprocess.SubprocessError) as exc:
+        _err(f"[T-Zero] Could not run pip: {exc}\n  Install manually:\n  {manual}")
+        return False
+
+    importlib.invalidate_caches()
+    if proc.returncode != 0:
+        output = (proc.stderr or proc.stdout or "").strip()
+        _err("[T-Zero] pip failed:\n" + "\n".join(output.splitlines()[-8:]))
+        if "externally-managed-environment" in output:
+            _err("[T-Zero] This Python is managed by your OS. Use a virtual environment:\n"
+                 "  python -m venv .venv && .venv/bin/pip install -r requirements.txt")
+        else:
+            _err(f"  Install manually:\n  {manual}")
+        return False
+
+    ensure_scripts_in_path(quiet=True)
+    still_bad = [d.spec for d in problems if check_dependency(d)[0] != "ok"]
+    if still_bad:
+        _err("[T-Zero] Still unavailable after install: " + ", ".join(still_bad))
+        return False
+    _err("[T-Zero] Dependencies ready.")
+    return True
+
+
+def ensure_scripts_in_path(quiet: bool = True) -> bool:
+    """Ensures Python's Scripts/bin directory is in the user's PATH environment variable.
+    
+    Automatically fixes Windows and Unix PATH when installing via pip so commands
+    like `tzero`, `tzero-gui`, `tzero-mcp`, `tzero-add-mcp` work everywhere immediately.
+    """
+    import site
+    candidates = []
+
+    if os.name == "nt":
+        sys_scripts = os.path.join(sys.prefix, "Scripts")
+        user_scripts = os.path.join(site.USER_BASE, "Scripts")
+    else:
+        sys_scripts = os.path.join(sys.prefix, "bin")
+        user_scripts = os.path.join(site.USER_BASE, "bin")
+
+    for p in [sys_scripts, user_scripts]:
+        if p and os.path.isdir(p) and p not in candidates:
+            candidates.append(p)
+
+    current_path_dirs = [os.path.normcase(os.path.abspath(x)) for x in os.environ.get("PATH", "").split(os.pathsep) if x]
+
+    added_any = False
+    for candidate in candidates:
+        norm_cand = os.path.normcase(os.path.abspath(candidate))
+        if norm_cand not in current_path_dirs:
+            # Update current process
+            os.environ["PATH"] = candidate + os.pathsep + os.environ.get("PATH", "")
+            current_path_dirs.insert(0, norm_cand)
+            added_any = True
+
+            # Permanently update user PATH
+            if os.name == "nt":
+                try:
+                    import winreg
+                    with winreg.OpenKey(winreg.HKEY_CURRENT_USER, r"Environment", 0, winreg.KEY_READ | winreg.KEY_WRITE) as key:
+                        try:
+                            user_path, _ = winreg.QueryValueEx(key, "Path")
+                        except FileNotFoundError:
+                            user_path = ""
+                        parts = [x.strip() for x in user_path.split(";") if x.strip()]
+                        if candidate not in parts:
+                            parts.append(candidate)
+                            new_path = ";".join(parts)
+                            winreg.SetValueEx(key, "Path", 0, winreg.REG_EXPAND_SZ, new_path)
+                            if not quiet:
+                                sys.stderr.write(f"[T-Zero] Added {candidate} to User PATH in Windows Registry.\n")
+                except Exception:
+                    pass
+            else:
+                try:
+                    home = os.path.expanduser("~")
+                    for rc_name in [".bashrc", ".zshrc"]:
+                        rc_path = os.path.join(home, rc_name)
+                        if os.path.exists(rc_path):
+                            with open(rc_path, "r", encoding="utf-8", errors="ignore") as f:
+                                rc_content = f.read()
+                            export_line = f'export PATH="{candidate}:$PATH"'
+                            if candidate not in rc_content:
+                                with open(rc_path, "a", encoding="utf-8") as f:
+                                    f.write(f"\n# Added by T-Zero Context Architect\n{export_line}\n")
+                                if not quiet:
+                                    sys.stderr.write(f"[T-Zero] Added {candidate} to {rc_name}\n")
+                except Exception:
+                    pass
+
+    return added_any
+
+
+def _line(level: str, text: str) -> str:
+    return f"  [{level:^4}] {text}"
+
+
+def run_doctor() -> int:
+    """Checks the environment, fixing missing packages when allowed. Returns a process exit code."""
+    print("T-Zero Doctor: environment check\n")
+    failures = 0
+
+    py = f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}"
+    if sys.version_info >= MIN_PYTHON:
+        print(_line("OK", f"Python {py}"))
+    else:
+        failures += 1
+        print(_line("FAIL", f"Python {py}: version {MIN_PYTHON[0]}.{MIN_PYTHON[1]}+ is required"))
+
+    ensure_dependencies(include_mcp=True)
+    for dep in REQUIRED + [MCP_DEPENDENCY]:
+        status, version = check_dependency(dep)
+        label = f"{dep.dist_name} {version or ''}".strip()
+        if status == "ok":
+            print(_line("OK", f"{label} ({dep.purpose})"))
+        else:
+            failures += 1
+            print(_line("FAIL", f"{dep.dist_name}>={dep.min_version} is {status} ({dep.purpose})"))
+
+    if importlib.util.find_spec("mcp") is not None:
+        try:
+            if importlib.util.find_spec("mcp.server.mcpserver") is not None:
+                print(_line("OK", "MCP SDK flavor: MCPServer (mcp 2.x)"))
+            else:
+                print(_line("OK", "MCP SDK flavor: FastMCP (mcp 1.x)"))
+        except (ImportError, ValueError):
+            print(_line("OK", "MCP SDK flavor: FastMCP (mcp 1.x)"))
+
+    if importlib.util.find_spec("tkinter") is not None:
+        print(_line("OK", "tkinter (desktop GUI available)"))
+    else:
+        print(_line("WARN", "tkinter missing: the GUI is unavailable, the CLI and MCP server still work "
+                            "(Debian/Ubuntu: sudo apt install python3-tk)"))
+
+    if shutil.which("git"):
+        print(_line("OK", "git found (commit history and diff features)"))
+    else:
+        print(_line("WARN", "git not found: git features are disabled"))
+
+    try:
+        import keyring
+        backend = keyring.get_keyring()
+        name = f"{type(backend).__module__}.{type(backend).__name__}"
+        if "fail" in name.lower() or "null" in name.lower():
+            print(_line("WARN", "no usable OS keyring backend: saving API keys in the app will not work; "
+                                "set NVIDIA_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY / OPENROUTER_API_KEY / "
+                                "ANTHROPIC_API_KEY instead"))
+        else:
+            print(_line("OK", f"keyring backend: {name}"))
+    except Exception as exc:
+        print(_line("WARN", f"keyring could not be checked: {exc}"))
+
+    ensure_scripts_in_path(quiet=True)
+    print(_line("OK", "Python Scripts PATH verified (tzero, tzero-gui, tzero-mcp accessible)"))
+
+    print()
+    if failures:
+        print(f"{failures} problem(s) found. See the FAIL lines above.")
+        return 1
+    print("All required checks passed.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(run_doctor())

package/src/tzero_drift.py

@@ -0,0 +1,208 @@
+# -*- coding: utf-8 -*-
+"""
+Siber Akademi — T-Zero Instruction & Architecture Drift Scorer.
+Developer: Toprak Ahmet Aydoğmuş (Siber Akademi)
+License: MIT
+
+Quantifies how closely LLM code generations and workspace modifications adhere
+to initial system prompt rules, negative constraints, and architectural boundaries.
+Directly measures the "Lost in the Middle" attention degradation phenomenon:
+proves high SNR via AST pruning prevents instruction decay over long sessions.
+"""
+
+import os
+import sys
+import ast
+import json
+from dataclasses import dataclass, field
+from typing import Dict, List, Any, Optional
+
+from tzero_security import ZeroLeakEngine
+
+
+@dataclass
+class DriftFinding:
+    category: str
+    severity: str
+    file_path: str
+    line_no: int
+    message: str
+    penalty_points: float
+
+
+@dataclass
+class DriftReport:
+    workspace_dir: str
+    drift_score: float         # 0.0 = Perfect zero drift, 100.0 = Severe drift
+    adherence_pct: float       # 100.0% = Flawless instruction following
+    snr_rating: str            # "EXCELLENT (HIGH SNR)", "DEGRADED", "CRITICAL"
+    findings: List[DriftFinding] = field(default_factory=list)
+    files_audited: int = 0
+
+
+class DriftAnalyzer:
+    """Measures instruction drift and architectural rule decay across the codebase."""
+
+    SKIP_DIRS = {
+        ".git", "__pycache__", ".pytest_cache", "target", "dist",
+        "build", ".venv", "venv", "node_modules", ".superpowers", "bin"
+    }
+
+    @classmethod
+    def analyze_workspace(cls, workspace_dir: str = ".") -> DriftReport:
+        """Analyzes active workspace files for rule drift, security drift, and complexity."""
+        abs_root = os.path.abspath(workspace_dir)
+        findings: List[DriftFinding] = []
+        files_count = 0
+
+        total_penalty = 0.0
+
+        for root, dirs, files in os.walk(abs_root):
+            dirs[:] = [d for d in dirs if d not in cls.SKIP_DIRS and not d.startswith(".")]
+            for fname in files:
+                if fname.endswith(".py"):
+                    fpath = os.path.join(root, fname)
+                    rel = os.path.relpath(fpath, abs_root).replace("\\", "/")
+                    if "test" in rel.lower():
+                        continue
+                    files_count += 1
+                    try:
+                        with open(fpath, "r", encoding="utf-8", errors="replace") as f:
+                            content = f.read()
+
+                        # 1. Zero-Leak Security Drift
+                        sec_hits = ZeroLeakEngine.scan_text(content, check_entropy=True)
+                        for hit in sec_hits:
+                            penalty = 15.0
+                            total_penalty += penalty
+                            findings.append(DriftFinding(
+                                category="Zero-Leak Security",
+                                severity="CRITICAL",
+                                file_path=rel,
+                                line_no=hit.line_no,
+                                message=f"Secret leak introduced: {hit.description}",
+                                penalty_points=penalty
+                            ))
+
+                        # 2. AST Code Smell & Instruction Drift
+                        tree = ast.parse(content, filename=rel)
+                        for node in ast.walk(tree):
+                            # Bare exceptions swallow interrupts and drift from error guidelines
+                            if isinstance(node, ast.ExceptHandler) and node.type is None:
+                                penalty = 5.0
+                                total_penalty += penalty
+                                findings.append(DriftFinding(
+                                category="Error Handling",
+                                severity="HIGH",
+                                file_path=rel,
+                                line_no=node.lineno,
+                                message="Bare `except:` clause used instead of typed exception",
+                                penalty_points=penalty
+                            ))
+
+                            # Large un-decomposed functions (>60 lines) violate clean architecture
+                            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                                length = getattr(node, "end_lineno", node.lineno) - node.lineno
+                                if length > 60:
+                                    penalty = 3.0
+                                    total_penalty += penalty
+                                    findings.append(DriftFinding(
+                                        category="Architectural Modularity",
+                                        severity="MEDIUM",
+                                        file_path=rel,
+                                        line_no=node.lineno,
+                                        message=f"Function `{node.name}` ({length} lines) exceeds clean modularity limit (60 max)",
+                                        penalty_points=penalty
+                                    ))
+
+                    except Exception:
+                        pass
+
+        # Normalize drift score between 0.0 and 100.0
+        normalized_drift = min(100.0, round(total_penalty, 1))
+        adherence_pct = max(0.0, round(100.0 - normalized_drift, 1))
+
+        if adherence_pct >= 90.0:
+            snr = "EXCELLENT (HIGH SNR / ZERO DECAY)"
+        elif adherence_pct >= 75.0:
+            snr = "MODERATE (MINOR ATTENTION DEGRADATION)"
+        else:
+            snr = "POOR (ATTENTION DILUTION / HIGH DRIFT)"
+
+        return DriftReport(
+            workspace_dir=abs_root,
+            drift_score=normalized_drift,
+            adherence_pct=adherence_pct,
+            snr_rating=snr,
+            findings=findings,
+            files_audited=files_count
+        )
+
+    @classmethod
+    def render_cli(cls, report: DriftReport) -> None:
+        """Renders rich ANSI terminal drift score report."""
+        print("\n" + "=" * 80)
+        print("🎯 \033[36mT-ZERO INSTRUCTION & ARCHITECTURAL DRIFT ANALYZER\033[0m")
+        print("=" * 80)
+        print(f"📁 Workspace: \033[33m{report.workspace_dir}\033[0m ({report.files_audited} modules audited)")
+        
+        # Color badge for adherence
+        if report.adherence_pct >= 90.0:
+            badge = f"\033[32m{report.adherence_pct}% (EXCELLENT)\033[0m"
+        elif report.adherence_pct >= 75.0:
+            badge = f"\033[33m{report.adherence_pct}% (ACCEPTABLE)\033[0m"
+        else:
+            badge = f"\033[31m{report.adherence_pct}% (CRITICAL DRIFT)\033[0m"
+
+        print(f"📈 Prompt Instruction Adherence: {badge}")
+        print(f"📉 Cumulative Drift Score: \033[33m{report.drift_score} / 100\033[0m")
+        print(f"⚡ Context Attention SNR: \033[32m{report.snr_rating}\033[0m")
+        print("-" * 80)
+
+        if not report.findings:
+            print("🌟 \033[32mFlawless Adherence! Zero rule drift, zero secret leaks, zero boundary violations.\033[0m")
+        else:
+            print(f"Identified {len(report.findings)} rule drift / violation points:")
+            for f in report.findings[:15]:
+                print(f"  • \033[33m{f.file_path}:{f.line_no}\033[0m [{f.category}]: {f.message}")
+            if len(report.findings) > 15:
+                print(f"  ... and {len(report.findings) - 15} more findings.")
+
+        print("=" * 80)
+        print("💡 \033[32mAST pruning preserves high Signal-to-Noise Ratio (SNR), preventing model forgetting over 50+ turns.\033[0m\n")
+
+    @classmethod
+    def to_json(cls, report: DriftReport) -> str:
+        """Serializes drift report into JSON."""
+        return json.dumps({
+            "workspace_dir": report.workspace_dir,
+            "drift_score": report.drift_score,
+            "adherence_pct": report.adherence_pct,
+            "snr_rating": report.snr_rating,
+            "files_audited": report.files_audited,
+            "findings_count": len(report.findings),
+            "findings": [
+                {
+                    "category": f.category,
+                    "severity": f.severity,
+                    "file_path": f.file_path,
+                    "line_no": f.line_no,
+                    "message": f.message,
+                    "penalty_points": f.penalty_points
+                }
+                for f in report.findings
+            ]
+        }, indent=2)
+
+
+def main():
+    target = sys.argv[1] if len(sys.argv) > 1 and not sys.argv[1].startswith("-") else "."
+    rep = DriftAnalyzer.analyze_workspace(target)
+    if "--json" in sys.argv:
+        print(DriftAnalyzer.to_json(rep))
+    else:
+        DriftAnalyzer.render_cli(rep)
+
+
+if __name__ == "__main__":
+    main()