raise-cli 2.2.1__py3-none-any.whl

raise_cli/hooks/events.py

@@ -0,0 +1,262 @@
+"""Typed lifecycle event definitions.
+
+Each event is a frozen dataclass with a specific payload type.
+Events use frozen dataclasses (not Pydantic) because they are internal
+infrastructure, not boundary objects.
+
+Architecture: ADR-039 §2 (Typed events as frozen dataclasses)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Literal
+
+
+def _now_utc() -> datetime:
+    """Return current UTC datetime."""
+    return datetime.now(UTC)
+
+
+@dataclass(frozen=True)
+class HookEvent:
+    """Base class for all lifecycle events.
+
+    Subclasses set ``event_name`` via a class-level default with ``init=False``.
+    ``timestamp`` defaults to now(UTC) but can be overridden for testing.
+    """
+
+    event_name: str = field(init=False, default="")
+    timestamp: datetime = field(default_factory=_now_utc)
+
+
+@dataclass(frozen=True)
+class HookResult:
+    """Result returned by a hook handler.
+
+    Attributes:
+        status: ``ok`` (success), ``abort`` (request operation abort,
+                only valid for ``before:`` events), or ``error`` (handler failed).
+        message: Human-readable detail (required for abort/error).
+    """
+
+    status: Literal["ok", "abort", "error"] = "ok"
+    message: str = ""
+
+
+@dataclass(frozen=True)
+class EmitResult:
+    """Aggregate result from dispatching an event to all handlers.
+
+    Attributes:
+        aborted: True if a handler requested abort on a ``before:`` event.
+        abort_message: Reason for abort.
+        handler_errors: Error messages from handlers that raised exceptions.
+    """
+
+    aborted: bool = False
+    abort_message: str = ""
+    handler_errors: tuple[str, ...] = ()
+
+
+# ---------------------------------------------------------------------------
+# Concrete events
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class SessionStartEvent(HookEvent):
+    """Emitted after a session starts."""
+
+    event_name: Literal["session:start"] = field(  # type: ignore[assignment]
+        default="session:start", init=False
+    )
+    session_id: str = ""
+    developer: str = ""
+
+
+@dataclass(frozen=True)
+class SessionCloseEvent(HookEvent):
+    """Emitted after a session closes."""
+
+    event_name: Literal["session:close"] = field(  # type: ignore[assignment]
+        default="session:close", init=False
+    )
+    session_id: str = ""
+    outcome: str = ""
+
+
+@dataclass(frozen=True)
+class GraphBuildEvent(HookEvent):
+    """Emitted after a graph build completes."""
+
+    event_name: Literal["graph:build"] = field(  # type: ignore[assignment]
+        default="graph:build", init=False
+    )
+    project_path: Path = field(default_factory=lambda: Path("."))
+    node_count: int = 0
+    edge_count: int = 0
+
+
+@dataclass(frozen=True)
+class PatternAddedEvent(HookEvent):
+    """Emitted after a pattern is added to memory."""
+
+    event_name: Literal["pattern:added"] = field(  # type: ignore[assignment]
+        default="pattern:added", init=False
+    )
+    pattern_id: str = ""
+    content: str = ""
+    context: str = ""
+
+
+@dataclass(frozen=True)
+class DiscoverScanEvent(HookEvent):
+    """Emitted after a discovery scan completes."""
+
+    event_name: Literal["discover:scan"] = field(  # type: ignore[assignment]
+        default="discover:scan", init=False
+    )
+    project_path: Path = field(default_factory=lambda: Path("."))
+    language: str = ""
+    component_count: int = 0
+
+
+@dataclass(frozen=True)
+class InitCompleteEvent(HookEvent):
+    """Emitted after project initialization completes."""
+
+    event_name: Literal["init:complete"] = field(  # type: ignore[assignment]
+        default="init:complete", init=False
+    )
+    project_path: Path = field(default_factory=lambda: Path("."))
+    project_name: str = ""
+
+
+@dataclass(frozen=True)
+class AdapterLoadedEvent(HookEvent):
+    """Emitted after an adapter is successfully loaded from entry points."""
+
+    event_name: Literal["adapter:loaded"] = field(  # type: ignore[assignment]
+        default="adapter:loaded", init=False
+    )
+    adapter_name: str = ""
+    group: str = ""
+    adapter_type: str = ""
+
+
+@dataclass(frozen=True)
+class AdapterFailedEvent(HookEvent):
+    """Emitted when an adapter fails to load from entry points."""
+
+    event_name: Literal["adapter:failed"] = field(  # type: ignore[assignment]
+        default="adapter:failed", init=False
+    )
+    adapter_name: str = ""
+    group: str = ""
+    error: str = ""
+
+
+@dataclass(frozen=True)
+class ReleasePublishEvent(HookEvent):
+    """Emitted after a release is published."""
+
+    event_name: Literal["release:publish"] = field(  # type: ignore[assignment]
+        default="release:publish", init=False
+    )
+    version: str = ""
+    project_path: Path = field(default_factory=lambda: Path("."))
+
+
+@dataclass(frozen=True)
+class WorkLifecycleEvent(HookEvent):
+    """Emitted when a work lifecycle signal is recorded.
+
+    Bridges ``rai signal emit-work`` to the hook system so hooks like
+    BacklogHook can react to story/epic lifecycle transitions.
+    """
+
+    event_name: Literal["work:lifecycle"] = field(  # type: ignore[assignment]
+        default="work:lifecycle", init=False
+    )
+    work_type: str = ""  # "story" or "epic"
+    work_id: str = ""  # e.g. "S325.4", "E325"
+    event: str = ""  # "start", "complete", "blocked", etc.
+    phase: str = ""  # "design", "plan", "implement", "review", "close"
+
+
+# ---------------------------------------------------------------------------
+# Work lifecycle events (S301.6: auto-sync hooks)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class WorkStartEvent(HookEvent):
+    """Emitted when a work item (story/epic) starts."""
+
+    event_name: Literal["work:start"] = field(  # type: ignore[assignment]
+        default="work:start", init=False
+    )
+    work_type: str = ""
+    work_id: str = ""
+    issue_key: str = ""
+
+
+@dataclass(frozen=True)
+class WorkCloseEvent(HookEvent):
+    """Emitted when a work item (story/epic) closes."""
+
+    event_name: Literal["work:close"] = field(  # type: ignore[assignment]
+        default="work:close", init=False
+    )
+    work_type: str = ""
+    work_id: str = ""
+    issue_key: str = ""
+
+
+# ---------------------------------------------------------------------------
+# Before-variant events (AD-6: only release:publish and session:close)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class BeforeSessionCloseEvent(HookEvent):
+    """Emitted before a session closes. Handlers can abort."""
+
+    event_name: Literal["before:session:close"] = field(  # type: ignore[assignment]
+        default="before:session:close", init=False
+    )
+    session_id: str = ""
+    outcome: str = ""
+
+
+@dataclass(frozen=True)
+class BeforeReleasePublishEvent(HookEvent):
+    """Emitted before a release is published. Handlers can abort."""
+
+    event_name: Literal["before:release:publish"] = field(  # type: ignore[assignment]
+        default="before:release:publish", init=False
+    )
+    version: str = ""
+    project_path: Path = field(default_factory=lambda: Path("."))
+
+
+# ---------------------------------------------------------------------------
+# MCP events (E338: MCP Platform)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class McpCallEvent(HookEvent):
+    """Emitted after an MCP tool call completes (success or failure)."""
+
+    event_name: Literal["mcp:call"] = field(  # type: ignore[assignment]
+        default="mcp:call", init=False
+    )
+    server: str = ""
+    tool: str = ""
+    success: bool = True
+    latency_ms: int = 0
+    error: str = ""

raise_cli/hooks/protocol.py

@@ -0,0 +1,38 @@
+"""LifecycleHook Protocol — contract for hook implementations.
+
+Hooks react to CLI lifecycle events (telemetry, notifications, compliance).
+A hook failure is logged and skipped — hooks never crash the CLI.
+
+Architecture: ADR-039 §1 (LifecycleHook Protocol)
+"""
+
+from __future__ import annotations
+
+from typing import ClassVar, Protocol, runtime_checkable
+
+from raise_cli.hooks.events import HookEvent, HookResult
+
+
+@runtime_checkable
+class LifecycleHook(Protocol):
+    """Contract for lifecycle hook implementations.
+
+    Attributes:
+        events: Event names this hook subscribes to (e.g. ``["session:start"]``).
+        priority: Dispatch order — higher runs first. Default ``0``.
+
+    Example::
+
+        class TelemetryHook:
+            events = ["session:start", "graph:build"]
+            priority = 0
+
+            def handle(self, event: HookEvent) -> HookResult:
+                # write to signals.jsonl...
+                return HookResult(status="ok")
+    """
+
+    events: ClassVar[list[str]]
+    priority: ClassVar[int]
+
+    def handle(self, event: HookEvent) -> HookResult: ...

raise_cli/hooks/registry.py

@@ -0,0 +1,117 @@
+"""Hook registry with entry point discovery.
+
+Discovers LifecycleHook implementations registered via Python entry points
+(``[project.entry-points."rai.hooks"]`` in pyproject.toml). Validates
+Protocol conformance before accepting hooks.
+
+Architecture: ADR-039 §3 (Entry point discovery, same as RAISE-211)
+"""
+
+from __future__ import annotations
+
+import inspect
+import logging
+from importlib.metadata import entry_points
+from typing import Any
+
+from raise_cli.hooks.protocol import LifecycleHook
+
+logger = logging.getLogger(__name__)
+
+EP_HOOKS: str = "rai.hooks"
+
+
+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 HookRegistry:
+    """Discovers and manages LifecycleHook implementations.
+
+    Example::
+
+        registry = HookRegistry()
+        registry.discover()  # loads from rai.hooks entry points
+
+        for hook in registry.hooks:
+            print(f"{hook.__class__.__name__}: priority={hook.priority}")
+
+        handlers = registry.get_hooks_for_event("session:start")
+    """
+
+    def __init__(self) -> None:
+        self._hooks: list[LifecycleHook] = []
+
+    @property
+    def hooks(self) -> list[LifecycleHook]:
+        """Return a copy of registered hooks."""
+        return list(self._hooks)
+
+    def discover(self) -> None:
+        """Load hooks from ``rai.hooks`` entry points.
+
+        Skips entry points that:
+        - Fail to load (ImportError, etc.)
+        - Are not classes
+        - Don't conform to the LifecycleHook Protocol
+        """
+        for ep in entry_points(group=EP_HOOKS):
+            try:
+                loaded: Any = ep.load()
+            except Exception as exc:  # noqa: BLE001
+                logger.warning(
+                    "Skipping hook entry point '%s' from '%s': %s",
+                    ep.name,
+                    _dist_name(ep),
+                    exc,
+                )
+                continue
+
+            if not inspect.isclass(loaded):
+                logger.warning(
+                    "Skipping hook entry point '%s' from '%s': expected a class, got %s",
+                    ep.name,
+                    _dist_name(ep),
+                    type(loaded).__name__,
+                )
+                continue
+
+            instance = loaded()
+            if not isinstance(instance, LifecycleHook):
+                logger.warning(
+                    "Skipping hook entry point '%s' from '%s': "
+                    "does not conform to LifecycleHook Protocol",
+                    ep.name,
+                    _dist_name(ep),
+                )
+                continue
+
+            self._hooks.append(instance)
+            logger.debug(
+                "Loaded hook '%s' (priority=%d, events=%s)",
+                ep.name,
+                instance.priority,
+                instance.events,
+            )
+
+    def register(self, hook: LifecycleHook | Any) -> None:
+        """Manually register a hook instance (useful for testing).
+
+        Silently skips non-compliant objects.
+        """
+        if not isinstance(hook, LifecycleHook):
+            logger.warning(
+                "Skipping manual hook registration: %s does not conform to LifecycleHook Protocol",
+                type(hook).__name__,
+            )
+            return
+        self._hooks.append(hook)
+
+    def get_hooks_for_event(self, event_name: str) -> list[LifecycleHook]:
+        """Return hooks subscribed to ``event_name``, sorted by priority (highest first)."""
+        matching = [h for h in self._hooks if event_name in h.events]
+        return sorted(matching, key=lambda h: h.priority, reverse=True)

raise_cli/mcp/__init__.py

@@ -0,0 +1,33 @@
+"""MCP infrastructure layer — independent of domain adapters.
+
+Provides generic MCP server management: bridge, models, schema, registry.
+Domain adapters (PM, Docs) live in ``raise_cli.adapters`` and consume this layer.
+
+Architecture: ADR-042, E338
+
+Note: Bridge imports are lazy because the ``mcp`` SDK and ``logfire-api``
+are optional dependencies. Eager import would crash CLI startup when
+these packages are not installed.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from raise_cli.mcp.models import McpHealthResult, McpToolInfo, McpToolResult
+from raise_cli.mcp.registry import discover_mcp_servers
+from raise_cli.mcp.schema import McpServerConfig, ServerConnection
+
+if TYPE_CHECKING:
+    from raise_cli.mcp.bridge import McpBridge, McpBridgeError
+
+__all__ = [
+    "McpBridge",
+    "McpBridgeError",
+    "McpHealthResult",
+    "McpServerConfig",
+    "McpToolInfo",
+    "McpToolResult",
+    "ServerConnection",
+    "discover_mcp_servers",
+]

