raise-cli 2.2.1__py3-none-any.whl

raise_cli/hooks/builtin/gate_bridge.py

@@ -0,0 +1,83 @@
+"""Built-in GateBridgeHook — bridges gate system into before: events.
+
+Subscribes to ``before:`` events and runs matching WorkflowGates via
+GateRegistry discovery. Returns ``abort`` if any gate fails, preventing
+the guarded operation from proceeding.
+
+This is the bridge between the independent gate and hook systems (PAT-E-454).
+Gates remain standalone (AD-5) — the bridge is the only coupling point.
+
+Architecture: ADR-039 §5 (Built-in hooks), S248.6
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import ClassVar
+
+from raise_cli.gates.models import GateContext, GateResult
+from raise_cli.gates.registry import GateRegistry
+from raise_cli.hooks.events import HookEvent, HookResult
+
+logger = logging.getLogger(__name__)
+
+
+class GateBridgeHook:
+    """Bridges WorkflowGates into the hook lifecycle.
+
+    Subscribes to ``before:`` events, discovers gates registered for
+    the matching workflow point, runs them all, and returns ``abort``
+    if any gate fails. Priority 100 ensures gates run before other hooks.
+
+    Registered via ``rai.hooks`` entry point in pyproject.toml.
+    """
+
+    events: ClassVar[list[str]] = [
+        "before:release:publish",
+        "before:session:close",
+    ]
+    priority: ClassVar[int] = 100
+
+    def handle(self, event: HookEvent) -> HookResult:
+        """Run matching gates and abort if any fail."""
+        workflow_point = event.event_name
+
+        registry = GateRegistry()
+        registry.discover()
+        gates = registry.get_gates_for_point(workflow_point)
+
+        if not gates:
+            logger.debug("GateBridgeHook: no gates for '%s'", workflow_point)
+            return HookResult(status="ok")
+
+        logger.debug(
+            "GateBridgeHook: running %d gate(s) for '%s'",
+            len(gates),
+            workflow_point,
+        )
+
+        failures: list[GateResult] = []
+        for gate in gates:
+            context = GateContext(gate_id=gate.gate_id)
+            try:
+                result = gate.evaluate(context)
+            except Exception as exc:  # noqa: BLE001
+                result = GateResult(
+                    passed=False,
+                    gate_id=gate.gate_id,
+                    message=f"{type(exc).__name__}: {exc}",
+                )
+
+            if not result.passed:
+                failures.append(result)
+                logger.debug(
+                    "GateBridgeHook: gate '%s' failed: %s",
+                    gate.gate_id,
+                    result.message,
+                )
+
+        if failures:
+            summary = "; ".join(f"{f.gate_id}: {f.message}" for f in failures)
+            return HookResult(status="abort", message=f"Gates failed: {summary}")
+
+        return HookResult(status="ok")

raise_cli/hooks/builtin/jira_sync.py

@@ -0,0 +1,127 @@
+"""Built-in JiraSyncHook — auto-sync work lifecycle events to Jira transitions.
+
+Subscribes to ``work:start`` and ``work:close`` events. Maps lifecycle events
+to Jira transition IDs via ``lifecycle_mapping`` in ``.raise/jira.yaml``.
+
+Graceful degradation:
+- No issue_key on event → skip (debug log)
+- No lifecycle_mapping configured → skip (debug log)
+- No mapping entry for event type → skip (debug log)
+- Adapter unavailable → return error (no crash)
+
+Architecture: E301 S301.6 (Skill Auto-Sync Hooks)
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import ClassVar
+
+import yaml
+
+from raise_cli.hooks.events import HookEvent, HookResult, WorkCloseEvent, WorkStartEvent
+
+logger = logging.getLogger(__name__)
+
+_JIRA_YAML_PATH: Path = Path(".raise/jira.yaml")
+
+
+def _load_lifecycle_mapping() -> dict[str, int] | None:
+    """Read lifecycle_mapping from .raise/jira.yaml.
+
+    Returns None if file missing or section absent.
+    """
+    if not _JIRA_YAML_PATH.exists():
+        return None
+    data = yaml.safe_load(_JIRA_YAML_PATH.read_text())
+    mapping = data.get("workflow", {}).get("lifecycle_mapping")
+    if not mapping:
+        return None
+    return mapping
+
+
+def _resolve_status_name(transition_id: int) -> str:
+    """Reverse-lookup: transition ID → status name from status_mapping.
+
+    Falls back to string of transition_id if not found.
+    """
+    if not _JIRA_YAML_PATH.exists():
+        return str(transition_id)
+    data = yaml.safe_load(_JIRA_YAML_PATH.read_text())
+    status_mapping: dict[str, int] = data.get("workflow", {}).get("status_mapping", {})
+    for name, tid in status_mapping.items():
+        if tid == transition_id:
+            return name
+    return str(transition_id)
+
+
+class JiraSyncHook:
+    """Auto-sync work lifecycle events to Jira transitions.
+
+    Reads ``lifecycle_mapping`` from ``.raise/jira.yaml``::
+
+        workflow:
+          lifecycle_mapping:
+            story_start: 31   # → In Progress
+            story_close: 41   # → Done
+            epic_start: 31
+            epic_close: 41
+
+    Maps ``work:start`` + ``work_type=story`` → ``story_start`` → transition ID 31
+    → adapter.transition_issue(issue_key, "in-progress").
+
+    Registered via ``rai.hooks`` entry point in pyproject.toml.
+    """
+
+    events: ClassVar[list[str]] = ["work:start", "work:close"]
+    priority: ClassVar[int] = -10  # after telemetry (priority 0)
+
+    def handle(self, event: HookEvent) -> HookResult:
+        """Handle work lifecycle events by triggering Jira transitions.
+
+        Never raises — returns HookResult(status="error") on failure.
+        """
+        # 1. Type-narrow to work events
+        if not isinstance(event, (WorkStartEvent, WorkCloseEvent)):
+            return HookResult(status="ok")
+
+        # 2. Skip if no issue key
+        if not event.issue_key:
+            logger.debug("JiraSyncHook: no issue_key, skipping")
+            return HookResult(status="ok")
+
+        # 3. Load lifecycle_mapping
+        mapping = _load_lifecycle_mapping()
+        if not mapping:
+            logger.debug("JiraSyncHook: no lifecycle_mapping configured")
+            return HookResult(status="ok")
+
+        # 4. Resolve mapping key: "{work_type}_{action}"
+        action = "start" if isinstance(event, WorkStartEvent) else "close"
+        mapping_key = f"{event.work_type}_{action}"
+        transition_id = mapping.get(mapping_key)
+        if transition_id is None:
+            logger.debug("JiraSyncHook: no mapping for %s", mapping_key)
+            return HookResult(status="ok")
+
+        # 5. Resolve status name from transition ID
+        status_name = _resolve_status_name(transition_id)
+
+        # 6. Call adapter
+        try:
+            from raise_cli.cli.commands._resolve import resolve_adapter
+
+            adapter = resolve_adapter(None)
+            adapter.transition_issue(event.issue_key, status_name)
+            logger.info(
+                "JiraSyncHook: %s → %s (%s)",
+                event.issue_key,
+                status_name,
+                mapping_key,
+            )
+            return HookResult(status="ok")
+        except Exception as exc:  # noqa: BLE001
+            msg = f"JiraSyncHook: {type(exc).__name__}: {exc}"
+            logger.warning(msg)
+            return HookResult(status="error", message=msg)

