gaard-plugin-api 0.1.0__tar.gz

gaard_plugin_api-0.1.0/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: gaard-plugin-api
+Version: 0.1.0
+Summary: Versioned extension contracts and discovery for GAARD
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: packaging>=24.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: ruff>=0.5.0; extra == "dev"
+Requires-Dist: mypy>=1.10.0; extra == "dev"
+
+# gaard-plugin-api
+
+`gaard-plugin-api` provides the stable, dependency-light contracts used by
+GAARD extension packages. It defines extension manifests, discovery through
+Python entry points, compatibility validation, and contribution activation.
+
+An extension is trusted, installed Python code. GAARD does not load executable
+extensions from database records, configuration files, or arbitrary URLs.

gaard_plugin_api-0.1.0/README.md

@@ -0,0 +1,8 @@
+# gaard-plugin-api
+
+`gaard-plugin-api` provides the stable, dependency-light contracts used by
+GAARD extension packages. It defines extension manifests, discovery through
+Python entry points, compatibility validation, and contribution activation.
+
+An extension is trusted, installed Python code. GAARD does not load executable
+extensions from database records, configuration files, or arbitrary URLs.

gaard_plugin_api-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gaard-plugin-api"
+version = "0.1.0"
+description = "Versioned extension contracts and discovery for GAARD"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "packaging>=24.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "ruff>=0.5.0",
+    "mypy>=1.10.0",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.setuptools.packages.find]
+where = ["src"]

gaard_plugin_api-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

gaard_plugin_api-0.1.0/src/gaard_plugin_api/__init__.py

@@ -0,0 +1,29 @@
+from gaard_plugin_api.discovery import (
+    EXTENSION_ENTRY_POINT_GROUP,
+    ExtensionManager,
+    discover_extensions,
+)
+from gaard_plugin_api.models import (
+    EXTENSION_API_VERSION,
+    ExtensionActivationError,
+    ExtensionCompatibilityError,
+    ExtensionContext,
+    ExtensionManifest,
+    ExtensionManifestError,
+    ExtensionRecord,
+    ExtensionStatus,
+)
+
+__all__ = [
+    "EXTENSION_API_VERSION",
+    "EXTENSION_ENTRY_POINT_GROUP",
+    "ExtensionActivationError",
+    "ExtensionCompatibilityError",
+    "ExtensionContext",
+    "ExtensionManager",
+    "ExtensionManifest",
+    "ExtensionManifestError",
+    "ExtensionRecord",
+    "ExtensionStatus",
+    "discover_extensions",
+]

gaard_plugin_api-0.1.0/src/gaard_plugin_api/discovery.py

