raise-cli 2.2.1__py3-none-any.whl

raise_cli/graph/backends/__init__.py

@@ -0,0 +1,57 @@
+"""Graph backend implementations — CLI layer with env-var-based selection.
+
+The factory `get_active_backend()` checks RAI_SERVER_URL + RAI_API_KEY
+and returns DualWriteBackend when both are set, else FilesystemGraphBackend.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+
+from raise_core.graph.backends.filesystem import FilesystemGraphBackend
+from raise_core.graph.backends.protocol import KnowledgeGraphBackend
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["get_active_backend"]
+
+
+def get_active_backend(path: Path) -> KnowledgeGraphBackend:
+    """Resolve the active graph backend based on environment.
+
+    Returns DualWriteBackend when RAI_SERVER_URL and RAI_API_KEY are both
+    set. Falls back to FilesystemGraphBackend otherwise.
+
+    Args:
+        path: Path to the graph JSON file (for local backend).
+    """
+    server_url = os.environ.get("RAI_SERVER_URL", "").strip()
+    api_key = os.environ.get("RAI_API_KEY", "").strip()
+
+    if server_url and api_key:
+        from raise_cli.graph.backends.api import ApiGraphBackend
+        from raise_cli.graph.backends.dual import DualWriteBackend
+
+        project_id = Path.cwd().name
+        raise_dir = Path.cwd() / ".raise"
+        local = FilesystemGraphBackend(path=path)
+        remote = ApiGraphBackend(
+            server_url=server_url,
+            api_key=api_key,
+            project_id=project_id,
+        )
+        return DualWriteBackend(
+            local=local,
+            remote=remote,
+            raise_dir=raise_dir if raise_dir.exists() else None,
+        )
+
+    if server_url and not api_key:
+        logger.warning(
+            "RAI_SERVER_URL is set but RAI_API_KEY is missing. "
+            "Using local filesystem backend only."
+        )
+
+    return FilesystemGraphBackend(path=path)

raise_cli/graph/backends/api.py

@@ -0,0 +1,137 @@
+"""API-based graph backend — sends graph data to rai-server via HTTP.
+
+PRO backend. Requires RAI_SERVER_URL and RAI_API_KEY.
+Implements KnowledgeGraphBackend protocol from raise-core (ADR-036).
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+try:
+    import httpx
+except ModuleNotFoundError as exc:
+    raise ModuleNotFoundError(
+        "httpx is required for the API graph backend. "
+        "Install with: pip install 'raise-cli[dev]'"
+    ) from exc
+
+from raise_core.graph.backends.models import BackendHealth
+from raise_core.graph.engine import Graph
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["ApiGraphBackend"]
+
+
+class ApiGraphBackend:
+    """HTTP client backend — persists graph to rai-server.
+
+    Args:
+        server_url: Base URL of the rai-server (e.g. "http://localhost:8000").
+        api_key: API key for authentication (rsk_ prefix).
+        project_id: Project identifier for graph sync.
+    """
+
+    def __init__(self, server_url: str, api_key: str, project_id: str) -> None:
+        self.server_url = server_url
+        self.api_key = api_key
+        self.project_id = project_id
+        self._client = httpx.Client(
+            base_url=server_url,
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=httpx.Timeout(connect=5.0, read=30.0, write=30.0, pool=5.0),
+        )
+
+    def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        self._client.close()
+
+    def persist(self, graph: Graph) -> None:
+        """Send graph to server via POST /api/v1/graph/sync.
+
+        Serializes all nodes and edges from the Graph into the server's
+        expected sync payload format.
+
+        Args:
+            graph: The graph to persist.
+        """
+        skipped = 0
+        nodes: list[dict[str, Any]] = []
+        for node in graph.iter_concepts():
+            if not node.content:
+                skipped += 1
+                continue
+            nodes.append(
+                {
+                    "node_id": node.id,
+                    "node_type": node.type,
+                    "scope": "project",
+                    "content": node.content,
+                    "source_file": node.source_file,
+                    "properties": node.metadata,
+                }
+            )
+        if skipped:
+            logger.info("Skipped %d nodes with empty content", skipped)
+        edges: list[dict[str, Any]] = [
+            {
+                "source_node_id": edge.source,
+                "target_node_id": edge.target,
+                "edge_type": edge.type,
+                "weight": edge.weight,
+                "properties": edge.metadata,
+            }
+            for edge in graph.iter_relationships()
+        ]
+        payload: dict[str, Any] = {
+            "project_id": self.project_id,
+            "nodes": nodes,
+            "edges": edges,
+        }
+        response = self._client.post(url="/api/v1/graph/sync", json=payload)
+        response.raise_for_status()
+        logger.info(
+            "Synced to remote server (%d nodes, %d edges)",
+            len(nodes),
+            len(edges),
+        )
+
+    def load(self) -> Graph:
+        """Not supported — DualWriteBackend reads from local.
+
+        Raises:
+            NotImplementedError: Always. Use DualWriteBackend for load,
+                which delegates to local FilesystemGraphBackend.
+        """
+        raise NotImplementedError(
+            "ApiGraphBackend.load() is not supported. "
+            "Use DualWriteBackend, which loads from local filesystem."
+        )
+
+    def health(self) -> BackendHealth:
+        """Check server availability via GET /health.
+
+        Returns:
+            BackendHealth with status healthy or unavailable.
+        """
+        try:
+            response = self._client.get(url="/health")
+            if response.status_code == 200:
+                return BackendHealth(
+                    status="healthy",
+                    message="API server operational",
+                    metadata={"backend": "api", "server_url": self.server_url},
+                )
+            return BackendHealth(
+                status="degraded",
+                message=f"Server returned {response.status_code}",
+                metadata={"backend": "api", "server_url": self.server_url},
+            )
+        except httpx.HTTPError as e:
+            return BackendHealth(
+                status="unavailable",
+                message=f"Connection failed: {e}",
+                metadata={"backend": "api", "server_url": self.server_url},
+            )

