forgeoptimizer 0.1.0__py3-none-any.whl

forgecli/sdk/events.py

@@ -0,0 +1,206 @@
+"""Plugin event bus + hook manager.
+
+The SDK exposes:
+
+* :class:`PluginEventBus` — a tiny pub/sub bus for plugin
+  lifecycle and runtime events. Distinct from the engine's
+  :class:`~forgecli.engine.events.EventBus` (which is for the
+  eight-stage pipeline). The two are independent so plugins can
+  listen to the engine *and* the plugin lifecycle without coupling.
+* :class:`PluginHook` and :class:`HookManager` — synchronous
+  before/after hooks the SDK fires when a plugin is installed,
+  enabled, disabled, updated, or uninstalled.
+
+Plugins subscribe at enable-time; the SDK guarantees that the
+event handlers are called for every registered subscriber, even
+if one raises (failures are logged and isolated).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from enum import Enum
+from typing import Any
+
+_logger = logging.getLogger("forgecli.sdk.events")
+
+
+# ---------------------------------------------------------------------------
+# Event types
+# ---------------------------------------------------------------------------
+
+
+class PluginEventKind(str, Enum):
+    """The high-level events plugins can listen to."""
+
+    INSTALLED = "installed"
+    ENABLED = "enabled"
+    DISABLED = "disabled"
+    UNINSTALLED = "uninstalled"
+    UPDATED = "updated"
+    BEFORE_COMMAND = "before_command"
+    AFTER_COMMAND = "after_command"
+    CONFIG_CHANGED = "config_changed"
+    ERROR = "error"
+
+
+@dataclass(frozen=True)
+class PluginEvent:
+    """A single lifecycle / runtime event."""
+
+    kind: PluginEventKind
+    plugin_name: str | None = None
+    payload: dict[str, Any] = field(default_factory=dict)
+    timestamp: datetime = field(default_factory=lambda: datetime.now(UTC))
+
+
+EventHandler = Callable[[PluginEvent], "None | Awaitable[None]"]
+
+
+# ---------------------------------------------------------------------------
+# Event bus
+# ---------------------------------------------------------------------------
+
+
+class PluginEventBus:
+    """In-process pub/sub bus for plugin events.
+
+    Async-aware: subscribers may be sync or async. The bus
+    serialises fan-out for synchronous subscribers and schedules
+    coroutines for async ones.
+    """
+
+    def __init__(self) -> None:
+        self._subscribers: dict[PluginEventKind, list[EventHandler]] = {}
+
+    def subscribe(self, kind: PluginEventKind, handler: EventHandler) -> None:
+        self._subscribers.setdefault(kind, []).append(handler)
+
+    def unsubscribe(self, kind: PluginEventKind, handler: EventHandler) -> None:
+        bucket = self._subscribers.get(kind)
+        if not bucket:
+            return
+        with _suppress(ValueError):
+            bucket.remove(handler)
+
+    def publish(self, event: PluginEvent) -> None:
+        """Publish synchronously. Async handlers are scheduled."""
+        for handler in list(self._subscribers.get(event.kind, ())):
+            try:
+                result = handler(event)
+            except Exception:
+                _logger.exception("plugin event handler raised")
+                continue
+            if asyncio.iscoroutine(result):
+                try:
+                    loop = asyncio.get_running_loop()
+                    task = loop.create_task(result)
+                    task.add_done_callback(_discard_task)
+                except RuntimeError:
+                    pass
+
+    async def publish_and_drain(self, event: PluginEvent) -> None:
+        """Publish and await any async handler results."""
+        for handler in list(self._subscribers.get(event.kind, ())):
+            try:
+                result = handler(event)
+            except Exception:
+                _logger.exception("plugin event handler raised")
+                continue
+            if asyncio.iscoroutine(result):
+                await result
+
+
+# ---------------------------------------------------------------------------
+# Hook manager
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class PluginHook:
+    """A single registered hook.
+
+    ``callback`` may be sync or async. The SDK wraps it in
+    :func:`asyncio.iscoroutine` before calling so plugins can
+    return a coroutine for async work.
+    """
+
+    name: str
+    callback: Callable[..., Any]
+
+
+class HookManager:
+    """Synchronous registry of before/after hooks."""
+
+    def __init__(self) -> None:
+        self._before: list[PluginHook] = []
+        self._after: list[PluginHook] = []
+
+    def before(self, hook: PluginHook) -> None:
+        self._before.append(hook)
+
+    def after(self, hook: PluginHook) -> None:
+        self._after.append(hook)
+
+    def fire_before(self, *args: Any, **kwargs: Any) -> None:
+        for hook in self._before:
+            try:
+                hook.callback(*args, **kwargs)
+            except Exception:
+                _logger.exception("hook %s failed (before)", hook.name)
+
+    def fire_after(self, *args: Any, **kwargs: Any) -> None:
+        for hook in self._after:
+            try:
+                hook.callback(*args, **kwargs)
+            except Exception:
+                _logger.exception("hook %s failed (after)", hook.name)
+
+    async def fire_before_async(self, *args: Any, **kwargs: Any) -> None:
+        for hook in self._before:
+            try:
+                result = hook.callback(*args, **kwargs)
+                if asyncio.iscoroutine(result):
+                    await result
+            except Exception:
+                _logger.exception("hook %s failed (before)", hook.name)
+
+    async def fire_after_async(self, *args: Any, **kwargs: Any) -> None:
+        for hook in self._after:
+            try:
+                result = hook.callback(*args, **kwargs)
+                if asyncio.iscoroutine(result):
+                    await result
+            except Exception:
+                _logger.exception("hook %s failed (after)", hook.name)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+@contextlib.contextmanager
+def _suppress(*exceptions: type[BaseException]):
+    with contextlib.suppress(*exceptions):
+        yield
+
+
+def _discard_task(task: asyncio.Task) -> None:
+    """Keep a strong reference to a scheduled task until it completes."""
+    return None
+
+
+__all__ = [
+    "EventHandler",
+    "HookManager",
+    "PluginEvent",
+    "PluginEventBus",
+    "PluginEventKind",
+    "PluginHook",
+]

forgecli/sdk/interfaces.py

@@ -0,0 +1,282 @@
+"""The 10 canonical plugin extension points.
+
+Every ForgeCLI plugin declares one or more of these. Each interface
+is a :class:`typing.Protocol` with a single async or sync ``register``
+method; the SDK calls the method when the plugin is enabled.
+
+Adding a new plugin category is intentionally hard: the SDK exposes
+exactly these ten categories and the engine only looks for them by
+name. Plugin authors who want a new category should add a new
+:class:`EntryPointKind` to :mod:`forgecli.sdk.manifest`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# Re-export the SDK manager for forward references below. The import
+# is intentionally non-binding (TYPE_CHECKING) because the actual
+# PluginManager class lives in :mod:`forgecli.sdk.manager` and would
+# create a circular import at runtime.
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+if TYPE_CHECKING:  # pragma: no cover - type hints only
+    from forgecli.sdk.manager import PluginManager
+
+# ---------------------------------------------------------------------------
+# Configuration protocol
+# ---------------------------------------------------------------------------
+
+
+@runtime_checkable
+class PluginConfigurable(Protocol):
+    """A plugin that exposes user-configurable values.
+
+    Plugins implementing this protocol may return a dict from
+    :meth:`default_config`; the SDK merges that into the persisted
+    configuration under ``plugin.<name>``. The dict may contain any
+    JSON-serialisable values.
+    """
+
+    def default_config(self) -> dict[str, Any]: ...
+
+
+# ---------------------------------------------------------------------------
+# Health protocol
+# ---------------------------------------------------------------------------
+
+
+@runtime_checkable
+class PluginHealthCheck(Protocol):
+    """A plugin that exposes a synchronous health probe.
+
+    The SDK calls :meth:`health` whenever ``forge plugin doctor``
+    is invoked; the returned list of :class:`HealthIssue` items is
+    surfaced in the doctor report.
+    """
+
+    def health(self) -> list[HealthIssue]: ...
+
+
+# ---------------------------------------------------------------------------
+# 1. AI Provider
+# ---------------------------------------------------------------------------
+
+
+@runtime_checkable
+class AIProviderPlugin(Protocol):
+    """Register a custom AI provider with the router.
+
+    The plugin's :meth:`register` is called with the
+    :class:`~forgecli.plugins.PluginRegistry`; the plugin calls
+    :meth:`PluginRegistry.register_provider` to add itself.
+    """
+
+    name: str
+
+    def register(self, manager: PluginManager) -> None: ...
+
+
+# ---------------------------------------------------------------------------
+# 2. Repository Analyzer
+# ---------------------------------------------------------------------------
+
+
+@runtime_checkable
+class RepositoryAnalyzerPlugin(Protocol):
+    """Register a :class:`RepositoryAnalyzer` with the review engine.
+
+    The plugin's :meth:`register` is called with the manager; the
+    plugin calls :meth:`PluginManager.register_repository_analyzer`.
+    """
+
+    name: str
+
+    def register(self, manager: PluginManager) -> None: ...
+
+
+# ---------------------------------------------------------------------------
+# 3. Context Optimizer
+# ---------------------------------------------------------------------------
+
+
+@runtime_checkable
+class ContextOptimizerPlugin(Protocol):
+    """Register a :class:`PromptOptimizer` with the engine."""
+
+    name: str
+
+    def register(self, manager: PluginManager) -> None: ...
+
+
+# ---------------------------------------------------------------------------
+# 4. Code Generator
+# ---------------------------------------------------------------------------
+
+
+@runtime_checkable
+class CodeGeneratorPlugin(Protocol):
+    """Register a code generator (e.g. a custom executor)."""
+
+    name: str
+
+    def register(self, manager: PluginManager) -> None: ...
+
+
+# ---------------------------------------------------------------------------
+# 5. Test Runner
+# ---------------------------------------------------------------------------
+
+
+@runtime_checkable
+class TestRunnerPlugin(Protocol):
+    """Register a custom test runner.
+
+    The plugin's :meth:`register` is called with the manager; the
+    plugin can use ``manager.register_test_runner(name, callback)``
+    to register a callable that the engine will use to run tests
+    on a project.
+    """
+
+    name: str
+
+    def register(self, manager: PluginManager) -> None: ...
+
+
+# ---------------------------------------------------------------------------
+# 6. Git Provider
+# ---------------------------------------------------------------------------
+
+
+@runtime_checkable
+class GitProviderPlugin(Protocol):
+    """Register a custom Git provider.
+
+    The plugin's :meth:`register` is called with the manager; the
+    plugin can replace or extend ``manager.git_service`` with its
+    own implementation.
+    """
+
+    name: str
+
+    def register(self, manager: PluginManager) -> None: ...
+
+
+# ---------------------------------------------------------------------------
+# 7. Documentation Generator
+# ---------------------------------------------------------------------------
+
+
+@runtime_checkable
+class DocumentationGeneratorPlugin(Protocol):
+    """Register a documentation generator.
+
+    The plugin's :meth:`register` is called with the manager; the
+    plugin calls :meth:`PluginManager.register_docs_generator`.
+    """
+
+    name: str
+
+    def register(self, manager: PluginManager) -> None: ...
+
+
+# ---------------------------------------------------------------------------
+# 8. Deployment Provider
+# ---------------------------------------------------------------------------
+
+
+@runtime_checkable
+class DeploymentProviderPlugin(Protocol):
+    """Register a deployment provider (CI, cloud, package manager)."""
+
+    name: str
+
+    def register(self, manager: PluginManager) -> None: ...
+
+
+# ---------------------------------------------------------------------------
+# 9. Observability Provider
+# ---------------------------------------------------------------------------
+
+
+@runtime_checkable
+class ObservabilityProviderPlugin(Protocol):
+    """Register an observability provider (metrics, tracing, logs)."""
+
+    name: str
+
+    def register(self, manager: PluginManager) -> None: ...
+
+
+# ---------------------------------------------------------------------------
+# 10. Notification Provider
+# ---------------------------------------------------------------------------
+
+
+@runtime_checkable
+class NotificationProviderPlugin(Protocol):
+    """Register a notification sink (Slack, email, webhook)."""
+
+    name: str
+
+    def register(self, manager: PluginManager) -> None: ...
+
+
+# ---------------------------------------------------------------------------
+# Health issue + summary types
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class HealthIssue:
+    """A single result from a plugin's health probe."""
+
+    severity: str  # "info" | "warn" | "error"
+    message: str
+    suggestion: str | None = None
+
+
+@dataclass(frozen=True)
+class HealthReport:
+    """The aggregated health report for a single plugin."""
+
+    plugin_name: str
+    issues: tuple[HealthIssue, ...] = ()
+    healthy: bool = True
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "plugin": self.plugin_name,
+            "healthy": self.healthy,
+            "issues": [
+                {
+                    "severity": issue.severity,
+                    "message": issue.message,
+                    "suggestion": issue.suggestion,
+                }
+                for issue in self.issues
+            ],
+        }
+
+
+# Forward import for type hints only.
+if False:  # pragma: no cover - type hints only
+    from forgecli.sdk.manager import PluginManager
+
+
+__all__ = [
+    "AIProviderPlugin",
+    "CodeGeneratorPlugin",
+    "ContextOptimizerPlugin",
+    "DeploymentProviderPlugin",
+    "DocumentationGeneratorPlugin",
+    "GitProviderPlugin",
+    "HealthIssue",
+    "HealthReport",
+    "NotificationProviderPlugin",
+    "ObservabilityProviderPlugin",
+    "PluginConfigurable",
+    "PluginHealthCheck",
+    "RepositoryAnalyzerPlugin",
+    "TestRunnerPlugin",
+]