@@ -0,0 +1,195 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Mapping
+from importlib import import_module
+from importlib.metadata import PackageNotFoundError, entry_points, version
+from typing import Any, Protocol, cast
+
+from packaging.specifiers import InvalidSpecifier, SpecifierSet
+
+from gaard_plugin_api.models import (
+    EXTENSION_API_VERSION,
+    ExtensionActivationError,
+    ExtensionCompatibilityError,
+    ExtensionContext,
+    ExtensionManifest,
+    ExtensionManifestError,
+    ExtensionRecord,
+    ExtensionStatus,
+)
+
+
+EXTENSION_ENTRY_POINT_GROUP = "gaard.extensions"
+
+
+class EntryPointLike(Protocol):
+    name: str
+
+    def load(self) -> Any: ...
+
+
+ContributionLoader = Callable[[str], Callable[[ExtensionContext], None]]
+PackageVersionResolver = Callable[[str], str]
+
+
+def discover_extensions(
+    entry_point_items: Iterable[EntryPointLike] | None = None,
+    package_version: PackageVersionResolver = version,
+) -> list[ExtensionRecord]:
+    """Discover installed manifests without activating their contributions."""
+
+    selected_entry_points = (
+        list(entry_point_items)
+        if entry_point_items is not None
+        else list(entry_points(group=EXTENSION_ENTRY_POINT_GROUP))
+    )
+    records: list[ExtensionRecord] = []
+
+    for entry_point in sorted(selected_entry_points, key=lambda item: item.name):
+        record = ExtensionRecord(entry_point_name=entry_point.name)
+        records.append(record)
+
+        try:
+            manifest = _load_manifest(entry_point)
+            _validate_compatibility(manifest, package_version)
+        except (
+            ExtensionCompatibilityError,
+            ExtensionManifestError,
+            PackageNotFoundError,
+            TypeError,
+            ValueError,
+        ) as exc:
+            record.status = ExtensionStatus.FAILED
+            record.error = str(exc)
+            continue
+        except Exception as exc:  # pragma: no cover - defensive boundary for third-party code
+            record.status = ExtensionStatus.FAILED
+            record.error = f"Unable to load extension manifest: {exc}"
+            continue
+
+        record.manifest = manifest
+        record.status = ExtensionStatus.VALIDATED
+
+    return records
+
+
+class ExtensionManager:
+    """Discovers and activates typed extension contributions for one host process."""
+
+    def __init__(
+        self,
+        entry_point_items: Iterable[EntryPointLike] | None = None,
+        package_version: PackageVersionResolver = version,
+        contribution_loader: ContributionLoader | None = None,
+    ) -> None:
+        self._entry_point_items = entry_point_items
+        self._package_version = package_version
+        self._contribution_loader = contribution_loader or load_contribution
+        self.records: list[ExtensionRecord] = []
+
+    def discover(self) -> list[ExtensionRecord]:
+        self.records = discover_extensions(
+            entry_point_items=self._entry_point_items,
+            package_version=self._package_version,
+        )
+        return self.records
+
+    def activate(
+        self,
+        capability: str,
+        registry: Any,
+        services: Mapping[str, Any] | None = None,
+    ) -> list[ExtensionRecord]:
+        """Activate one capability for every validated extension that declares it."""
+
+        if not self.records:
+            self.discover()
+
+        activated: list[ExtensionRecord] = []
+
+        for record in self.records:
+            if record.status not in {ExtensionStatus.VALIDATED, ExtensionStatus.ACTIVE}:
+                continue
+            if record.manifest is None or capability not in record.manifest.contributions:
+                continue
+            if capability in record.active_capabilities:
+                continue
+
+            target = record.manifest.contributions[capability]
+            context = ExtensionContext(
+                extension_id=record.manifest.id,
+                capability=capability,
+                registry=registry,
+                services=services or {},
+            )
+
+            try:
+                contribution = self._contribution_loader(target)
+                contribution(context)
+            except Exception as exc:  # pragma: no cover - defensive boundary for third-party code
+                record.status = ExtensionStatus.FAILED
+                record.error = f"Unable to activate {capability!r} contribution: {exc}"
+                continue
+
+            record.active_capabilities.add(capability)
+            record.status = ExtensionStatus.ACTIVE
+            activated.append(record)
+
+        return activated
+
+
+def load_contribution(target: str) -> Callable[[ExtensionContext], None]:
+    """Import one declared contribution factory from a `module:attribute` target."""
+
+    module_name, separator, attribute_name = target.partition(":")
+    if not separator or not module_name or not attribute_name:
+        raise ExtensionActivationError(
+            "Extension contribution targets must use the 'module:attribute' format."
+        )
+
+    module = import_module(module_name)
+    contribution = getattr(module, attribute_name)
+
+    if not callable(contribution):
+        raise ExtensionActivationError(f"Extension contribution {target!r} is not callable.")
+
+    return cast(Callable[[ExtensionContext], None], contribution)
+
+
+def _load_manifest(entry_point: EntryPointLike) -> ExtensionManifest:
+    candidate = entry_point.load()
+    manifest = candidate() if callable(candidate) else candidate
+
+    if not isinstance(manifest, ExtensionManifest):
+        raise ExtensionManifestError(
+            f"Entry point {entry_point.name!r} must resolve to an ExtensionManifest or a factory."
+        )
+
+    return manifest
+
+
+def _validate_compatibility(
+    manifest: ExtensionManifest,
+    package_version: PackageVersionResolver,
+) -> None:
+    if manifest.extension_api_version != EXTENSION_API_VERSION:
+        raise ExtensionCompatibilityError(
+            f"Extension {manifest.id!r} requires extension API "
+            f"{manifest.extension_api_version!r}, but host supports {EXTENSION_API_VERSION!r}."
+        )
+
+    for package_name, version_specifier in manifest.requires.items():
+        try:
+            requirement = SpecifierSet(version_specifier)
+        except InvalidSpecifier as exc:
+            raise ExtensionCompatibilityError(
+                f"Extension {manifest.id!r} has invalid version specifier "
+                f"{version_specifier!r} for {package_name!r}."
+            ) from exc
+
+        installed_version = package_version(package_name)
+        if installed_version not in requirement:
+            raise ExtensionCompatibilityError(
+                f"Extension {manifest.id!r} requires {package_name}{version_specifier}, "
+                f"but {installed_version} is installed."
+            )

