raise-cli 2.2.1__py3-none-any.whl

raise_cli/doctor/report.py

@@ -0,0 +1,141 @@
+"""Diagnostic report generation and email submission."""
+
+from __future__ import annotations
+
+import importlib.util
+import platform
+import urllib.parse
+import webbrowser
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+
+from raise_cli.doctor.models import CheckResult, CheckStatus
+
+SUPPORT_EMAIL = "support@raise.humansys.ai"
+
+
+def _str_list() -> list[str]:
+    return []
+
+
+@dataclass
+class DiagnosticReport:
+    """Non-sensitive diagnostic snapshot."""
+
+    timestamp: str
+    rai_version: str
+    python_version: str
+    os_info: str
+    check_results: list[CheckResult]
+    raise_structure: list[str] = field(default_factory=_str_list)
+    installed_extras: list[str] = field(default_factory=_str_list)
+
+
+def generate_report(
+    results: list[CheckResult], working_dir: Path
+) -> DiagnosticReport:
+    """Collect non-sensitive data into report."""
+    # Get rai version
+    try:
+        from importlib.metadata import version
+
+        rai_ver = version("raise-cli")
+    except Exception:  # noqa: BLE001
+        rai_ver = "unknown"
+
+    # Collect .raise/ file names (not contents)
+    raise_dir = working_dir / ".raise"
+    structure: list[str] = []
+    if raise_dir.exists():
+        for p in sorted(raise_dir.rglob("*")):
+            if p.is_file():
+                structure.append(str(p.relative_to(working_dir)))
+
+    # Detect installed extras via find_spec (no actual import)
+    extras: list[str] = []
+    for pkg in ("mcp", "httpx"):
+        if importlib.util.find_spec(pkg) is not None:
+            extras.append(pkg)
+
+    return DiagnosticReport(
+        timestamp=datetime.now(UTC).isoformat(),
+        rai_version=rai_ver,
+        python_version=platform.python_version(),
+        os_info=f"{platform.system()} {platform.release()} ({platform.machine()})",
+        check_results=results,
+        raise_structure=structure[:50],  # cap at 50 files
+        installed_extras=extras,
+    )
+
+
+def report_to_markdown(report: DiagnosticReport) -> str:
+    """Render report as markdown."""
+    extras_str = ", ".join(report.installed_extras) if report.installed_extras else "none"
+    lines = [
+        "# rai doctor report",
+        "",
+        f"**Timestamp:** {report.timestamp}",
+        f"**raise-cli:** {report.rai_version}",
+        f"**Python:** {report.python_version}",
+        f"**OS:** {report.os_info}",
+        f"**Extras:** {extras_str}",
+        "",
+        "## Check Results",
+        "",
+    ]
+    for r in report.check_results:
+        icon = {"pass": "OK", "warn": "!!", "error": "XX"}[r.status.value]
+        lines.append(f"- [{icon}] {r.category}: {r.message}")
+        if r.fix_hint:
+            lines.append(f"  - hint: {r.fix_hint}")
+
+    if report.raise_structure:
+        lines.extend(["", "## .raise/ structure", ""])
+        for path in report.raise_structure:
+            lines.append(f"- {path}")
+
+    return "\n".join(lines)
+
+
+def save_report(report: DiagnosticReport, working_dir: Path) -> Path:
+    """Save report to .raise/rai/personal/report-{date}.md. Returns path."""
+    personal_dir = working_dir / ".raise" / "rai" / "personal"
+    personal_dir.mkdir(parents=True, exist_ok=True)
+    date_str = datetime.now(UTC).strftime("%Y-%m-%d")
+    path = personal_dir / f"report-{date_str}.md"
+    path.write_text(report_to_markdown(report))
+    return path
+
+
+def open_mailto(report: DiagnosticReport, to: str = SUPPORT_EMAIL) -> bool:
+    """Open default email client via mailto: URI. Returns True if opened."""
+    md = report_to_markdown(report)
+
+    # Count issues for subject
+    warns = sum(1 for r in report.check_results if r.status == CheckStatus.WARN)
+    errors = sum(1 for r in report.check_results if r.status == CheckStatus.ERROR)
+    parts: list[str] = []
+    if errors:
+        parts.append(f"{errors} error{'s' if errors > 1 else ''}")
+    if warns:
+        parts.append(f"{warns} warning{'s' if warns > 1 else ''}")
+    issue_summary = ", ".join(parts) if parts else "all clear"
+
+    subject = f"[rai-doctor] {report.rai_version} — {issue_summary}"
+
+    # Truncate body for mailto (most clients cap at ~2000 chars in URL)
+    body = md[:1800]
+    if len(md) > 1800:
+        body += "\n\n(truncated — full report in local file)"
+
+    mailto_url = (
+        f"mailto:{to}"
+        f"?subject={urllib.parse.quote(subject)}"
+        f"&body={urllib.parse.quote(body)}"
+    )
+
+    try:
+        return webbrowser.open(mailto_url)
+    except Exception:  # noqa: BLE001
+        return False