raise_cli/hooks/builtin/memory.py

@@ -0,0 +1,117 @@
+"""Built-in MemoryMdSyncHook — regenerates MEMORY.md after graph build.
+
+Subscribes to ``graph:build`` and writes MEMORY.md to both the canonical
+location (``.raise/rai/memory/MEMORY.md``) and the Claude Code copy
+(``~/.claude/projects/{encoded}/memory/MEMORY.md``).
+
+Error isolation: ``handle()`` never raises. Failures are logged and
+returned as ``HookResult(status="error")``.
+
+Architecture: S350.3 (MEMORY.md sync hook)
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import ClassVar
+
+from raise_cli.config.paths import (
+    get_claude_memory_path,
+    get_framework_dir,
+    get_memory_dir,
+)
+from raise_cli.hooks.events import GraphBuildEvent, HookEvent, HookResult
+from raise_cli.onboarding.memory_md import generate_memory_md
+
+logger = logging.getLogger(__name__)
+
+
+class MemoryMdSyncHook:
+    """Regenerate MEMORY.md after graph build.
+
+    Writes to:
+    1. Canonical: ``.raise/rai/memory/MEMORY.md``
+    2. Claude Code: ``~/.claude/projects/{hash}/memory/MEMORY.md``
+
+    Reads project name and development branch from manifest.yaml.
+    Falls back to sensible defaults if manifest is unavailable.
+
+    Registered via ``rai.hooks`` entry point in pyproject.toml.
+    """
+
+    events: ClassVar[list[str]] = ["graph:build"]
+    priority: ClassVar[int] = 0
+
+    def handle(self, event: HookEvent) -> HookResult:
+        """Generate MEMORY.md and write to canonical + Claude Code paths.
+
+        Never raises — returns ``HookResult(status="error")`` on failure.
+        """
+        try:
+            return self._do_handle(event)
+        except Exception as exc:  # noqa: BLE001
+            msg = f"{type(exc).__name__}: {exc}"
+            logger.warning("MemoryMdSyncHook failed: %s", msg)
+            return HookResult(status="error", message=msg)
+
+    def _do_handle(self, event: HookEvent) -> HookResult:
+        """Internal handler — may raise, caller catches."""
+        assert isinstance(event, (HookEvent, GraphBuildEvent))
+
+        project_path = getattr(event, "project_path", None)
+        if project_path is None:
+            return HookResult(status="error", message="No project_path in event")
+
+        project_path = project_path.resolve()
+
+        # Load manifest for project name and development branch
+        project_name, dev_branch = self._load_project_info(project_path)
+
+        # Generate content
+        methodology_path = get_framework_dir(project_path) / "methodology.yaml"
+        patterns_path = get_memory_dir(project_path) / "patterns.jsonl"
+
+        content = generate_memory_md(
+            methodology_path=methodology_path,
+            patterns_path=patterns_path,
+            project_name=project_name,
+            development_branch=dev_branch,
+        )
+
+        # Write canonical copy
+        canonical = get_memory_dir(project_path) / "MEMORY.md"
+        canonical.parent.mkdir(parents=True, exist_ok=True)
+        canonical.write_text(content, encoding="utf-8")
+        logger.debug("MemoryMdSyncHook wrote canonical MEMORY.md: %s", canonical)
+
+        # Write Claude Code copy
+        claude_memory = get_claude_memory_path(project_path)
+        claude_memory.parent.mkdir(parents=True, exist_ok=True)
+        claude_memory.write_text(content, encoding="utf-8")
+        logger.debug("MemoryMdSyncHook wrote Claude Code MEMORY.md: %s", claude_memory)
+
+        return HookResult(status="ok")
+
+    @staticmethod
+    def _load_project_info(project_path: Path) -> tuple[str, str]:
+        """Load project name and development branch from manifest.
+
+        Returns:
+            Tuple of (project_name, development_branch) with defaults.
+        """
+
+        project_name = "project"
+        dev_branch = "main"
+
+        try:
+            from raise_cli.onboarding.manifest import load_manifest
+
+            manifest = load_manifest(Path(str(project_path)))
+            if manifest is not None:
+                project_name = manifest.project.name
+                dev_branch = manifest.branches.development
+        except Exception:  # noqa: BLE001
+            logger.debug("Could not load manifest, using defaults")
+
+        return project_name, dev_branch

raise_cli/hooks/builtin/telemetry.py

@@ -0,0 +1,72 @@
+"""Built-in TelemetryHook — writes CommandUsage signals for lifecycle events.
+
+First real LifecycleHook implementation. Subscribes to all 9 after-events
+and maps each to a ``CommandUsage`` telemetry signal via ``emit_command_usage()``.
+
+Error isolation: ``handle()`` never raises. Emit failures are logged and
+returned as ``HookResult(status="error")``.
+
+Architecture: ADR-039 §5 (Built-in hooks), S248.3
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import ClassVar
+
+from raise_cli.hooks.events import HookEvent, HookResult
+from raise_cli.telemetry.writer import emit_command_usage
+
+logger = logging.getLogger(__name__)
+
+
+class TelemetryHook:
+    """Writes CommandUsage signals for CLI lifecycle events.
+
+    Maps event names to command/subcommand pairs::
+
+        "session:start"  → command="session", subcommand="start"
+        "graph:build"    → command="graph",   subcommand="build"
+
+    Registered via ``rai.hooks`` entry point in pyproject.toml.
+    """
+
+    events: ClassVar[list[str]] = [
+        "session:start",
+        "session:close",
+        "graph:build",
+        "pattern:added",
+        "discover:scan",
+        "init:complete",
+        "adapter:loaded",
+        "adapter:failed",
+        "release:publish",
+    ]
+    priority: ClassVar[int] = 0
+
+    def handle(self, event: HookEvent) -> HookResult:
+        """Map event to CommandUsage signal and emit.
+
+        Never raises — returns ``HookResult(status="error")`` on failure.
+        """
+        command, subcommand = event.event_name.split(":", 1)
+
+        try:
+            result = emit_command_usage(command, subcommand)
+        except Exception as exc:  # noqa: BLE001
+            msg = f"{type(exc).__name__}: {exc}"
+            logger.warning(
+                "TelemetryHook emit failed for '%s': %s", event.event_name, msg
+            )
+            return HookResult(status="error", message=msg)
+
+        if not result.success:
+            logger.warning(
+                "TelemetryHook emit failed for '%s': %s",
+                event.event_name,
+                result.error,
+            )
+            return HookResult(status="error", message=result.error or "unknown error")
+
+        logger.debug("TelemetryHook emitted CommandUsage for '%s'", event.event_name)
+        return HookResult(status="ok")

