raise-cli 2.2.1__py3-none-any.whl

raise_cli/doctor/__init__.py

@@ -0,0 +1,4 @@
+"""rai doctor — self-diagnostic, coherence audit, and bug reporting.
+
+Architecture: ADR-045 (DoctorCheck protocol, separate from WorkflowGates).
+"""

raise_cli/doctor/checks/__init__.py

@@ -0,0 +1 @@
+"""Built-in doctor checks, registered via rai.doctor.checks entry points."""

raise_cli/doctor/checks/environment.py

@@ -0,0 +1,110 @@
+"""Environment diagnostic check — Python, raise-cli, OS, optional extras.
+
+Reports Python version, raise-cli version, OS platform, and whether optional
+extras (mcp, api) are installed.
+
+Architecture: ADR-045.
+"""
+
+from __future__ import annotations
+
+import importlib
+import platform
+import sys
+from typing import ClassVar
+
+from raise_cli.doctor.models import CheckResult, CheckStatus, DoctorContext
+
+_MIN_PYTHON: tuple[int, int] = (3, 11)
+
+_OPTIONAL_EXTRAS: tuple[tuple[str, str, str], ...] = (
+    ("mcp", "mcp", "pip install raise-cli[mcp]"),
+    ("httpx", "httpx", "pip install raise-cli[api]"),
+)
+
+
+class EnvironmentCheck:
+    """Validates Python version, raise-cli version, OS, and installed extras."""
+
+    check_id: ClassVar[str] = "environment"
+    category: ClassVar[str] = "environment"
+    description: ClassVar[str] = "Python version, raise-cli version, OS, installed extras"
+    requires_online: ClassVar[bool] = False
+
+    def evaluate(self, context: DoctorContext) -> list[CheckResult]:
+        results: list[CheckResult] = []
+        results.append(self._check_python_version())
+        results.append(self._check_rai_version())
+        results.append(self._check_os_info())
+        results.extend(self._check_optional_extras())
+        return results
+
+    # ------------------------------------------------------------------
+    # Individual checks
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _check_python_version() -> CheckResult:
+        current = sys.version_info[:2]
+        version_str = f"{current[0]}.{current[1]}"
+        if current >= _MIN_PYTHON:
+            return CheckResult(
+                check_id="env-python-version",
+                category="environment",
+                status=CheckStatus.PASS,
+                message=f"Python {version_str}",
+            )
+        return CheckResult(
+            check_id="env-python-version",
+            category="environment",
+            status=CheckStatus.ERROR,
+            message=f"Python {version_str} (>= {_MIN_PYTHON[0]}.{_MIN_PYTHON[1]} required)",
+            fix_hint=f"Install Python >= {_MIN_PYTHON[0]}.{_MIN_PYTHON[1]}",
+        )
+
+    @staticmethod
+    def _check_rai_version() -> CheckResult:
+        from raise_cli import __version__
+
+        return CheckResult(
+            check_id="env-rai-version",
+            category="environment",
+            status=CheckStatus.PASS,
+            message=f"raise-cli {__version__}",
+        )
+
+    @staticmethod
+    def _check_os_info() -> CheckResult:
+        os_info = f"{platform.system()} {platform.release()} ({platform.machine()})"
+        return CheckResult(
+            check_id="env-os-info",
+            category="environment",
+            status=CheckStatus.PASS,
+            message=os_info,
+        )
+
+    @staticmethod
+    def _check_optional_extras() -> list[CheckResult]:
+        results: list[CheckResult] = []
+        for extra_name, module_name, fix_hint in _OPTIONAL_EXTRAS:
+            try:
+                importlib.import_module(module_name)
+                results.append(
+                    CheckResult(
+                        check_id=f"env-extra-{extra_name}",
+                        category="environment",
+                        status=CheckStatus.PASS,
+                        message=f"Optional extra '{extra_name}' installed",
+                    )
+                )
+            except ImportError:
+                results.append(
+                    CheckResult(
+                        check_id=f"env-extra-{extra_name}",
+                        category="environment",
+                        status=CheckStatus.WARN,
+                        message=f"Optional extra '{extra_name}' not installed",
+                        fix_hint=fix_hint,
+                    )
+                )
+        return results