raise_cli/doctor/runner.py

@@ -0,0 +1,95 @@
+"""Doctor check runner — executes checks in pipeline order.
+
+Pipeline order ensures dependencies: environment must pass before
+project checks, project before adapters, etc.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from raise_cli.doctor.models import CheckResult, CheckStatus, DoctorContext
+from raise_cli.doctor.registry import CheckRegistry
+
+logger = logging.getLogger(__name__)
+
+PIPELINE_ORDER: list[str] = [
+    "environment",
+    "project",
+    "adapters",
+    "skills",
+    "mcp",
+]
+
+
+def run_checks(
+    registry: CheckRegistry,
+    context: DoctorContext,
+    categories: list[str] | None = None,
+) -> list[CheckResult]:
+    """Execute checks in pipeline order.
+
+    Args:
+        registry: Check registry with discovered checks.
+        context: Execution context (working_dir, online, verbose).
+        categories: If provided, only run checks in these categories.
+
+    Returns:
+        All check results in execution order.
+    """
+    results: list[CheckResult] = []
+    critical_failure = False
+
+    ordered = categories or PIPELINE_ORDER
+
+    for category in ordered:
+        if critical_failure:
+            results.append(
+                CheckResult(
+                    check_id=f"{category}-skipped",
+                    category=category,
+                    status=CheckStatus.WARN,
+                    message="Skipped — previous category had critical errors",
+                )
+            )
+            continue
+
+        checks = registry.get_checks_for_category(category)
+        if not checks:
+            continue
+
+        for check in checks:
+            if check.requires_online and not context.online:
+                logger.debug("Skipping online check '%s'", check.check_id)
+                continue
+
+            try:
+                check_results = check.evaluate(context)
+                results.extend(check_results)
+            except Exception as exc:  # noqa: BLE001
+                logger.warning("Check '%s' raised: %s", check.check_id, exc)
+                results.append(
+                    CheckResult(
+                        check_id=check.check_id,
+                        category=check.category,
+                        status=CheckStatus.ERROR,
+                        message=f"Check crashed: {exc}",
+                    )
+                )
+
+        # If any ERROR in this category, flag for downstream skip
+        category_errors = [
+            r for r in results if r.category == category and r.status == CheckStatus.ERROR
+        ]
+        if category_errors and category == "environment":
+            critical_failure = True
+
+    return results
+
+
+def summarize(results: list[CheckResult]) -> tuple[int, int, int]:
+    """Count pass/warn/error results. Returns (pass_count, warn_count, error_count)."""
+    passes = sum(1 for r in results if r.status == CheckStatus.PASS)
+    warns = sum(1 for r in results if r.status == CheckStatus.WARN)
+    errors = sum(1 for r in results if r.status == CheckStatus.ERROR)
+    return passes, warns, errors

raise_cli/engines/__init__.py

@@ -0,0 +1,3 @@
+"""Engines."""
+
+from __future__ import annotations

raise_cli/exceptions.py

@@ -0,0 +1,215 @@
+"""Centralized exception hierarchy for raise-cli.
+
+This module defines all exceptions used throughout raise-cli with:
+- Consistent exit codes for scripting
+- Error codes for documentation/troubleshooting
+- Optional hints and details for user guidance
+
+Exit Code Table:
+    0  - Success
+    1  - General error (RaiError)
+    2  - Configuration error
+    3  - Resource not found (kata, gate)
+    4  - Artifact not found
+    5  - Dependency unavailable
+    6  - State corruption
+    7  - Validation error
+    10 - Gate failed
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class RaiError(Exception):
+    """Base exception for all raise-cli errors.
+
+    All raise-cli exceptions inherit from this class, providing:
+    - exit_code: Process exit code for scripting
+    - error_code: Unique identifier for documentation
+    - message: Human-readable error description
+    - hint: Optional suggestion for resolution
+    - details: Optional structured data for debugging
+
+    Example:
+        >>> raise RaiError("Something went wrong", hint="Try again")
+    """
+
+    exit_code: int = 1
+    error_code: str = "E000"
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        hint: str | None = None,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize a RaiError.
+
+        Args:
+            message: Human-readable error description.
+            hint: Optional suggestion for resolution.
+            details: Optional structured data for debugging.
+        """
+        self.message = message
+        self.hint = hint
+        self.details = details or {}
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        """Return the error message."""
+        return self.message
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert exception to dictionary for JSON output.
+
+        Returns:
+            Dictionary with error_code, exit_code, message, hint, and details.
+        """
+        return {
+            "error_code": self.error_code,
+            "exit_code": self.exit_code,
+            "message": self.message,
+            "hint": self.hint,
+            "details": self.details,
+        }
+
+
+class ConfigurationError(RaiError):
+    """Configuration-related errors.
+
+    Raised when:
+    - Config file is malformed
+    - Required configuration is missing
+    - Configuration values are invalid
+
+    Exit code: 2
+    """
+
+    exit_code: int = 2
+    error_code: str = "E001"
+
+
+class KataNotFoundError(RaiError):
+    """Kata definition not found.
+
+    Raised when a requested kata ID does not exist in .raise/katas/.
+
+    Exit code: 3
+    """
+
+    exit_code: int = 3
+    error_code: str = "E002"
+
+
+class GateNotFoundError(RaiError):
+    """Gate definition not found.
+
+    Raised when a requested gate ID does not exist in .raise/gates/.
+
+    Exit code: 3
+    """
+
+    exit_code: int = 3
+    error_code: str = "E003"
+
+
+class ArtifactNotFoundError(RaiError):
+    """Artifact file not found.
+
+    Raised when a referenced artifact path does not exist.
+
+    Exit code: 4
+    """
+
+    exit_code: int = 4
+    error_code: str = "E004"
+
+
+class DependencyError(RaiError):
+    """External dependency not available.
+
+    Raised when a required external tool is not installed or accessible:
+    - git
+    - ast-grep
+    - ripgrep
+
+    Exit code: 5
+    """
+
+    exit_code: int = 5
+    error_code: str = "E005"
+
+
+class StateError(RaiError):
+    """State file corrupted or invalid.
+
+    Raised when:
+    - State file cannot be parsed
+    - State schema validation fails
+    - State version mismatch
+
+    Exit code: 6
+    """
+
+    exit_code: int = 6
+    error_code: str = "E006"
+
+
+class ValidationError(RaiError):
+    """Schema or artifact validation failed.
+
+    Raised when:
+    - Pydantic schema validation fails
+    - Artifact content validation fails
+    - Input format is invalid
+
+    Exit code: 7
+    """
+
+    exit_code: int = 7
+    error_code: str = "E007"
+
+
+class GateFailedError(RaiError):
+    """Gate validation did not pass.
+
+    Raised when one or more required gate criteria fail.
+    This is a "business logic" failure, not a system error.
+
+    Exit code: 10
+    """
+
+    exit_code: int = 10
+    error_code: str = "E010"
+
+
+class RaiSessionNotFoundError(RaiError):
+    """Session ID not provided or resolvable.
+
+    Raised when:
+    - Neither --session flag nor RAI_SESSION_ID env var is provided
+    - Session ID is required but cannot be determined
+
+    Exit code: 2 (configuration error - user must provide session context)
+    """
+
+    exit_code: int = 2
+    error_code: str = "E011"
+
+
+# All public exceptions
+__all__ = [
+    "RaiError",
+    "ConfigurationError",
+    "KataNotFoundError",
+    "GateNotFoundError",
+    "ArtifactNotFoundError",
+    "DependencyError",
+    "StateError",
+    "ValidationError",
+    "GateFailedError",
+    "RaiSessionNotFoundError",
+]