raise_cli/graph/backends/dual.py

@@ -0,0 +1,139 @@
+"""Dual-write graph backend — local + remote with best-effort sync.
+
+Writes to both FilesystemGraphBackend (local, always succeeds) and
+ApiGraphBackend (remote, best-effort). Loads from local only.
+
+Architecture: ADR-036 (KnowledgeGraphBackend)
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import UTC, datetime
+from pathlib import Path
+
+from raise_core.graph.backends.models import BackendHealth
+from raise_core.graph.backends.protocol import KnowledgeGraphBackend
+from raise_core.graph.engine import Graph
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["DualWriteBackend"]
+
+
+class DualWriteBackend:
+    """Dual-write backend — local always, remote best-effort.
+
+    Local is source of truth. Remote failures are logged as warnings,
+    never raised as exceptions. When raise_dir is provided, a pending_sync
+    marker is created on remote failure and cleared on success.
+
+    Args:
+        local: Local backend (FilesystemGraphBackend).
+        remote: Remote backend (ApiGraphBackend).
+        raise_dir: Path to .raise/ directory for pending_sync marker.
+            If None, marker behavior is skipped.
+    """
+
+    def __init__(
+        self,
+        local: KnowledgeGraphBackend,
+        remote: KnowledgeGraphBackend,
+        raise_dir: Path | None = None,
+    ) -> None:
+        self.local = local
+        self.remote = remote
+        self._raise_dir = raise_dir
+
+    def persist(self, graph: Graph) -> None:
+        """Persist to local first, then sync to remote (best-effort).
+
+        Local failure raises (critical). Remote failure logs warning
+        and creates a pending_sync marker if raise_dir is configured.
+
+        Args:
+            graph: The graph to persist.
+        """
+        self.local.persist(graph)
+        try:
+            self.remote.persist(graph)
+        except Exception as e:
+            detail = ""
+            try:
+                import httpx
+
+                if isinstance(e, httpx.HTTPStatusError):
+                    detail = f" Response: {e.response.text[:200]}"
+            except ImportError:
+                pass
+            logger.warning(
+                "Remote sync failed: %s.%s Graph saved locally only.", e, detail
+            )
+            self._write_marker(graph, str(e))
+            return
+
+        # Remote succeeded — clear any pending marker
+        self._clear_marker()
+
+    def _write_marker(self, graph: Graph, error: str) -> None:
+        """Create pending_sync marker on remote failure."""
+        if self._raise_dir is None:
+            return
+        from raise_cli.graph.backends.pending import (
+            PendingSyncMarker,
+            write_pending_marker,
+        )
+
+        marker = PendingSyncMarker(
+            timestamp=datetime.now(tz=UTC),
+            graph_path=str(getattr(self.local, "path", "unknown")),
+            node_count=graph.node_count,
+            edge_count=graph.edge_count,
+            error=error,
+        )
+        write_pending_marker(self._raise_dir, marker)
+
+    def _clear_marker(self) -> None:
+        """Clear pending_sync marker on remote success."""
+        if self._raise_dir is None:
+            return
+        from raise_cli.graph.backends.pending import clear_pending_marker
+
+        clear_pending_marker(self._raise_dir)
+
+    def load(self) -> Graph:
+        """Load from local backend (source of truth).
+
+        Returns:
+            Graph loaded from local filesystem.
+        """
+        return self.local.load()
+
+    def health(self) -> BackendHealth:
+        """Aggregate health from both backends.
+
+        Returns:
+            BackendHealth with combined status:
+            - healthy: both healthy
+            - degraded: local healthy, remote not
+            - unavailable: local not healthy
+        """
+        local_health = self.local.health()
+        remote_health = self.remote.health()
+
+        if local_health.status != "healthy":
+            status = "unavailable"
+        elif remote_health.status != "healthy":
+            status = "degraded"
+        else:
+            status = "healthy"
+
+        return BackendHealth(
+            status=status,
+            message=f"local: {local_health.status}, remote: {remote_health.status}",
+            metadata={
+                "backend": "dual",
+                "local": local_health.status,
+                "remote": remote_health.status,
+            },
+        )

raise_cli/graph/backends/pending.py

@@ -0,0 +1,84 @@
+"""Pending sync marker — tracks failed remote writes for retry.
+
+When DualWriteBackend fails to sync remotely, a marker file is created
+in .raise/pending_sync.json. On next successful sync, the marker is cleared.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from datetime import datetime
+from pathlib import Path
+
+from pydantic import BaseModel
+
+logger = logging.getLogger(__name__)
+
+__all__ = [
+    "PendingSyncMarker",
+    "write_pending_marker",
+    "read_pending_marker",
+    "clear_pending_marker",
+]
+
+MARKER_FILENAME = "pending_sync.json"
+
+
+class PendingSyncMarker(BaseModel):
+    """Marker for a failed remote graph sync."""
+
+    timestamp: datetime
+    graph_path: str
+    node_count: int
+    edge_count: int
+    error: str
+
+
+def write_pending_marker(raise_dir: Path, marker: PendingSyncMarker) -> None:
+    """Write pending_sync.json to .raise/ directory.
+
+    Args:
+        raise_dir: Path to .raise/ directory.
+        marker: The marker data to write.
+    """
+    path = raise_dir / MARKER_FILENAME
+    path.write_text(marker.model_dump_json(indent=2))
+    logger.warning("Remote sync failed, marked as pending: %s", path)
+
+
+def read_pending_marker(raise_dir: Path) -> PendingSyncMarker | None:
+    """Read pending_sync.json, return None if not present or corrupt.
+
+    Args:
+        raise_dir: Path to .raise/ directory.
+
+    Returns:
+        PendingSyncMarker if file exists and is valid, None otherwise.
+    """
+    path = raise_dir / MARKER_FILENAME
+    if not path.exists():
+        return None
+    try:
+        data = json.loads(path.read_text())
+        return PendingSyncMarker.model_validate(data)
+    except (json.JSONDecodeError, ValueError):
+        logger.warning("Corrupt pending_sync marker at %s, ignoring", path)
+        return None
+
+
+def clear_pending_marker(raise_dir: Path) -> bool:
+    """Delete pending_sync.json.
+
+    Args:
+        raise_dir: Path to .raise/ directory.
+
+    Returns:
+        True if file existed and was deleted, False otherwise.
+    """
+    path = raise_dir / MARKER_FILENAME
+    if path.exists():
+        path.unlink()
+        logger.info("Cleared pending sync marker — remote sync successful")
+        return True
+    return False