raise_cli/doctor/checks/project.py

@@ -0,0 +1,238 @@
+"""Built-in ProjectCheck — validates .raise/ structure and project coherence.
+
+Checks .raise/ directory, manifest.yaml, graph staleness, adapter config,
+skill deployment, and .gitignore entries.
+
+Architecture: ADR-045, S352.3
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import ClassVar
+
+import yaml
+
+from raise_cli.doctor.models import CheckResult, CheckStatus, DoctorContext
+
+
+class ProjectCheck:
+    """Diagnostic check for .raise/ project structure and coherence.
+
+    Registered via ``rai.doctor.checks`` entry point in pyproject.toml.
+    """
+
+    check_id: ClassVar[str] = "project"
+    category: ClassVar[str] = "project"
+    description: ClassVar[str] = (
+        ".raise/ structure, manifest, graph staleness, config"
+    )
+    requires_online: ClassVar[bool] = False
+
+    _GRAPH_STALENESS_DAYS: ClassVar[int] = 7
+
+    def evaluate(self, context: DoctorContext) -> list[CheckResult]:
+        """Run all project coherence checks."""
+        root = context.working_dir
+        results: list[CheckResult] = []
+
+        results.append(self._check_raise_dir(root))
+        results.append(self._check_manifest(root))
+        results.append(self._check_graph_staleness(root))
+        results.append(self._check_adapter_config(root))
+        results.append(self._check_skills_deployed(root))
+        results.append(self._check_gitignore(root))
+
+        return results
+
+    def _check_raise_dir(self, root: Path) -> CheckResult:
+        """Check that .raise/ directory exists."""
+        raise_dir = root / ".raise"
+        if raise_dir.is_dir():
+            return CheckResult(
+                check_id="project-raise-dir",
+                category=self.category,
+                status=CheckStatus.PASS,
+                message=".raise/ directory exists",
+            )
+        return CheckResult(
+            check_id="project-raise-dir",
+            category=self.category,
+            status=CheckStatus.ERROR,
+            message=".raise/ directory missing",
+            fix_hint="run: rai init",
+        )
+
+    def _check_manifest(self, root: Path) -> CheckResult:
+        """Check that manifest.yaml exists and is valid YAML."""
+        manifest = root / ".raise" / "manifest.yaml"
+        if not manifest.is_file():
+            return CheckResult(
+                check_id="project-manifest",
+                category=self.category,
+                status=CheckStatus.ERROR,
+                message="manifest.yaml missing",
+                fix_hint="run: rai init",
+            )
+        try:
+            content = manifest.read_text(encoding="utf-8")
+            parsed = yaml.safe_load(content)
+            if not isinstance(parsed, dict):
+                return CheckResult(
+                    check_id="project-manifest",
+                    category=self.category,
+                    status=CheckStatus.ERROR,
+                    message="manifest.yaml is not a valid YAML mapping",
+                )
+        except yaml.YAMLError as exc:
+            return CheckResult(
+                check_id="project-manifest",
+                category=self.category,
+                status=CheckStatus.ERROR,
+                message=f"manifest.yaml has invalid YAML: {exc}",
+            )
+        return CheckResult(
+            check_id="project-manifest",
+            category=self.category,
+            status=CheckStatus.PASS,
+            message="manifest.yaml is valid",
+        )
+
+    def _check_graph_staleness(self, root: Path) -> CheckResult:
+        """Check if graph index exists and is not stale."""
+        # Graph is stored at .raise/rai/memory/index.json (rai graph build output)
+        graph_index = root / ".raise" / "rai" / "memory" / "index.json"
+        if not graph_index.is_file():
+            return CheckResult(
+                check_id="project-graph",
+                category=self.category,
+                status=CheckStatus.WARN,
+                message="graph not built (.raise/rai/memory/index.json missing)",
+                fix_hint="run: rai graph build",
+                fix_id="rebuild-graph",
+            )
+
+        graph_files = [graph_index]
+        # Also check for additional graph files in the directory
+        graph_dir = graph_index.parent
+        graph_files.extend(f for f in graph_dir.rglob("*") if f.is_file() and f != graph_index)
+        if not graph_files:
+            return CheckResult(
+                check_id="project-graph",
+                category=self.category,
+                status=CheckStatus.WARN,
+                message="graph directory is empty",
+                fix_hint="run: rai graph build",
+                fix_id="rebuild-graph",
+            )
+
+        newest_graph = max(f.stat().st_mtime for f in graph_files)
+        now = time.time()
+        days_old = (now - newest_graph) / 86400
+
+        if days_old > self._GRAPH_STALENESS_DAYS:
+            return CheckResult(
+                check_id="project-graph",
+                category=self.category,
+                status=CheckStatus.WARN,
+                message=f"graph is {days_old:.0f} days old",
+                fix_hint="run: rai graph build",
+                fix_id="rebuild-graph",
+            )
+
+        # Check if governance files are newer than graph
+        governance_dir = root / "governance"
+        if governance_dir.is_dir():
+            gov_files = list(governance_dir.rglob("*.md"))
+            if gov_files:
+                newest_gov = max(f.stat().st_mtime for f in gov_files)
+                if newest_gov > newest_graph:
+                    return CheckResult(
+                        check_id="project-graph",
+                        category=self.category,
+                        status=CheckStatus.WARN,
+                        message="governance files are newer than graph",
+                        fix_hint="run: rai graph build",
+                        fix_id="rebuild-graph",
+                    )
+
+        return CheckResult(
+            check_id="project-graph",
+            category=self.category,
+            status=CheckStatus.PASS,
+            message="graph is up to date",
+        )
+
+    def _check_adapter_config(self, root: Path) -> CheckResult:
+        """Check if adapter config files are present (informational)."""
+        jira_config = root / ".raise" / "jira.yaml"
+        if jira_config.is_file():
+            return CheckResult(
+                check_id="project-adapter-config",
+                category=self.category,
+                status=CheckStatus.PASS,
+                message="jira.yaml adapter config found",
+            )
+        return CheckResult(
+            check_id="project-adapter-config",
+            category=self.category,
+            status=CheckStatus.WARN,
+            message="jira.yaml not found (optional — needed for Jira integration)",
+        )
+
+    def _check_skills_deployed(self, root: Path) -> CheckResult:
+        """Check if skills are deployed to .claude/skills/."""
+        skills_dir = root / ".claude" / "skills"
+        if not skills_dir.is_dir():
+            return CheckResult(
+                check_id="project-skills",
+                category=self.category,
+                status=CheckStatus.WARN,
+                message=".claude/skills/ directory missing",
+                fix_hint="run: rai skill sync",
+            )
+        skill_files = list(skills_dir.rglob("SKILL.md"))
+        if not skill_files:
+            return CheckResult(
+                check_id="project-skills",
+                category=self.category,
+                status=CheckStatus.WARN,
+                message="no skills deployed in .claude/skills/",
+                fix_hint="run: rai skill sync",
+            )
+        return CheckResult(
+            check_id="project-skills",
+            category=self.category,
+            status=CheckStatus.PASS,
+            message=f"{len(skill_files)} skills deployed",
+        )
+
+    def _check_gitignore(self, root: Path) -> CheckResult:
+        """Check if .raise/rai/personal/ is in .gitignore."""
+        gitignore = root / ".gitignore"
+        if not gitignore.is_file():
+            return CheckResult(
+                check_id="project-gitignore",
+                category=self.category,
+                status=CheckStatus.WARN,
+                message=".gitignore missing",
+                fix_hint="run: rai init",
+            )
+        content = gitignore.read_text(encoding="utf-8")
+        # Check for the personal directory pattern
+        if ".raise/rai/personal/" in content or ".raise/rai/personal" in content:
+            return CheckResult(
+                check_id="project-gitignore",
+                category=self.category,
+                status=CheckStatus.PASS,
+                message=".raise/rai/personal/ is in .gitignore",
+            )
+        return CheckResult(
+            check_id="project-gitignore",
+            category=self.category,
+            status=CheckStatus.WARN,
+            message=".raise/rai/personal/ not found in .gitignore",
+            fix_hint="run: rai init",
+            fix_id="add-gitignore-personal",
+        )

raise_cli/doctor/fix.py

@@ -0,0 +1,80 @@
+"""Auto-fix actions for rai doctor --fix.
+
+Each fix is a function registered via @register_fix(fix_id).
+Fix IDs correspond to CheckResult.fix_id values set by checks.
+
+Before any mutation, backups are created (.bak suffix).
+
+Architecture: S352.4
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+from collections.abc import Callable
+from pathlib import Path
+
+from raise_cli.doctor.models import CheckResult
+
+FIX_REGISTRY: dict[str, Callable[[Path], bool]] = {}
+
+
+def register_fix(fix_id: str) -> Callable[[Callable[[Path], bool]], Callable[[Path], bool]]:
+    """Decorator to register a fix function by ID."""
+
+    def decorator(fn: Callable[[Path], bool]) -> Callable[[Path], bool]:
+        FIX_REGISTRY[fix_id] = fn
+        return fn
+
+    return decorator
+
+
+@register_fix("rebuild-graph")
+def rebuild_graph(working_dir: Path) -> bool:
+    """Rebuild the knowledge graph by invoking ``rai graph build``."""
+    result = subprocess.run(
+        [sys.executable, "-m", "raise_cli", "graph", "build"],
+        cwd=working_dir,
+        capture_output=True,
+        text=True,
+    )
+    return result.returncode == 0
+
+
+@register_fix("add-gitignore-personal")
+def add_gitignore_personal(working_dir: Path) -> bool:
+    """Add .raise/rai/personal/ to .gitignore with backup."""
+    gitignore = working_dir / ".gitignore"
+    entry = ".raise/rai/personal/"
+
+    if gitignore.exists():
+        content = gitignore.read_text(encoding="utf-8")
+        if entry in content:
+            return True  # already present, no-op
+        # Backup before mutation
+        shutil.copy2(gitignore, working_dir / ".gitignore.bak")
+    else:
+        content = ""
+
+    with open(gitignore, "a", encoding="utf-8") as f:
+        f.write(f"\n# RaiSE personal data (sessions, telemetry)\n{entry}\n")
+    return True
+
+
+def run_fixes(
+    results: list[CheckResult],
+    working_dir: Path,
+) -> list[tuple[str, bool]]:
+    """Run fixes for all results that have a fix_id.
+
+    Returns:
+        List of (fix_id, success) pairs for each attempted fix.
+    """
+    outcomes: list[tuple[str, bool]] = []
+    for r in results:
+        if r.fix_id and r.fix_id in FIX_REGISTRY:
+            success = FIX_REGISTRY[r.fix_id](working_dir)
+            outcomes.append((r.fix_id, success))
+    return outcomes