raise_cli/hooks/emitter.py

@@ -0,0 +1,184 @@
+"""Event emitter for lifecycle hooks.
+
+Dispatches typed events to registered handlers with error isolation.
+Handlers that raise exceptions are logged and skipped — the CLI never
+crashes from a handler failure.
+
+When a ``HookRegistry`` is provided, discovered hooks are auto-registered
+and dispatched in priority order with per-hook timeout enforcement.
+
+Architecture: ADR-039 §4 (Synchronous execution with error isolation)
+"""
+
+from __future__ import annotations
+
+import logging
+from collections import defaultdict
+from collections.abc import Callable
+from concurrent.futures import ThreadPoolExecutor
+from concurrent.futures import TimeoutError as FuturesTimeoutError
+from typing import TYPE_CHECKING
+
+from raise_cli.hooks.events import EmitResult, HookEvent, HookResult
+from raise_cli.hooks.protocol import LifecycleHook
+
+if TYPE_CHECKING:
+    from raise_cli.hooks.registry import HookRegistry
+
+logger = logging.getLogger(__name__)
+
+HandlerFn = Callable[[HookEvent], HookResult]
+
+
+class EventEmitter:
+    """Dispatches lifecycle events to registered handlers.
+
+    Handlers are called in registration order per event name.
+    For ``before:`` events, if any handler returns ``abort``, the emit
+    result signals that the operation should be aborted.
+
+    When ``registry`` is provided, discovered hooks are auto-registered
+    and dispatched in priority order with per-hook timeout.
+
+    Example::
+
+        emitter = EventEmitter()
+        emitter.register("session:start", my_handler)
+        result = emitter.emit(SessionStartEvent(session_id="SES-1"))
+
+    With registry::
+
+        registry = HookRegistry()
+        registry.discover()
+        emitter = EventEmitter(registry=registry)
+        result = emitter.emit(SessionStartEvent(session_id="SES-1"))
+    """
+
+    DEFAULT_TIMEOUT: float = 5.0
+
+    def __init__(self, registry: HookRegistry | None = None) -> None:
+        self._handlers: dict[str, list[HandlerFn]] = defaultdict(list)
+        self._registry = registry
+
+    def register(self, event_name: str, handler: HandlerFn) -> None:
+        """Register a handler for a specific event name."""
+        self._handlers[event_name].append(handler)
+
+    def emit(self, event: HookEvent) -> EmitResult:
+        """Dispatch event to all registered handlers.
+
+        For ``before:`` events, if any handler returns ``abort``,
+        returns ``EmitResult(aborted=True)``. Remaining handlers
+        are still called (all-notify semantics).
+
+        Handler exceptions and timeouts are caught, logged, and
+        reported in ``EmitResult.handler_errors``.
+        """
+        errors: list[str] = []
+        aborted = False
+        abort_message = ""
+
+        # Phase 1: Registry hooks (priority-sorted, with timeout)
+        if self._registry is not None:
+            hooks = self._registry.get_hooks_for_event(event.event_name)
+            for hook in hooks:
+                result = self._call_hook_with_timeout(hook, event, errors)
+                if result is not None:
+                    aborted, abort_message = self._check_abort(
+                        result, event.event_name, aborted, abort_message
+                    )
+
+        # Phase 2: Manual handlers (registration order, no timeout)
+        handlers = self._handlers.get(event.event_name, [])
+        for handler in handlers:
+            try:
+                result = handler(event)
+            except Exception as exc:  # noqa: BLE001
+                error_msg = f"{type(exc).__name__}: {exc}"
+                errors.append(error_msg)
+                logger.warning(
+                    "Hook handler %s raised %s for event '%s'",
+                    getattr(handler, "__name__", repr(handler)),
+                    error_msg,
+                    event.event_name,
+                )
+                continue
+
+            aborted, abort_message = self._check_abort(
+                result, event.event_name, aborted, abort_message
+            )
+
+        return EmitResult(
+            aborted=aborted,
+            abort_message=abort_message,
+            handler_errors=tuple(errors),
+        )
+
+    def _call_hook_with_timeout(
+        self,
+        hook: LifecycleHook,
+        event: HookEvent,
+        errors: list[str],
+    ) -> HookResult | None:
+        """Call a hook's handle() with timeout enforcement.
+
+        Returns the HookResult on success, or None on error/timeout.
+        """
+        timeout: float = getattr(hook, "timeout", self.DEFAULT_TIMEOUT)
+        hook_name = type(hook).__name__
+
+        executor = ThreadPoolExecutor(max_workers=1)
+        try:
+            future = executor.submit(hook.handle, event)
+            return future.result(timeout=timeout)
+        except FuturesTimeoutError:
+            error_msg = f"TimeoutError: {hook_name} exceeded {timeout}s timeout"
+            errors.append(error_msg)
+            logger.warning(
+                "Hook %s timed out after %ss for event '%s'",
+                hook_name,
+                timeout,
+                event.event_name,
+            )
+            return None
+        except Exception as exc:  # noqa: BLE001
+            error_msg = f"{type(exc).__name__}: {exc}"
+            errors.append(error_msg)
+            logger.warning(
+                "Hook %s raised %s for event '%s'",
+                hook_name,
+                error_msg,
+                event.event_name,
+            )
+            return None
+        finally:
+            executor.shutdown(wait=False, cancel_futures=True)
+
+    @staticmethod
+    def _check_abort(
+        result: HookResult,
+        event_name: str,
+        aborted: bool,
+        abort_message: str,
+    ) -> tuple[bool, str]:
+        """Check if a handler result triggers abort (before: events only)."""
+        if (
+            result.status == "abort"
+            and event_name.startswith("before:")
+            and not aborted
+        ):
+            return True, result.message
+        return aborted, abort_message
+
+
+def create_emitter() -> EventEmitter:
+    """Create an EventEmitter with a discovered HookRegistry.
+
+    Convenience factory that avoids repeating registry setup in every
+    CLI command. Discovers hooks from ``rai.hooks`` entry points.
+    """
+    from raise_cli.hooks.registry import HookRegistry
+
+    registry = HookRegistry()
+    registry.discover()
+    return EventEmitter(registry=registry)