raise_cli/handlers/__init__.py

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

raise_cli/hooks/__init__.py

@@ -0,0 +1,54 @@
+"""Lifecycle hooks infrastructure for raise-cli.
+
+Provides typed event infrastructure for cross-cutting concerns (telemetry,
+notifications, compliance) to react to CLI operations without coupling
+to skill content.
+
+Architecture: ADR-039 (Lifecycle Hooks & Workflow Gates)
+"""
+
+from raise_cli.hooks.emitter import EventEmitter, create_emitter
+from raise_cli.hooks.events import (
+    AdapterFailedEvent,
+    AdapterLoadedEvent,
+    BeforeReleasePublishEvent,
+    BeforeSessionCloseEvent,
+    DiscoverScanEvent,
+    EmitResult,
+    GraphBuildEvent,
+    HookEvent,
+    HookResult,
+    InitCompleteEvent,
+    PatternAddedEvent,
+    ReleasePublishEvent,
+    SessionCloseEvent,
+    SessionStartEvent,
+)
+from raise_cli.hooks.protocol import LifecycleHook
+from raise_cli.hooks.registry import HookRegistry
+
+__all__ = [
+    # Base types
+    "HookEvent",
+    "HookResult",
+    "EmitResult",
+    # Protocol + Registry
+    "LifecycleHook",
+    "HookRegistry",
+    # Emitter
+    "EventEmitter",
+    "create_emitter",
+    # After-events (9)
+    "SessionStartEvent",
+    "SessionCloseEvent",
+    "GraphBuildEvent",
+    "PatternAddedEvent",
+    "DiscoverScanEvent",
+    "InitCompleteEvent",
+    "AdapterLoadedEvent",
+    "AdapterFailedEvent",
+    "ReleasePublishEvent",
+    # Before-events (2)
+    "BeforeSessionCloseEvent",
+    "BeforeReleasePublishEvent",
+]