raise_cli/gates/__init__.py

@@ -0,0 +1,19 @@
+"""Workflow gates infrastructure for raise-cli.
+
+Provides standalone quality gates that validate workflow transitions.
+Gates are independent of the event emitter (AD-5) and can be invoked
+directly via ``rai gate check``.
+
+Architecture: ADR-039 §1 (WorkflowGate Protocol), §5 (Standalone gates)
+"""
+
+from raise_cli.gates.models import GateContext, GateResult
+from raise_cli.gates.protocol import WorkflowGate
+from raise_cli.gates.registry import GateRegistry
+
+__all__ = [
+    "GateContext",
+    "GateRegistry",
+    "GateResult",
+    "WorkflowGate",
+]

raise_cli/gates/builtin/__init__.py

@@ -0,0 +1 @@
+"""Built-in quality gates for raise-cli (COMMUNITY tier)."""

raise_cli/gates/builtin/coverage.py

@@ -0,0 +1,52 @@
+"""Built-in CoverageGate — validates test coverage collection succeeds.
+
+Runs ``pytest --cov --cov-report=term-missing -q`` and reports pass/fail.
+Per PAT-E-444, coverage is diagnostic — this gate checks that coverage
+collection succeeds, not a specific percentage threshold.
+
+Architecture: ADR-039 §5 (Built-in gates), S248.6
+"""
+
+from __future__ import annotations
+
+import subprocess
+from typing import ClassVar
+
+from raise_cli.gates.models import GateContext, GateResult
+
+
+class CoverageGate:
+    """Quality gate that runs pytest with coverage.
+
+    Registered via ``rai.gates`` entry point in pyproject.toml.
+    """
+
+    gate_id: ClassVar[str] = "gate-coverage"
+    description: ClassVar[str] = "Coverage collection succeeds"
+    workflow_point: ClassVar[str] = "before:release:publish"
+
+    def evaluate(self, context: GateContext) -> GateResult:
+        """Run pytest --cov and return pass/fail result."""
+        try:
+            result = subprocess.run(
+                ["pytest", "--cov", "--cov-report=term-missing", "-q"],
+                capture_output=True,
+                text=True,
+                cwd=str(context.working_dir),
+            )
+        except Exception as exc:  # noqa: BLE001
+            return GateResult(
+                passed=False,
+                gate_id=self.gate_id,
+                message=f"{type(exc).__name__}: {exc}",
+            )
+
+        passed = result.returncode == 0
+        return GateResult(
+            passed=passed,
+            gate_id=self.gate_id,
+            message="Coverage collection succeeds"
+            if passed
+            else "Coverage check failed",
+            details=(result.stdout,) if not passed else (),
+        )