gaard_plugin_api-0.1.0/src/gaard_plugin_api/models.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from enum import StrEnum
+from types import MappingProxyType
+from typing import Any
+
+
+EXTENSION_API_VERSION = "1"
+_EXTENSION_ID_PATTERN = re.compile(r"^[a-z][a-z0-9-]{0,62}$")
+
+
+class ExtensionManifestError(ValueError):
+    """Raised when an extension manifest does not satisfy the public contract."""
+
+
+class ExtensionCompatibilityError(RuntimeError):
+    """Raised when an installed extension is incompatible with the host."""
+
+
+class ExtensionActivationError(RuntimeError):
+    """Raised when an extension contribution cannot be activated."""
+
+
+class ExtensionStatus(StrEnum):
+    DISCOVERED = "discovered"
+    VALIDATED = "validated"
+    ACTIVE = "active"
+    DISABLED = "disabled"
+    FAILED = "failed"
+
+
+@dataclass(frozen=True, slots=True)
+class ExtensionManifest:
+    """Public metadata describing one installed GAARD extension."""
+
+    id: str
+    version: str
+    extension_api_version: str = EXTENSION_API_VERSION
+    requires: Mapping[str, str] = field(default_factory=dict)
+    contributions: Mapping[str, str] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if not _EXTENSION_ID_PATTERN.fullmatch(self.id):
+            raise ExtensionManifestError(
+                "Extension id must use lowercase letters, digits, and hyphens, "
+                "and must start with a letter."
+            )
+
+        if not self.version.strip():
+            raise ExtensionManifestError("Extension version must not be empty.")
+
+        for package_name, version_specifier in self.requires.items():
+            if not package_name.strip() or not version_specifier.strip():
+                raise ExtensionManifestError(
+                    "Extension package requirements must contain a package name and version specifier."
+                )
+
+        for capability, target in self.contributions.items():
+            if not capability.strip():
+                raise ExtensionManifestError("Extension contribution capability must not be empty.")
+            if not _is_import_target(target):
+                raise ExtensionManifestError(
+                    "Extension contribution targets must use the 'module:attribute' format."
+                )
+
+        object.__setattr__(self, "requires", MappingProxyType(dict(self.requires)))
+        object.__setattr__(self, "contributions", MappingProxyType(dict(self.contributions)))
+
+
+@dataclass(slots=True)
+class ExtensionRecord:
+    """Runtime state for a discovered extension."""
+
+    entry_point_name: str
+    manifest: ExtensionManifest | None = None
+    status: ExtensionStatus = ExtensionStatus.DISCOVERED
+    error: str | None = None
+    active_capabilities: set[str] = field(default_factory=set)
+
+
+@dataclass(frozen=True, slots=True)
+class ExtensionContext:
+    """Controlled context supplied to one extension contribution factory."""
+
+    extension_id: str
+    capability: str
+    registry: Any
+    services: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "services", MappingProxyType(dict(self.services)))
+
+
+def _is_import_target(value: str) -> bool:
+    module_name, separator, attribute_name = value.partition(":")
+    return bool(separator and module_name.strip() and attribute_name.strip())

