forgeoptimizer 1.0.0__py3-none-any.whl

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",
+]

forgecli/sdk/loader.py

@@ -0,0 +1,243 @@
+"""Plugin discovery and on-disk loading.
+
+The SDK supports two complementary sources:
+
+* **Filesystem-based** plugins. A directory under
+  ``$config_dir/plugins/<name>`` containing
+  ``forgecli-plugin.toml`` and a Python package. The loader reads
+  the manifest, then imports the entry-point callables on enable.
+* **Entry-point-based** plugins. A regular Python package with a
+  ``[project.entry-points."forgecli.plugins"]`` table. The loader
+  walks the active distribution set via :mod:`importlib.metadata`.
+
+Both sources return a :class:`LoadedPlugin` (manifest + the
+resolved entry-point callables + source path). The
+:class:`PluginManager` consumes these.
+"""
+
+from __future__ import annotations
+
+import importlib
+import importlib.metadata as importlib_metadata
+import importlib.util
+import sys
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from types import ModuleType
+
+from forgecli.platform.paths import config_dir
+from forgecli.sdk.manifest import PluginManifest
+from forgecli.sdk.version import Version
+
+_MANIFEST_FILENAME = "forgecli-plugin.toml"
+_PLUGINS_DIRNAME = "plugins"
+_ENTRY_POINT_GROUP = "forgecli.plugins"
+
+
+@dataclass(frozen=True)
+class LoadedPlugin:
+    """The result of loading a single plugin from disk or PyPI."""
+
+    manifest: PluginManifest
+    entry_point_factories: dict
+    """Map of (kind, name) -> configure(manager) callable.
+
+    Each callable is invoked when the plugin is enabled; the
+    callable uses the manager to register workflows, providers,
+    analyzers, etc.
+    """
+
+    source: Path | None = None  # None for entry-point-only plugins
+
+    @property
+    def name(self) -> str:
+        return self.manifest.name
+
+    @property
+    def version(self) -> Version:
+        return self.manifest.version
+
+
+class PluginManifestNotFoundError(LookupError):
+    """Raised when a plugin's manifest is missing or malformed."""
+
+
+# Backward-compatible alias for the legacy name.
+PluginManifestNotFound = PluginManifestNotFoundError
+
+
+def default_plugins_dir() -> Path:
+    """Return the directory where on-disk plugins live."""
+    path = config_dir() / _PLUGINS_DIRNAME
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def discover_filesystem(root: Path | None = None) -> list[LoadedPlugin]:
+    """Find every plugin under ``root`` (default: ``$config_dir/plugins``)."""
+    base = root or default_plugins_dir()
+    if not base.exists():
+        return []
+    plugins: list[LoadedPlugin] = []
+    for child in sorted(base.iterdir()):
+        if not child.is_dir():
+            continue
+        manifest_path = child / _MANIFEST_FILENAME
+        if not manifest_path.exists():
+            continue
+        try:
+            plugins.append(load_filesystem(child))
+        except PluginManifestNotFound:
+            continue
+    return plugins
+
+
+def load_filesystem(plugin_dir: Path) -> LoadedPlugin:
+    """Load a single plugin from a directory on disk."""
+    manifest_path = plugin_dir / _MANIFEST_FILENAME
+    manifest = PluginManifest.load(manifest_path)
+    factories = _load_entry_point_factories(manifest, plugin_dir)
+    return LoadedPlugin(
+        manifest=manifest,
+        entry_point_factories=factories,
+        source=plugin_dir,
+    )
+
+
+def discover_entry_points() -> list[LoadedPlugin]:
+    """Find every plugin registered via the ``forgecli.plugins`` entry point group."""
+    plugins: list[LoadedPlugin] = []
+    try:
+        entries = importlib_metadata.entry_points(group=_ENTRY_POINT_GROUP)
+    except Exception:
+        return plugins
+    # Group by distribution to load one synthetic manifest per
+    # distribution. This is a pragmatic choice that lets users ship
+    # multiple plugins in a single distribution.
+    by_distribution: dict[str | None, list] = {}
+    for ep in entries:
+        dist = getattr(ep, "dist", None)
+        dist_name = dist.name if dist is not None else "unknown"
+        by_distribution.setdefault(dist_name, []).append(ep)
+    for dist_name, ep_list in by_distribution.items():
+        try:
+            plugins.append(_load_entry_point_distribution(dist_name, ep_list))
+        except PluginManifestNotFound:
+            continue
+        except Exception:
+            continue
+    return plugins
+
+
+def _load_entry_point_distribution(
+    dist_name: str | None, entry_points: list
+) -> LoadedPlugin:
+    """Load a distribution's entry-points as a synthetic plugin."""
+    if dist_name is None:
+        raise PluginManifestNotFound("entry point has no distribution")
+    try:
+        dist = importlib_metadata.distribution(dist_name)
+    except importlib_metadata.PackageNotFoundError as exc:
+        raise PluginManifestNotFound(dist_name) from exc
+    # Use the distribution's metadata to build a synthetic manifest.
+    meta = dist.metadata
+    name = _coerce_name(meta.get("Name") or dist_name, dist_name)
+    version = _coerce_version(meta.get("Version"))
+    if version is None:
+        raise PluginManifestNotFound(f"{dist_name}: no version")
+    summary = meta.get("Summary", "").strip()
+    summary = summary.splitlines()[0] if summary else f"{name} plugin"
+    manifest = PluginManifest(
+        name=name,
+        version=version,
+        summary=summary,
+        description=meta.get("Description", "") or "",
+        authors=tuple(_parse_authors(meta.get("Author"))),
+        license=meta.get("License", "") or "",
+        homepage=meta.get("Home-page", "") or "",
+    )
+    factories: dict[tuple[str, str], Callable] = {}
+    for ep in entry_points:
+        try:
+            callback = ep.load()
+        except Exception:
+            continue
+        from forgecli.sdk.manifest import EntryPointKind as _Kind
+
+        try:
+            kind = _Kind(ep.group.replace(f"{_ENTRY_POINT_GROUP}.", ""))
+        except ValueError:
+            continue
+        factories[(kind.value, ep.name)] = callback
+    return LoadedPlugin(
+        manifest=manifest,
+        entry_point_factories=factories,
+        source=None,
+    )
+
+
+def _load_entry_point_factories(
+    manifest: PluginManifest, plugin_dir: Path
+) -> dict:
+    """Import each ``module:attr`` reference declared in the manifest."""
+    factories: dict = {}
+    for ep in manifest.entry_points:
+        module_name, _, attr = ep.reference.partition(":")
+        if not module_name or not attr:
+            continue
+        try:
+            module = _import_module_from_dir(module_name, plugin_dir)
+        except Exception:
+            continue
+        callback = getattr(module, attr, None)
+        if not callable(callback):
+            continue
+        factories[(ep.kind.value, ep.name)] = callback
+    return factories
+
+
+def _import_module_from_dir(name: str, plugin_dir: Path) -> ModuleType:
+    """Import ``name`` from a directory under ``plugin_dir``.
+
+    We add the plugin dir to ``sys.path`` and then ``importlib.import_module``
+    so the import works for both regular packages and loose modules.
+    """
+    if str(plugin_dir) not in sys.path:
+        sys.path.insert(0, str(plugin_dir))
+    return importlib.import_module(name)
+
+
+def _coerce_name(value: str | None, fallback: str) -> str:
+    if not value:
+        return fallback.lower().replace("_", "-").replace(" ", "-")
+    return value.lower().replace("_", "-")
+
+
+def _coerce_version(value: str | None) -> Version | None:
+    if not value:
+        return None
+    from forgecli.sdk.version import Version, VersionParseError
+
+    try:
+        return Version.parse(value)
+    except VersionParseError:
+        return None
+
+
+def _parse_authors(value: str | None) -> list[str]:
+    if not value:
+        return []
+    return [a.strip() for a in value.split(",") if a.strip()]
+
+
+# Silence unused-import warnings.
+
+__all__ = [
+    "LoadedPlugin",
+    "PluginManifestNotFound",
+    "default_plugins_dir",
+    "discover_entry_points",
+    "discover_filesystem",
+    "load_filesystem",
+]