raise_cli/gates/builtin/lint.py

@@ -0,0 +1,48 @@
+"""Built-in LintGate — validates linting passes.
+
+Runs ``ruff check .`` and reports pass/fail.
+
+Architecture: ADR-039 §5 (Built-in gates), S248.6
+"""
+
+from __future__ import annotations
+
+import subprocess
+from typing import ClassVar
+
+from raise_cli.gates.models import GateContext, GateResult
+
+
+class LintGate:
+    """Quality gate that runs ruff.
+
+    Registered via ``rai.gates`` entry point in pyproject.toml.
+    """
+
+    gate_id: ClassVar[str] = "gate-lint"
+    description: ClassVar[str] = "Linting passes"
+    workflow_point: ClassVar[str] = "before:release:publish"
+
+    def evaluate(self, context: GateContext) -> GateResult:
+        """Run ruff check and return pass/fail result."""
+        try:
+            result = subprocess.run(
+                ["ruff", "check", "."],
+                capture_output=True,
+                text=True,
+                cwd=str(context.working_dir),
+            )
+        except Exception as exc:  # noqa: BLE001
+            return GateResult(
+                passed=False,
+                gate_id=self.gate_id,
+                message=f"{type(exc).__name__}: {exc}",
+            )
+
+        passed = result.returncode == 0
+        return GateResult(
+            passed=passed,
+            gate_id=self.gate_id,
+            message="Linting passes" if passed else "Lint errors found",
+            details=(result.stdout,) if not passed else (),
+        )