gaard_plugin_api-0.1.0/src/gaard_plugin_api.egg-info/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: gaard-plugin-api
+Version: 0.1.0
+Summary: Versioned extension contracts and discovery for GAARD
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: packaging>=24.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: ruff>=0.5.0; extra == "dev"
+Requires-Dist: mypy>=1.10.0; extra == "dev"
+
+# gaard-plugin-api
+
+`gaard-plugin-api` provides the stable, dependency-light contracts used by
+GAARD extension packages. It defines extension manifests, discovery through
+Python entry points, compatibility validation, and contribution activation.
+
+An extension is trusted, installed Python code. GAARD does not load executable
+extensions from database records, configuration files, or arbitrary URLs.

gaard_plugin_api-0.1.0/src/gaard_plugin_api.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+src/gaard_plugin_api/__init__.py
+src/gaard_plugin_api/discovery.py
+src/gaard_plugin_api/models.py
+src/gaard_plugin_api.egg-info/PKG-INFO
+src/gaard_plugin_api.egg-info/SOURCES.txt
+src/gaard_plugin_api.egg-info/dependency_links.txt
+src/gaard_plugin_api.egg-info/requires.txt
+src/gaard_plugin_api.egg-info/top_level.txt
+tests/test_discovery.py

gaard_plugin_api-0.1.0/src/gaard_plugin_api.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

gaard_plugin_api-0.1.0/src/gaard_plugin_api.egg-info/requires.txt

@@ -0,0 +1,6 @@
+packaging>=24.0
+
+[dev]
+pytest>=8.0.0
+ruff>=0.5.0
+mypy>=1.10.0

gaard_plugin_api-0.1.0/src/gaard_plugin_api.egg-info/top_level.txt

@@ -0,0 +1 @@
+gaard_plugin_api

gaard_plugin_api-0.1.0/tests/test_discovery.py

@@ -0,0 +1,79 @@
+from dataclasses import dataclass
+
+from gaard_plugin_api import (
+    EXTENSION_API_VERSION,
+    ExtensionContext,
+    ExtensionManager,
+    ExtensionManifest,
+    ExtensionStatus,
+    discover_extensions,
+)
+
+
+@dataclass
+class FakeEntryPoint:
+    name: str
+    value: object
+
+    def load(self) -> object:
+        return self.value
+
+
+def test_discovery_validates_manifests_and_package_compatibility() -> None:
+    manifest = ExtensionManifest(
+        id="acme-warehouse",
+        version="1.2.3",
+        requires={"gaard-connectors": ">=0.1,<0.2"},
+    )
+
+    records = discover_extensions(
+        [FakeEntryPoint("acme", manifest)],
+        package_version=lambda package_name: "0.1.0",
+    )
+
+    assert len(records) == 1
+    assert records[0].status == ExtensionStatus.VALIDATED
+    assert records[0].manifest == manifest
+
+
+def test_discovery_reports_incompatible_extensions_without_raising() -> None:
+    manifest = ExtensionManifest(
+        id="future-extension",
+        version="1.0.0",
+        extension_api_version="999",
+    )
+
+    records = discover_extensions([FakeEntryPoint("future", manifest)])
+
+    assert records[0].status == ExtensionStatus.FAILED
+    assert records[0].error is not None
+    assert "requires extension API" in records[0].error
+
+
+def test_manager_activates_only_declared_capability() -> None:
+    received_contexts: list[ExtensionContext] = []
+
+    def register(context: ExtensionContext) -> None:
+        received_contexts.append(context)
+
+    manifest = ExtensionManifest(
+        id="acme-connector",
+        version="1.0.0",
+        extension_api_version=EXTENSION_API_VERSION,
+        contributions={"connectors": "acme.module:register"},
+    )
+    manager = ExtensionManager(
+        entry_point_items=[FakeEntryPoint("acme", manifest)],
+        contribution_loader=lambda target: register,
+    )
+    registry = object()
+
+    activated = manager.activate("connectors", registry, services={"mode": "test"})
+
+    assert [record.manifest.id for record in activated if record.manifest] == ["acme-connector"]
+    assert received_contexts[0].registry is registry
+    assert received_contexts[0].services == {"mode": "test"}
+    assert manager.records[0].status == ExtensionStatus.ACTIVE
+    assert manager.records[0].active_capabilities == {"connectors"}
+
+    assert manager.activate("llm", registry) == []