raise_cli/doctor/models.py

@@ -0,0 +1,56 @@
+"""Doctor check result types.
+
+Frozen dataclasses (not Pydantic) — internal infrastructure, not boundary
+objects. Same rationale as gate models (ADR-039 S2).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+
+
+class CheckStatus(Enum):
+    """Three-level severity for doctor checks."""
+
+    PASS = "pass"
+    WARN = "warn"
+    ERROR = "error"
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    """Result from a single diagnostic check.
+
+    Attributes:
+        check_id: Unique identifier (e.g. ``"env-python-version"``).
+        category: Grouping key for output (e.g. ``"environment"``).
+        status: Pass, warning, or error.
+        message: Human-readable summary.
+        fix_hint: Actionable suggestion (e.g. ``"run: pip install raise-cli[mcp]"``).
+        details: Additional detail lines.
+    """
+
+    check_id: str
+    category: str
+    status: CheckStatus
+    message: str
+    fix_hint: str = ""
+    fix_id: str = ""
+    details: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class DoctorContext:
+    """Context passed to each check's ``evaluate()`` method.
+
+    Attributes:
+        working_dir: Project root directory.
+        online: Whether online checks (MCP, adapters) should run.
+        verbose: Whether to include extra detail.
+    """
+
+    working_dir: Path = field(default_factory=Path.cwd)
+    online: bool = False
+    verbose: bool = False

raise_cli/doctor/protocol.py

@@ -0,0 +1,43 @@
+"""DoctorCheck Protocol — contract for diagnostic check implementations.
+
+Doctor checks diagnose RaiSE's own health. They inform and suggest fixes,
+but never block operations (unlike WorkflowGates which guard transitions).
+
+Architecture: ADR-045 (DoctorCheck protocol).
+"""
+
+from __future__ import annotations
+
+from typing import ClassVar, Protocol, runtime_checkable
+
+from raise_cli.doctor.models import CheckResult, DoctorContext
+
+
+@runtime_checkable
+class DoctorCheck(Protocol):
+    """Contract for diagnostic check implementations.
+
+    Attributes:
+        check_id: Unique identifier (e.g. ``"environment"``).
+        category: Grouping key for output and pipeline ordering.
+        description: Human-readable purpose.
+        requires_online: If True, skipped unless ``--online`` flag is set.
+
+    Example::
+
+        class EnvironmentCheck:
+            check_id = "environment"
+            category = "environment"
+            description = "Python version, raise-cli version, OS, installed extras"
+            requires_online = False
+
+            def evaluate(self, context: DoctorContext) -> list[CheckResult]:
+                ...
+    """
+
+    check_id: ClassVar[str]
+    category: ClassVar[str]
+    description: ClassVar[str]
+    requires_online: ClassVar[bool]
+
+    def evaluate(self, context: DoctorContext) -> list[CheckResult]: ...

raise_cli/doctor/registry.py

@@ -0,0 +1,100 @@
+"""Check registry with entry point discovery.
+
+Discovers DoctorCheck implementations registered via Python entry points
+(``[project.entry-points."rai.doctor.checks"]`` in pyproject.toml).
+
+Architecture: ADR-045, same discovery pattern as gates (ADR-039 S3).
+"""
+
+from __future__ import annotations
+
+import inspect
+import logging
+from importlib.metadata import entry_points
+from typing import Any
+
+from raise_cli.doctor.protocol import DoctorCheck
+
+logger = logging.getLogger(__name__)
+
+EP_DOCTOR: str = "rai.doctor.checks"
+
+
+def _dist_name(ep: Any) -> str:
+    """Best-effort extraction of the distribution name for an entry point."""
+    try:
+        return ep.dist.name  # type: ignore[union-attr]
+    except AttributeError:
+        return "unknown"
+
+
+class CheckRegistry:
+    """Discovers and manages DoctorCheck implementations.
+
+    Example::
+
+        registry = CheckRegistry()
+        registry.discover()
+
+        for check in registry.checks:
+            print(f"{check.check_id}: {check.description}")
+    """
+
+    def __init__(self) -> None:
+        self._checks: list[DoctorCheck] = []
+
+    @property
+    def checks(self) -> list[DoctorCheck]:
+        """Return a copy of registered checks."""
+        return list(self._checks)
+
+    def discover(self) -> None:
+        """Load checks from ``rai.doctor.checks`` entry points.
+
+        Skips entry points that fail to load, are not classes, or don't
+        conform to the DoctorCheck Protocol.
+        """
+        for ep in entry_points(group=EP_DOCTOR):
+            try:
+                loaded: Any = ep.load()
+            except Exception as exc:  # noqa: BLE001
+                logger.warning(
+                    "Skipping doctor check '%s' from '%s': %s",
+                    ep.name,
+                    _dist_name(ep),
+                    exc,
+                )
+                continue
+
+            if not inspect.isclass(loaded):
+                logger.warning(
+                    "Skipping doctor check '%s': expected a class, got %s",
+                    ep.name,
+                    type(loaded).__name__,
+                )
+                continue
+
+            instance = loaded()
+            if not isinstance(instance, DoctorCheck):
+                logger.warning(
+                    "Skipping doctor check '%s': does not conform to DoctorCheck Protocol",
+                    ep.name,
+                )
+                continue
+
+            self._checks.append(instance)
+            logger.debug("Loaded doctor check '%s' (category=%s)", ep.name, instance.category)
+
+    def register(self, check: DoctorCheck | Any) -> None:
+        """Manually register a check instance (useful for testing)."""
+        if not isinstance(check, DoctorCheck):
+            logger.warning(
+                "Skipping manual check registration: %s does not conform to DoctorCheck",
+                type(check).__name__,
+            )
+            return
+        self._checks.append(check)
+
+    def get_checks_for_category(self, category: str) -> list[DoctorCheck]:
+        """Return checks matching the given category."""
+        return [c for c in self._checks if c.category == category]