raise_cli/gates/builtin/tests.py

@@ -0,0 +1,48 @@
+"""Built-in TestGate — validates all tests pass.
+
+Runs ``pytest -x --tb=short`` and reports pass/fail.
+
+Architecture: ADR-039 §5 (Built-in gates), S248.6
+"""
+
+from __future__ import annotations
+
+import subprocess
+from typing import ClassVar
+
+from raise_cli.gates.models import GateContext, GateResult
+
+
+class TestGate:
+    """Quality gate that runs pytest.
+
+    Registered via ``rai.gates`` entry point in pyproject.toml.
+    """
+
+    gate_id: ClassVar[str] = "gate-tests"
+    description: ClassVar[str] = "All tests pass"
+    workflow_point: ClassVar[str] = "before:release:publish"
+
+    def evaluate(self, context: GateContext) -> GateResult:
+        """Run pytest and return pass/fail result."""
+        try:
+            result = subprocess.run(
+                ["pytest", "-x", "--tb=short"],
+                capture_output=True,
+                text=True,
+                cwd=str(context.working_dir),
+            )
+        except Exception as exc:  # noqa: BLE001
+            return GateResult(
+                passed=False,
+                gate_id=self.gate_id,
+                message=f"{type(exc).__name__}: {exc}",
+            )
+
+        passed = result.returncode == 0
+        return GateResult(
+            passed=passed,
+            gate_id=self.gate_id,
+            message="Tests pass" if passed else "Tests failing",
+            details=(result.stdout,) if not passed else (),
+        )

raise_cli/gates/builtin/types.py

@@ -0,0 +1,48 @@
+"""Built-in TypeGate — validates no type errors.
+
+Runs ``pyright`` and reports pass/fail.
+
+Architecture: ADR-039 §5 (Built-in gates), S248.6
+"""
+
+from __future__ import annotations
+
+import subprocess
+from typing import ClassVar
+
+from raise_cli.gates.models import GateContext, GateResult
+
+
+class TypeGate:
+    """Quality gate that runs pyright.
+
+    Registered via ``rai.gates`` entry point in pyproject.toml.
+    """
+
+    gate_id: ClassVar[str] = "gate-types"
+    description: ClassVar[str] = "No type errors"
+    workflow_point: ClassVar[str] = "before:release:publish"
+
+    def evaluate(self, context: GateContext) -> GateResult:
+        """Run pyright and return pass/fail result."""
+        try:
+            result = subprocess.run(
+                ["pyright"],
+                capture_output=True,
+                text=True,
+                cwd=str(context.working_dir),
+            )
+        except Exception as exc:  # noqa: BLE001
+            return GateResult(
+                passed=False,
+                gate_id=self.gate_id,
+                message=f"{type(exc).__name__}: {exc}",
+            )
+
+        passed = result.returncode == 0
+        return GateResult(
+            passed=passed,
+            gate_id=self.gate_id,
+            message="No type errors" if passed else "Type errors found",
+            details=(result.stdout,) if not passed else (),
+        )