raise_cli/hooks/builtin/__init__.py

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

raise_cli/hooks/builtin/backlog.py

@@ -0,0 +1,216 @@
+"""Built-in BacklogHook — syncs backlog state on work lifecycle events.
+
+Listens to ``work:lifecycle`` events (fired by ``rai signal emit-work``)
+and calls the resolved ProjectManagementAdapter to create/transition issues.
+
+Error isolation: ``handle()`` never raises. Adapter or config failures are
+logged and returned as ``HookResult(status="error")``.
+
+Architecture: ADR-039 §5 (Built-in hooks), S325.4, S347.4
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, ClassVar
+
+if TYPE_CHECKING:
+    from raise_cli.adapters.protocols import ProjectManagementAdapter
+
+import yaml
+
+from raise_cli.adapters.models import IssueSpec
+from raise_cli.hooks.events import HookEvent, HookResult, WorkLifecycleEvent
+
+logger = logging.getLogger(__name__)
+
+# Events that trigger backlog actions
+_ACTIONABLE_EVENTS = frozenset({"start", "complete"})
+
+# Map (work_type, event) → lifecycle_mapping key
+_LIFECYCLE_KEY_MAP: dict[tuple[str, str], str] = {
+    ("story", "start"): "story_start",
+    ("story", "complete"): "story_close",
+    ("epic", "start"): "epic_start",
+    ("epic", "complete"): "epic_close",
+}
+
+# Map lifecycle_mapping key → target status for rai backlog transition
+_STATUS_MAP: dict[str, str] = {
+    "story_start": "in-progress",
+    "story_close": "done",
+    "epic_start": "in-progress",
+    "epic_close": "done",
+}
+
+
+class _JiraConfig:
+    """Parsed jira.yaml config relevant to BacklogHook."""
+
+    __slots__ = ("project_key", "lifecycle_mapping")
+
+    def __init__(self, project_key: str, lifecycle_mapping: dict[str, int]) -> None:
+        self.project_key = project_key
+        self.lifecycle_mapping = lifecycle_mapping
+
+
+def _load_jira_config(project_root: Path) -> _JiraConfig | None:
+    """Load project key and lifecycle_mapping from .raise/jira.yaml.
+
+    Returns None if file missing, unparseable, or missing required sections.
+    """
+    config_path = project_root / ".raise" / "jira.yaml"
+    if not config_path.exists():
+        return None
+    try:
+        with open(config_path) as f:
+            data: dict[str, Any] = yaml.safe_load(f)
+        workflow = data.get("workflow", {})
+        mapping: dict[str, int] | None = workflow.get("lifecycle_mapping")
+        if mapping is None:
+            return None
+        projects = data.get("projects", {})
+        project_key = next(iter(projects), None) if projects else None
+        if project_key is None:
+            return None
+        return _JiraConfig(project_key=project_key, lifecycle_mapping=mapping)
+    except Exception:  # noqa: BLE001
+        logger.warning("Failed to parse .raise/jira.yaml")
+        return None
+
+
+def _resolve_issue_key(
+    adapter: ProjectManagementAdapter, work_id: str, project_key: str
+) -> str | None:
+    """Search for a backlog issue by work_id.
+
+    Strategy depends on adapter type:
+    - FilesystemPMAdapter: direct key lookup (no JQL)
+    - Jira/MCP: label-first (``rai:{work_id}``), then summary fallback
+
+    Returns the issue key if found, None otherwise.
+    """
+    # Import inside function to avoid circular imports
+    from raise_cli.adapters.filesystem import FilesystemPMAdapter
+
+    if isinstance(adapter, FilesystemPMAdapter):
+        # FileAdapter: direct key lookup, no JQL
+        results = adapter.search(work_id, limit=1)
+        return results[0].key if results else None
+
+    # Jira/MCP: label-first search
+    label_query = f'project = "{project_key}" AND labels = "rai:{work_id}"'
+    results = adapter.search(label_query, limit=1)
+    if results:
+        return results[0].key
+
+    # Summary fallback with warning
+    logger.warning("No label match for %s — falling back to summary search", work_id)
+    summary_query = f'project = "{project_key}" AND summary ~ "{work_id}"'
+    results = adapter.search(summary_query, limit=1)
+    if results:
+        return results[0].key
+    return None
+
+
+def resolve_adapter() -> ProjectManagementAdapter:
+    """Resolve ProjectManagementAdapter via manifest default. Separated for testability."""
+    from raise_cli.cli.commands._resolve import (
+        resolve_adapter as _resolve,
+    )
+
+    return _resolve(None)
+
+
+class BacklogHook:
+    """Syncs backlog state on work lifecycle events.
+
+    Subscribes to ``work:lifecycle`` events and maps them to
+    ``rai backlog`` actions using ``.raise/jira.yaml`` lifecycle_mapping.
+
+    Registered via ``rai.hooks`` entry point in pyproject.toml.
+    """
+
+    events: ClassVar[list[str]] = ["work:lifecycle"]
+    priority: ClassVar[int] = 0
+    timeout: ClassVar[float] = 30.0  # MCP bridge cold start needs >5s
+
+    def __init__(self, project_root: Path | None = None) -> None:
+        self._project_root = project_root or Path(".")
+
+    def handle(self, event: HookEvent) -> HookResult:
+        """Handle a work lifecycle event by syncing Jira.
+
+        Never raises — returns HookResult with status and message.
+        """
+        if not isinstance(event, WorkLifecycleEvent):
+            return HookResult(status="ok")
+
+        # Only act on start/complete
+        if event.event not in _ACTIONABLE_EVENTS:
+            return HookResult(status="ok")
+
+        # Load jira config
+        config = _load_jira_config(self._project_root)
+        if config is None:
+            return HookResult(
+                status="error", message="no jira.yaml or lifecycle_mapping"
+            )
+
+        # Determine lifecycle key
+        lifecycle_key = _LIFECYCLE_KEY_MAP.get((event.work_type, event.event))
+        if lifecycle_key is None:
+            return HookResult(status="ok")
+
+        # Resolve adapter
+        try:
+            adapter = resolve_adapter()
+        except Exception as exc:  # noqa: BLE001
+            return HookResult(status="error", message=f"adapter unavailable: {exc}")
+
+        # Resolve Jira key
+        try:
+            jira_key = _resolve_issue_key(adapter, event.work_id, config.project_key)
+        except Exception as exc:  # noqa: BLE001
+            return HookResult(status="error", message=f"search failed: {exc}")
+
+        target_status = _STATUS_MAP[lifecycle_key]
+
+        # Handle start: create if missing, then transition
+        if event.event == "start":
+            if jira_key is None:
+                try:
+                    issue_type = "Epic" if event.work_type == "epic" else "Story"
+                    spec = IssueSpec(
+                        summary=f"{event.work_id}",
+                        issue_type=issue_type,
+                        labels=[f"rai:{event.work_id}"],
+                    )
+                    ref = adapter.create_issue(config.project_key, spec)
+                    jira_key = ref.key
+                except Exception as exc:  # noqa: BLE001
+                    return HookResult(status="error", message=f"create failed: {exc}")
+
+            try:
+                adapter.transition_issue(jira_key, target_status)
+            except Exception as exc:  # noqa: BLE001
+                return HookResult(status="error", message=f"transition failed: {exc}")
+
+            return HookResult(status="ok")
+
+        # Handle complete: transition existing issue
+        if event.event == "complete":
+            if jira_key is None:
+                return HookResult(
+                    status="error", message=f"no Jira issue found for {event.work_id}"
+                )
+
+            try:
+                adapter.transition_issue(jira_key, target_status)
+            except Exception as exc:  # noqa: BLE001
+                return HookResult(status="error", message=f"transition failed: {exc}")
+
+            return HookResult(status="ok")
+
+        return HookResult(status="ok")