raise_cli/mcp/bridge.py

@@ -0,0 +1,218 @@
+"""Generic MCP server bridge using the official MCP Python SDK.
+
+Manages server process lifecycle, async session, and RaiSE telemetry.
+Works with any MCP server via stdio transport.
+
+Architecture: E301 epic design (D1, D3, D4), moved to raise_cli.mcp (ADR-042, E338)
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import logging
+import subprocess
+import time
+from contextlib import AsyncExitStack
+from typing import Any
+
+try:
+    import logfire_api as logfire
+except ModuleNotFoundError:  # pragma: no cover
+    logfire = None  # type: ignore[assignment]
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+from mcp.types import TextContent
+
+from raise_cli.mcp.models import McpHealthResult, McpToolInfo, McpToolResult
+
+logger = logging.getLogger(__name__)
+
+
+class McpBridgeError(Exception):
+    """Raised when MCP bridge operations fail."""
+
+
+class McpBridge:
+    """Generic async bridge to any MCP server via official Python SDK.
+
+    Manages server process lifecycle, session, and RaiSE telemetry.
+    Session is lazy — created on first call, reused if alive,
+    reconnected if dead.
+
+    Args:
+        server_command: Command to start MCP server (e.g. "mcp-atlassian").
+        server_args: Optional args for the server command.
+        env: Optional environment variables. None = inherit parent env.
+    """
+
+    def __init__(
+        self,
+        server_command: str,
+        server_args: list[str] | None = None,
+        env: dict[str, str] | None = None,
+    ) -> None:
+        self._server_command = server_command
+        self._server_args = server_args or []
+        self._env = env  # None = subprocess inherits os.environ
+        self._session: ClientSession | None = None
+        self._cm_stack: AsyncExitStack | None = None
+
+    async def call(self, tool_name: str, arguments: dict[str, Any]) -> McpToolResult:
+        """Call a tool on the MCP server.
+
+        Wraps ClientSession.call_tool() with telemetry and error handling.
+
+        Args:
+            tool_name: MCP tool name (e.g. "jira_get_issue").
+            arguments: Tool arguments dict.
+
+        Returns:
+            Parsed McpToolResult.
+
+        Raises:
+            McpBridgeError: On connection or tool call failure.
+        """
+        span_cm = (
+            logfire.span(
+                "mcp.tool_call",
+                mcp_server=self._server_command,
+                mcp_tool=tool_name,
+            )
+            if logfire is not None
+            else contextlib.nullcontext()
+        )
+        with span_cm as span:
+            start = time.monotonic()
+            session = await self._ensure_session()
+            try:
+                result = await session.call_tool(tool_name, arguments)
+                elapsed_ms = int((time.monotonic() - start) * 1000)
+                if span is not None:
+                    span.set_attribute("duration_ms", elapsed_ms)
+                    span.set_attribute("success", not result.isError)
+                return self._parse_result(result)
+            except Exception as exc:
+                elapsed_ms = int((time.monotonic() - start) * 1000)
+                if span is not None:
+                    span.set_attribute("duration_ms", elapsed_ms)
+                    span.set_attribute("success", False)
+                raise McpBridgeError(f"Tool call '{tool_name}' failed: {exc}") from exc
+
+    async def list_tools(self) -> list[McpToolInfo]:
+        """List available tools on the server."""
+        session = await self._ensure_session()
+        result = await session.list_tools()
+        return [
+            McpToolInfo(name=t.name, description=t.description or "")
+            for t in result.tools
+        ]
+
+    async def health(self) -> McpHealthResult:
+        """Check server connectivity and tool availability."""
+        start = time.monotonic()
+        try:
+            tools = await self.list_tools()
+            elapsed_ms = int((time.monotonic() - start) * 1000)
+            return McpHealthResult(
+                server_name=self._server_command,
+                healthy=True,
+                message=f"OK, {len(tools)} tools",
+                latency_ms=elapsed_ms,
+                tool_count=len(tools),
+            )
+        except Exception as exc:
+            elapsed_ms = int((time.monotonic() - start) * 1000)
+            return McpHealthResult(
+                server_name=self._server_command,
+                healthy=False,
+                message=str(exc),
+                latency_ms=elapsed_ms,
+            )
+
+    async def _ensure_session(self) -> ClientSession:
+        """Lazy connect. Reconnects if session is closed/dead."""
+        if self._session is not None:
+            try:
+                await self._session.list_tools()
+                return self._session
+            except Exception:
+                await self._cleanup()
+
+        params = StdioServerParameters(
+            command=self._server_command,
+            args=self._server_args,
+            env=self._env,
+        )
+        stack = AsyncExitStack()
+        try:
+            # Redirect MCP server stderr to devnull to suppress banner/warning noise.
+            # Server errors are captured via MCP protocol (isError), not stderr.
+            # subprocess.DEVNULL is an int constant (-3) accepted by anyio.open_process;
+            # avoids sync open() in async context (RAISE-436).
+            read, write = await stack.enter_async_context(
+                stdio_client(params, errlog=subprocess.DEVNULL)  # type: ignore[arg-type]
+            )
+            session = await stack.enter_async_context(ClientSession(read, write))
+            await session.initialize()
+        except FileNotFoundError as exc:
+            await stack.aclose()
+            raise McpBridgeError(
+                f"MCP server '{self._server_command}' not found. "
+                f"Install the server and ensure it's on PATH."
+            ) from exc
+        except Exception as exc:
+            await stack.aclose()
+            raise McpBridgeError(
+                f"Failed to connect to MCP server '{self._server_command}': {exc}"
+            ) from exc
+
+        self._session = session
+        self._cm_stack = stack
+        return session
+
+    async def aclose(self) -> None:
+        """Close session and exit stack.
+
+        Must be called within the same event loop that created the session.
+        Prevents asyncgen finalizer tracebacks from stdio_client (RAISE-324).
+        """
+        if self._cm_stack:
+            with contextlib.suppress(Exception):
+                await self._cm_stack.aclose()
+        self._session = None
+        self._cm_stack = None
+
+    async def _cleanup(self) -> None:
+        """Alias for aclose() — used internally by _ensure_session."""
+        await self.aclose()
+
+    @staticmethod
+    def _parse_result(result: Any) -> McpToolResult:
+        """Parse CallToolResult into McpToolResult.
+
+        Handles: empty content, multiple text items, non-text content,
+        isError flag, and JSON auto-parsing.
+        """
+        if result.isError:
+            texts = [c.text for c in result.content if isinstance(c, TextContent)]
+            error_text = "\n".join(texts) if texts else "Unknown error"
+            return McpToolResult(is_error=True, error_message=error_text)
+
+        # Collect all text content, ignore non-text
+        texts = [c.text for c in result.content if isinstance(c, TextContent)]
+        text = "\n".join(texts) if texts else ""
+
+        # Try parse as JSON for structured access
+        data: dict[str, Any] = {}
+        if text:
+            try:
+                parsed: Any = json.loads(text)
+                if isinstance(parsed, dict):
+                    data = parsed  # type: ignore[assignment]
+                elif isinstance(parsed, list):
+                    data = {"items": parsed}
+            except json.JSONDecodeError:
+                pass
+
+        return McpToolResult(text=text, data=data)