pluginforge 0.2.0__tar.gz → 0.4.0__tar.gz

{pluginforge-0.2.0 → pluginforge-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pluginforge
-Version: 0.2.0
+Version: 0.4.0
 Summary: Application-agnostic plugin framework built on pluggy
 License: MIT
 License-File: LICENSE
@@ -118,6 +118,8 @@ pm.mount_routes(app)  # Routes at /api/plugins/{name}/
 - **Alembic Support** - Collect migration directories from plugins
 - **i18n** - Multi-language strings from YAML with fallback
 
+For detailed documentation, see the [Wiki](https://github.com/astrapi69/pluginforge/wiki).
+
 ## Entry Point Discovery
 
 Register plugins as entry points in your `pyproject.toml`:
@@ -148,20 +150,31 @@ pm.get_text("common.save", "en")  # "Save"
 pm.get_text("common.save", "de")  # "Speichern"
 ```
 
-## Development
+## Documentation
 
-```bash
-# Install dependencies
-poetry install --with dev
+The full documentation is available in the [Wiki](https://github.com/astrapi69/pluginforge/wiki):
 
-# Run tests
-poetry run pytest
+- [Getting Started](https://github.com/astrapi69/pluginforge/wiki/Getting-Started)
+- [BasePlugin](https://github.com/astrapi69/pluginforge/wiki/BasePlugin)
+- [PluginManager](https://github.com/astrapi69/pluginforge/wiki/PluginManager)
+- [Configuration](https://github.com/astrapi69/pluginforge/wiki/Configuration)
+- [Discovery and Dependencies](https://github.com/astrapi69/pluginforge/wiki/Discovery-and-Dependencies)
+- [Lifecycle](https://github.com/astrapi69/pluginforge/wiki/Lifecycle)
+- [Hooks](https://github.com/astrapi69/pluginforge/wiki/Hooks)
+- [FastAPI Integration](https://github.com/astrapi69/pluginforge/wiki/FastAPI-Integration)
+- [Alembic Integration](https://github.com/astrapi69/pluginforge/wiki/Alembic-Integration)
+- [i18n](https://github.com/astrapi69/pluginforge/wiki/i18n)
+- [Examples](https://github.com/astrapi69/pluginforge/wiki/Examples)
 
-# Lint
-poetry run ruff check pluginforge/ tests/
+## Development
 
-# Format
-poetry run ruff format pluginforge/ tests/
+```bash
+make install-dev   # Install with dev dependencies
+make test          # Run tests
+make lint          # Run ruff linter
+make format        # Format code
+make ci            # Full CI pipeline (lint + format-check + test)
+make help          # Show all available targets
 ```
 
 ## License

{pluginforge-0.2.0 → pluginforge-0.4.0}/README.md

@@ -93,6 +93,8 @@ pm.mount_routes(app)  # Routes at /api/plugins/{name}/
 - **Alembic Support** - Collect migration directories from plugins
 - **i18n** - Multi-language strings from YAML with fallback
 
+For detailed documentation, see the [Wiki](https://github.com/astrapi69/pluginforge/wiki).
+
 ## Entry Point Discovery
 
 Register plugins as entry points in your `pyproject.toml`:
@@ -123,20 +125,31 @@ pm.get_text("common.save", "en")  # "Save"
 pm.get_text("common.save", "de")  # "Speichern"
 ```
 
-## Development
+## Documentation
 
-```bash
-# Install dependencies
-poetry install --with dev
+The full documentation is available in the [Wiki](https://github.com/astrapi69/pluginforge/wiki):
 
-# Run tests
-poetry run pytest
+- [Getting Started](https://github.com/astrapi69/pluginforge/wiki/Getting-Started)
+- [BasePlugin](https://github.com/astrapi69/pluginforge/wiki/BasePlugin)
+- [PluginManager](https://github.com/astrapi69/pluginforge/wiki/PluginManager)
+- [Configuration](https://github.com/astrapi69/pluginforge/wiki/Configuration)
+- [Discovery and Dependencies](https://github.com/astrapi69/pluginforge/wiki/Discovery-and-Dependencies)
+- [Lifecycle](https://github.com/astrapi69/pluginforge/wiki/Lifecycle)
+- [Hooks](https://github.com/astrapi69/pluginforge/wiki/Hooks)
+- [FastAPI Integration](https://github.com/astrapi69/pluginforge/wiki/FastAPI-Integration)
+- [Alembic Integration](https://github.com/astrapi69/pluginforge/wiki/Alembic-Integration)
+- [i18n](https://github.com/astrapi69/pluginforge/wiki/i18n)
+- [Examples](https://github.com/astrapi69/pluginforge/wiki/Examples)
 
-# Lint
-poetry run ruff check pluginforge/ tests/
+## Development
 
-# Format
-poetry run ruff format pluginforge/ tests/
+```bash
+make install-dev   # Install with dev dependencies
+make test          # Run tests
+make lint          # Run ruff linter
+make format        # Format code
+make ci            # Full CI pipeline (lint + format-check + test)
+make help          # Show all available targets
 ```
 
 ## License

{pluginforge-0.2.0 → pluginforge-0.4.0}/pluginforge/__init__.py

@@ -3,6 +3,12 @@
 from pluginforge.base import BasePlugin
 from pluginforge.discovery import CircularDependencyError
 from pluginforge.manager import PluginManager
+from pluginforge.security import InvalidPluginNameError
 
-__version__ = "0.2.0"
-__all__ = ["BasePlugin", "CircularDependencyError", "PluginManager"]
+__version__ = "0.3.0"
+__all__ = [
+    "BasePlugin",
+    "CircularDependencyError",
+    "InvalidPluginNameError",
+    "PluginManager",
+]

{pluginforge-0.2.0 → pluginforge-0.4.0}/pluginforge/alembic_ext.py

@@ -28,6 +28,15 @@ def collect_migrations_dirs(plugins: list[BasePlugin]) -> dict[str, str]:
                 "Plugin '%s' migrations dir does not exist: %s", plugin.name, migrations_dir
             )
             continue
-        migrations[plugin.name] = str(path)
-        logger.info("Collected migrations for plugin '%s': %s", plugin.name, migrations_dir)
+        # Ensure resolved path doesn't escape via symlinks
+        resolved = path.resolve()
+        if not resolved.is_dir():
+            logger.warning(
+                "Plugin '%s' migrations dir resolves to non-directory: %s",
+                plugin.name,
+                resolved,
+            )
+            continue
+        migrations[plugin.name] = str(resolved)
+        logger.info("Collected migrations for plugin '%s': %s", plugin.name, resolved)
     return migrations

{pluginforge-0.2.0 → pluginforge-0.4.0}/pluginforge/base.py

@@ -16,6 +16,8 @@ class BasePlugin(ABC):
         depends_on: List of plugin names this plugin depends on.
         app_config: Global application configuration, populated during init().
         config: Plugin configuration, populated during init().
+        config_schema: Optional dict mapping config keys to expected types.
+            If set, config is validated during init().
     """
 
     name: str
@@ -26,6 +28,7 @@ class BasePlugin(ABC):
     depends_on: list[str] = []
     app_config: dict[str, Any] = {}
     config: dict[str, Any] = {}
+    config_schema: dict[str, type] | None = None
 
     def init(self, app_config: dict[str, Any], plugin_config: dict[str, Any]) -> None:
         """Called when the plugin is loaded. Receives app and plugin config.
@@ -51,6 +54,24 @@ class BasePlugin(ABC):
         """
         return []
 
+    def get_frontend_manifest(self) -> dict[str, Any] | None:
+        """Return manifest for frontend UI components. Optional.
+
+        Returns:
+            Frontend manifest dict or None.
+        """
+        return None
+
+    def health(self) -> dict[str, Any]:
+        """Return plugin health status. Optional.
+
+        Override to check external dependencies (APIs, databases, etc.).
+
+        Returns:
+            Dict with at least a "status" key ("ok" or "error").
+        """
+        return {"status": "ok"}
+
     def get_migrations_dir(self) -> str | None:
         """Return path to Alembic migration scripts. Optional.
 

{pluginforge-0.2.0 → pluginforge-0.4.0}/pluginforge/config.py

@@ -46,6 +46,8 @@ def load_app_config(config_path: str | Path) -> dict[str, Any]:
 def load_plugin_config(config_dir: str | Path, plugin_name: str) -> dict[str, Any]:
     """Load plugin-specific configuration from config/plugins/{name}.yaml.
 
+    Validates the plugin name to prevent path traversal attacks.
+
     Args:
         config_dir: Base config directory (parent of plugins/).
         plugin_name: Name of the plugin.
@@ -53,6 +55,9 @@ def load_plugin_config(config_dir: str | Path, plugin_name: str) -> dict[str, An
     Returns:
         Plugin configuration dict.
     """
+    from pluginforge.security import validate_plugin_name
+
+    validate_plugin_name(plugin_name)
     path = Path(config_dir) / "plugins" / f"{plugin_name}.yaml"
     return load_yaml(path)
 
@@ -60,6 +65,8 @@ def load_plugin_config(config_dir: str | Path, plugin_name: str) -> dict[str, An
 def load_i18n(config_dir: str | Path, lang: str) -> dict[str, Any]:
     """Load i18n strings for a specific language.
 
+    Validates the language code to prevent path traversal attacks.
+
     Args:
         config_dir: Base config directory (parent of i18n/).
         lang: Language code (e.g. "en", "de").
@@ -67,5 +74,8 @@ def load_i18n(config_dir: str | Path, lang: str) -> dict[str, Any]:
     Returns:
         i18n strings dict.
     """
+    from pluginforge.security import validate_plugin_name
+
+    validate_plugin_name(lang)
     path = Path(config_dir) / "i18n" / f"{lang}.yaml"
     return load_yaml(path)

{pluginforge-0.2.0 → pluginforge-0.4.0}/pluginforge/fastapi_ext.py

@@ -7,14 +7,16 @@ from pluginforge.base import BasePlugin
 logger = logging.getLogger(__name__)
 
 
-def mount_plugin_routes(app: "object", plugins: list[BasePlugin]) -> None:
+def mount_plugin_routes(app: "object", plugins: list[BasePlugin], prefix: str = "/api") -> None:
     """Mount routes from all plugins onto a FastAPI app.
 
-    Each plugin's routes are mounted under /api/plugins/{plugin_name}/.
+    Plugins bring their own route prefixes via their routers.
+    The prefix parameter is prepended to all plugin routes.
 
     Args:
         app: A FastAPI application instance.
         plugins: List of active plugins.
+        prefix: URL prefix for all plugin routes (default: "/api").
     """
     try:
         from fastapi import FastAPI
@@ -32,6 +34,5 @@ def mount_plugin_routes(app: "object", plugins: list[BasePlugin]) -> None:
         if not routes:
             continue
         for router in routes:
-            prefix = f"/api/plugins/{plugin.name}"
             app.include_router(router, prefix=prefix)
-            logger.info("Mounted routes for plugin '%s' at %s", plugin.name, prefix)
+            logger.info("Mounted routes for plugin '%s' under %s", plugin.name, prefix)

{pluginforge-0.2.0 → pluginforge-0.4.0}/pluginforge/lifecycle.py

@@ -37,6 +37,7 @@ class PluginLifecycle:
         """
         try:
             plugin.init(app_config, plugin_config)
+            self._validate_config(plugin)
             self._initialized[plugin.name] = plugin
             logger.info("Initialized plugin: %s", plugin.name)
             return True
@@ -44,6 +45,28 @@ class PluginLifecycle:
             logger.error("Failed to initialize plugin %s: %s", plugin.name, e)
             return False
 
+    @staticmethod
+    def _validate_config(plugin: BasePlugin) -> None:
+        """Validate plugin config against its config_schema if defined.
+
+        Args:
+            plugin: The plugin whose config to validate.
+
+        Raises:
+            TypeError: If a config value has the wrong type.
+        """
+        if plugin.config_schema is None:
+            return
+        for key, expected_type in plugin.config_schema.items():
+            if key not in plugin.config:
+                continue
+            value = plugin.config[key]
+            if not isinstance(value, expected_type):
+                raise TypeError(
+                    f"Plugin '{plugin.name}' config '{key}': "
+                    f"expected {expected_type.__name__}, got {type(value).__name__}"
+                )
+
     def activate_plugin(self, plugin: BasePlugin) -> bool:
         """Activate an initialized plugin.
 
@@ -112,6 +135,17 @@ class PluginLifecycle:
         """
         return self._initialized.get(name)
 
+    def remove_plugin(self, name: str) -> None:
+        """Remove a plugin from all lifecycle tracking.
+
+        Used during hot-reload to clean up before re-instantiation.
+
+        Args:
+            name: Plugin name.
+        """
+        self._initialized.pop(name, None)
+        self._active.pop(name, None)
+
     def is_active(self, name: str) -> bool:
         """Check if a plugin is currently active.
 

pluginforge-0.4.0/pluginforge/manager.py

@@ -0,0 +1,442 @@
+"""Central PluginManager that orchestrates config, discovery, lifecycle, and hooks."""
+
+import importlib
+import logging
+import sys
+from pathlib import Path
+from collections.abc import Callable
+from typing import Any
+
+import pluggy
+
+from pluginforge.base import BasePlugin
+from pluginforge.config import load_app_config, load_plugin_config
+from pluginforge.discovery import (
+    CircularDependencyError,
+    check_missing_dependencies,
+    discover_entry_points,
+    filter_plugins,
+    resolve_dependencies,
+)
+from pluginforge.i18n import I18n
+from pluginforge.lifecycle import PluginLifecycle
+from pluginforge.security import validate_plugin_name
+
+logger = logging.getLogger(__name__)
+
+
+class PluginManager:
+    """Central manager for plugin discovery, lifecycle, and hooks.
+
+    Wraps pluggy.PluginManager and adds YAML config, lifecycle management,
+    dependency resolution, and i18n support.
+
+    Args:
+        config_path: Path to app.yaml configuration file.
+        pre_activate: Optional callback called before plugin activation.
+            Receives (plugin, config) and must return True to allow activation.
+        api_version: Current hook spec version. Plugins with a different
+            api_version will log a warning but still load.
+    """
+
+    def __init__(
+        self,
+        config_path: str = "config/app.yaml",
+        pre_activate: Callable[[BasePlugin, dict[str, Any]], bool] | None = None,
+        api_version: str = "1",
+    ) -> None:
+        self._config_path = Path(config_path)
+        self._config_dir = self._config_path.parent
+        self._app_config = load_app_config(self._config_path)
+        self._pre_activate = pre_activate
+        self._api_version = api_version
+
+        plugins_config = self._app_config.get("plugins", {})
+        group = plugins_config.get("entry_point_group", "pluginforge.plugins")
+        self._entry_point_group = group
+
+        self._pm = pluggy.PluginManager(group)
+        self._lifecycle = PluginLifecycle()
+        self._load_errors: dict[str, str] = {}
+
+        default_lang = self._app_config.get("app", {}).get("default_language", "en")
+        self._i18n = I18n(self._config_dir, default_lang=default_lang)
+
+    def get_app_config(self) -> dict[str, Any]:
+        """Return the loaded application configuration.
+
+        Returns:
+            App config dict.
+        """
+        return self._app_config
+
+    def get_plugin_config(self, plugin_name: str) -> dict[str, Any]:
+        """Load and return config for a specific plugin.
+
+        Args:
+            plugin_name: Name of the plugin.
+
+        Returns:
+            Plugin configuration dict.
+        """
+        return load_plugin_config(self._config_dir, plugin_name)
+
+    def reload_config(self) -> None:
+        """Reload application config from disk.
+
+        Reloads app.yaml and clears the i18n cache. Active plugins are
+        not affected - call deactivate_all() + discover_plugins() to
+        fully restart with new config.
+        """
+        self._app_config = load_app_config(self._config_path)
+        default_lang = self._app_config.get("app", {}).get("default_language", "en")
+        self._i18n = I18n(self._config_dir, default_lang=default_lang)
+        logger.info("Reloaded config from %s", self._config_path)
+
+    def list_available_plugins(self) -> list[str]:
+        """Return names of all discoverable plugins from entry points.
+
+        Returns:
+            List of plugin names without loading them.
+        """
+        return list(discover_entry_points(self._entry_point_group).keys())
+
+    def discover_plugins(self) -> None:
+        """Discover, filter, resolve dependencies, and activate plugins.
+
+        Loads plugins from entry points, filters by enabled/disabled config,
+        checks dependencies, sorts topologically, then initializes and
+        activates each plugin.
+        """
+        plugins = discover_entry_points(self._entry_point_group)
+
+        plugins_config = self._app_config.get("plugins", {})
+        enabled = plugins_config.get("enabled")
+        disabled = plugins_config.get("disabled")
+        plugins = filter_plugins(plugins, enabled, disabled)
+
+        missing = check_missing_dependencies(plugins)
+        for name, deps in missing.items():
+            msg = f"Missing dependencies: {deps}"
+            logger.warning("Plugin '%s' has missing dependencies %s, skipping", name, deps)
+            self._load_errors[name] = msg
+            del plugins[name]
+
+        try:
+            order = resolve_dependencies(plugins)
+        except CircularDependencyError as e:
+            raise e
+
+        self._activate_ordered(plugins, order)
+
+    def register_plugins(self, plugin_classes: list[type[BasePlugin]]) -> None:
+        """Register plugin classes directly (without entry point discovery).
+
+        Useful for testing or programmatic plugin registration.
+
+        Args:
+            plugin_classes: List of plugin classes to register.
+        """
+        plugins_map: dict[str, type[BasePlugin]] = {}
+        for cls in plugin_classes:
+            plugins_map[cls.name] = cls
+
+        plugins_config = self._app_config.get("plugins", {})
+        enabled = plugins_config.get("enabled")
+        disabled = plugins_config.get("disabled")
+        plugins_map = filter_plugins(plugins_map, enabled, disabled)
+
+        missing = check_missing_dependencies(plugins_map)
+        for name, deps in missing.items():
+            msg = f"Missing dependencies: {deps}"
+            logger.warning("Plugin '%s' has missing dependencies %s, skipping", name, deps)
+            self._load_errors[name] = msg
+            del plugins_map[name]
+
+        order = resolve_dependencies(plugins_map)
+
+        self._activate_ordered(plugins_map, order)
+
+    def register_plugin(
+        self, plugin: BasePlugin, plugin_config: dict[str, Any] | None = None
+    ) -> None:
+        """Register a single pre-instantiated plugin.
+
+        Useful for tests or dynamically created plugins.
+
+        Args:
+            plugin: An already instantiated plugin.
+            plugin_config: Optional config dict. If None, loaded from YAML.
+        """
+        validate_plugin_name(plugin.name)
+
+        if plugin_config is None:
+            plugin_config = self.get_plugin_config(plugin.name)
+
+        self._check_api_version(plugin)
+
+        if not self._lifecycle.init_plugin(plugin, self._app_config, plugin_config):
+            self._load_errors[plugin.name] = "Failed to initialize"
+            return
+
+        if self._pre_activate is not None:
+            if not self._pre_activate(plugin, plugin_config):
+                logger.info("Pre-activate check rejected plugin '%s'", plugin.name)
+                self._load_errors[plugin.name] = "Rejected by pre-activate check"
+                return
+
+        self._pm.register(plugin, name=plugin.name)
+
+        if not self._lifecycle.activate_plugin(plugin):
+            self._load_errors[plugin.name] = "Failed to activate"
+            self._pm.unregister(name=plugin.name)
+
+    def _check_api_version(self, plugin: BasePlugin) -> None:
+        """Log a warning if the plugin's api_version differs from the manager's.
+
+        Args:
+            plugin: The plugin to check.
+        """
+        if plugin.api_version != self._api_version:
+            logger.warning(
+                "Plugin '%s' has api_version '%s', expected '%s'",
+                plugin.name,
+                plugin.api_version,
+                self._api_version,
+            )
+
+    def _activate_ordered(self, plugins: dict[str, type[BasePlugin]], order: list[str]) -> None:
+        """Initialize and activate plugins in dependency order.
+
+        Args:
+            plugins: Map of plugin name to plugin class.
+            order: Topologically sorted list of plugin names.
+        """
+        for name in order:
+            validate_plugin_name(name)
+            cls = plugins[name]
+            plugin = cls()
+            plugin_config = self.get_plugin_config(name)
+
+            self._check_api_version(plugin)
+
+            if not self._lifecycle.init_plugin(plugin, self._app_config, plugin_config):
+                self._load_errors[name] = "Failed to initialize"
+                continue
+
+            if self._pre_activate is not None:
+                if not self._pre_activate(plugin, plugin_config):
+                    logger.info("Pre-activate check rejected plugin '%s'", name)
+                    self._load_errors[name] = "Rejected by pre-activate check"
+                    continue
+
+            self._pm.register(plugin, name=name)
+
+            if not self._lifecycle.activate_plugin(plugin):
+                self._load_errors[name] = "Failed to activate"
+                self._pm.unregister(name=name)
+
+    def activate_plugin(self, name: str) -> None:
+        """Activate a specific initialized plugin.
+
+        Args:
+            name: Plugin name.
+        """
+        plugin = self._lifecycle.get_plugin(name)
+        if plugin is None:
+            logger.warning("Plugin '%s' not found", name)
+            return
+        self._lifecycle.activate_plugin(plugin)
+
+    def deactivate_plugin(self, name: str) -> None:
+        """Deactivate a specific active plugin and unregister its hooks.
+
+        Args:
+            name: Plugin name.
+        """
+        plugin = self._lifecycle.get_plugin(name)
+        if plugin is None:
+            logger.warning("Plugin '%s' not found", name)
+            return
+        if self._lifecycle.deactivate_plugin(plugin):
+            self._pm.unregister(name=name)
+
+    def get_plugin(self, name: str) -> BasePlugin | None:
+        """Get a plugin instance by name.
+
+        Args:
+            name: Plugin name.
+
+        Returns:
+            Plugin instance or None.
+        """
+        return self._lifecycle.get_plugin(name)
+
+    def get_active_plugins(self) -> list[BasePlugin]:
+        """Return all currently active plugins.
+
+        Returns:
+            List of active plugins.
+        """
+        return self._lifecycle.get_active_plugins()
+
+    def get_load_errors(self) -> dict[str, str]:
+        """Return errors from plugin loading/activation.
+
+        Returns:
+            Dict mapping plugin name to error message for failed plugins.
+        """
+        return dict(self._load_errors)
+
+    def deactivate_all(self) -> None:
+        """Deactivate all active plugins in reverse order and unregister hooks."""
+        for plugin in reversed(self._lifecycle.get_active_plugins()):
+            if self._lifecycle.deactivate_plugin(plugin):
+                self._pm.unregister(name=plugin.name)
+
+    def register_hookspecs(self, spec_module: object) -> None:
+        """Register hook specifications from a module.
+
+        Args:
+            spec_module: Module containing hookspec-decorated functions.
+        """
+        self._pm.add_hookspecs(spec_module)
+
+    def call_hook(self, hook_name: str, **kwargs: Any) -> list[Any]:
+        """Call a named hook on all registered plugins.
+
+        Args:
+            hook_name: Name of the hook to call.
+            **kwargs: Arguments to pass to hook implementations.
+
+        Returns:
+            List of results from all hook implementations.
+        """
+        hook = getattr(self._pm.hook, hook_name, None)
+        if hook is None:
+            logger.warning("Hook '%s' not found", hook_name)
+            return []
+        return hook(**kwargs)
+
+    def mount_routes(self, app: object, prefix: str = "/api") -> None:
+        """Mount FastAPI routes from all active plugins.
+
+        Args:
+            app: A FastAPI application instance.
+            prefix: URL prefix for all plugin routes (default: "/api").
+        """
+        from pluginforge.fastapi_ext import mount_plugin_routes
+
+        mount_plugin_routes(app, self.get_active_plugins(), prefix=prefix)
+
+    def get_text(self, key: str, lang: str | None = None) -> str:
+        """Get an internationalized string.
+
+        Args:
+            key: Dot-notation i18n key.
+            lang: Language code, or None for default.
+
+        Returns:
+            Translated string.
+        """
+        return self._i18n.get_text(key, lang)
+
+    def collect_migrations(self) -> dict[str, str]:
+        """Collect Alembic migration directories from all active plugins.
+
+        Returns:
+            Dict mapping plugin name to migrations directory path.
+        """
+        from pluginforge.alembic_ext import collect_migrations_dirs
+
+        return collect_migrations_dirs(self.get_active_plugins())
+
+    def health_check(self) -> dict[str, dict[str, Any]]:
+        """Run health checks on all active plugins.
+
+        Returns:
+            Dict mapping plugin name to health status dict.
+        """
+        results: dict[str, dict[str, Any]] = {}
+        for plugin in self.get_active_plugins():
+            try:
+                results[plugin.name] = plugin.health()
+            except Exception as e:
+                results[plugin.name] = {"status": "error", "error": str(e)}
+        return results
+
+    def reload_plugin(self, name: str) -> bool:
+        """Hot-reload a plugin: deactivate, re-import module, re-init, activate.
+
+        The plugin's module is reloaded from disk so code changes take effect
+        without restarting the application.
+
+        Args:
+            name: Name of the plugin to reload.
+
+        Returns:
+            True if reload succeeded, False otherwise.
+        """
+        plugin = self._lifecycle.get_plugin(name)
+        if plugin is None:
+            logger.warning("Cannot reload unknown plugin '%s'", name)
+            return False
+
+        plugin_cls = type(plugin)
+        module_name = plugin_cls.__module__
+
+        # Deactivate and unregister
+        if self._lifecycle.is_active(name):
+            self._lifecycle.deactivate_plugin(plugin)
+            self._pm.unregister(name=name)
+
+        # Remove from lifecycle tracking
+        self._lifecycle.remove_plugin(name)
+
+        # Reload the module
+        try:
+            module = sys.modules.get(module_name)
+            if module is not None:
+                module = importlib.reload(module)
+                plugin_cls = getattr(module, plugin_cls.__name__)
+        except Exception as e:
+            logger.error("Failed to reload module '%s': %s", module_name, e)
+            self._load_errors[name] = f"Failed to reload module: {e}"
+            return False
+
+        # Re-instantiate and activate
+        new_plugin = plugin_cls()
+        plugin_config = self.get_plugin_config(name)
+
+        if not self._lifecycle.init_plugin(new_plugin, self._app_config, plugin_config):
+            self._load_errors[name] = "Failed to initialize after reload"
+            return False
+
+        if self._pre_activate is not None:
+            if not self._pre_activate(new_plugin, plugin_config):
+                self._load_errors[name] = "Rejected by pre-activate check after reload"
+                return False
+
+        self._pm.register(new_plugin, name=name)
+
+        if not self._lifecycle.activate_plugin(new_plugin):
+            self._load_errors[name] = "Failed to activate after reload"
+            self._pm.unregister(name=name)
+            return False
+
+        logger.info("Reloaded plugin '%s'", name)
+        return True
+
+    def get_extensions(self, extension_point: type) -> list[BasePlugin]:
+        """Return all active plugins that implement a given extension point.
+
+        An extension point is any class or ABC. This method returns all active
+        plugins that are instances of that type.
+
+        Args:
+            extension_point: The extension point class to filter by.
+
+        Returns:
+            List of active plugins implementing the extension point.
+        """
+        return [p for p in self.get_active_plugins() if isinstance(p, extension_point)]

pluginforge-0.4.0/pluginforge/security.py

@@ -0,0 +1,55 @@
+"""Security utilities for plugin name validation and path traversal prevention."""
+
+import logging
+import re
+
+logger = logging.getLogger(__name__)
+
+# Plugin names must be alphanumeric with underscores/hyphens, max 64 chars
+_PLUGIN_NAME_RE = re.compile(r"^[a-zA-Z][a-zA-Z0-9_-]{0,63}$")
+
+
+class InvalidPluginNameError(ValueError):
+    """Raised when a plugin name contains invalid characters."""
+
+
+def validate_plugin_name(name: str) -> None:
+    """Validate a plugin name for safety.
+
+    Plugin names are used to construct file paths (config/plugins/{name}.yaml),
+    so they must not contain path separators or traversal sequences.
+
+    Args:
+        name: The plugin name to validate.
+
+    Raises:
+        InvalidPluginNameError: If the name is invalid.
+    """
+    if not _PLUGIN_NAME_RE.match(name):
+        raise InvalidPluginNameError(
+            f"Invalid plugin name '{name}'. "
+            "Names must start with a letter, contain only letters, digits, "
+            "underscores, or hyphens, and be at most 64 characters."
+        )
+
+
+def validate_safe_path(path: str, allowed_base: str) -> bool:
+    """Check that a resolved path stays within the allowed base directory.
+
+    Args:
+        path: The path to validate.
+        allowed_base: The base directory that the path must stay within.
+
+    Returns:
+        True if the path is safe, False otherwise.
+    """
+    from pathlib import Path
+
+    resolved = Path(path).resolve()
+    base = Path(allowed_base).resolve()
+    try:
+        resolved.relative_to(base)
+        return True
+    except ValueError:
+        logger.warning("Path traversal detected: '%s' escapes base '%s'", path, allowed_base)
+        return False

{pluginforge-0.2.0 → pluginforge-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pluginforge"
-version = "0.2.0"
+version = "0.4.0"
 description = "Application-agnostic plugin framework built on pluggy"
 authors = ["Asterios Raptis"]
 license = "MIT"

pluginforge-0.2.0/pluginforge/manager.py

@@ -1,243 +0,0 @@
-"""Central PluginManager that orchestrates config, discovery, lifecycle, and hooks."""
-
-import logging
-from pathlib import Path
-from typing import Any
-
-import pluggy
-
-from pluginforge.base import BasePlugin
-from pluginforge.config import load_app_config, load_plugin_config
-from pluginforge.discovery import (
-    CircularDependencyError,
-    check_missing_dependencies,
-    discover_entry_points,
-    filter_plugins,
-    resolve_dependencies,
-)
-from pluginforge.i18n import I18n
-from pluginforge.lifecycle import PluginLifecycle
-
-logger = logging.getLogger(__name__)
-
-
-class PluginManager:
-    """Central manager for plugin discovery, lifecycle, and hooks.
-
-    Wraps pluggy.PluginManager and adds YAML config, lifecycle management,
-    dependency resolution, and i18n support.
-
-    Args:
-        config_path: Path to app.yaml configuration file.
-    """
-
-    def __init__(self, config_path: str = "config/app.yaml") -> None:
-        self._config_path = Path(config_path)
-        self._config_dir = self._config_path.parent
-        self._app_config = load_app_config(self._config_path)
-
-        plugins_config = self._app_config.get("plugins", {})
-        group = plugins_config.get("entry_point_group", "pluginforge.plugins")
-        self._entry_point_group = group
-
-        self._pm = pluggy.PluginManager(group)
-        self._lifecycle = PluginLifecycle()
-
-        default_lang = self._app_config.get("app", {}).get("default_language", "en")
-        self._i18n = I18n(self._config_dir, default_lang=default_lang)
-
-    def get_app_config(self) -> dict[str, Any]:
-        """Return the loaded application configuration.
-
-        Returns:
-            App config dict.
-        """
-        return self._app_config
-
-    def get_plugin_config(self, plugin_name: str) -> dict[str, Any]:
-        """Load and return config for a specific plugin.
-
-        Args:
-            plugin_name: Name of the plugin.
-
-        Returns:
-            Plugin configuration dict.
-        """
-        return load_plugin_config(self._config_dir, plugin_name)
-
-    def discover_plugins(self) -> None:
-        """Discover, filter, resolve dependencies, and activate plugins.
-
-        Loads plugins from entry points, filters by enabled/disabled config,
-        checks dependencies, sorts topologically, then initializes and
-        activates each plugin.
-        """
-        plugins = discover_entry_points(self._entry_point_group)
-
-        plugins_config = self._app_config.get("plugins", {})
-        enabled = plugins_config.get("enabled")
-        disabled = plugins_config.get("disabled")
-        plugins = filter_plugins(plugins, enabled, disabled)
-
-        missing = check_missing_dependencies(plugins)
-        for name, deps in missing.items():
-            logger.warning("Plugin '%s' has missing dependencies %s, skipping", name, deps)
-            del plugins[name]
-
-        try:
-            order = resolve_dependencies(plugins)
-        except CircularDependencyError as e:
-            raise e
-
-        for name in order:
-            cls = plugins[name]
-            plugin = cls()
-            plugin_config = self.get_plugin_config(name)
-
-            if not self._lifecycle.init_plugin(plugin, self._app_config, plugin_config):
-                continue
-
-            self._pm.register(plugin, name=name)
-
-            if not self._lifecycle.activate_plugin(plugin):
-                self._pm.unregister(name=name)
-
-    def register_plugins(self, plugin_classes: list[type[BasePlugin]]) -> None:
-        """Register plugin classes directly (without entry point discovery).
-
-        Useful for testing or programmatic plugin registration.
-
-        Args:
-            plugin_classes: List of plugin classes to register.
-        """
-        plugins_map: dict[str, type[BasePlugin]] = {}
-        for cls in plugin_classes:
-            plugins_map[cls.name] = cls
-
-        plugins_config = self._app_config.get("plugins", {})
-        enabled = plugins_config.get("enabled")
-        disabled = plugins_config.get("disabled")
-        plugins_map = filter_plugins(plugins_map, enabled, disabled)
-
-        missing = check_missing_dependencies(plugins_map)
-        for name, deps in missing.items():
-            logger.warning("Plugin '%s' has missing dependencies %s, skipping", name, deps)
-            del plugins_map[name]
-
-        order = resolve_dependencies(plugins_map)
-
-        for name in order:
-            cls = plugins_map[name]
-            plugin = cls()
-            plugin_config = self.get_plugin_config(name)
-
-            if not self._lifecycle.init_plugin(plugin, self._app_config, plugin_config):
-                continue
-
-            self._pm.register(plugin, name=name)
-
-            if not self._lifecycle.activate_plugin(plugin):
-                self._pm.unregister(name=name)
-
-    def activate_plugin(self, name: str) -> None:
-        """Activate a specific initialized plugin.
-
-        Args:
-            name: Plugin name.
-        """
-        plugin = self._lifecycle.get_plugin(name)
-        if plugin is None:
-            logger.warning("Plugin '%s' not found", name)
-            return
-        self._lifecycle.activate_plugin(plugin)
-
-    def deactivate_plugin(self, name: str) -> None:
-        """Deactivate a specific active plugin.
-
-        Args:
-            name: Plugin name.
-        """
-        plugin = self._lifecycle.get_plugin(name)
-        if plugin is None:
-            logger.warning("Plugin '%s' not found", name)
-            return
-        self._lifecycle.deactivate_plugin(plugin)
-
-    def get_plugin(self, name: str) -> BasePlugin | None:
-        """Get a plugin instance by name.
-
-        Args:
-            name: Plugin name.
-
-        Returns:
-            Plugin instance or None.
-        """
-        return self._lifecycle.get_plugin(name)
-
-    def get_active_plugins(self) -> list[BasePlugin]:
-        """Return all currently active plugins.
-
-        Returns:
-            List of active plugins.
-        """
-        return self._lifecycle.get_active_plugins()
-
-    def deactivate_all(self) -> None:
-        """Deactivate all active plugins in reverse order."""
-        self._lifecycle.deactivate_all()
-
-    def register_hookspecs(self, spec_module: object) -> None:
-        """Register hook specifications from a module.
-
-        Args:
-            spec_module: Module containing hookspec-decorated functions.
-        """
-        self._pm.add_hookspecs(spec_module)
-
-    def call_hook(self, hook_name: str, **kwargs: Any) -> list[Any]:
-        """Call a named hook on all registered plugins.
-
-        Args:
-            hook_name: Name of the hook to call.
-            **kwargs: Arguments to pass to hook implementations.
-
-        Returns:
-            List of results from all hook implementations.
-        """
-        hook = getattr(self._pm.hook, hook_name, None)
-        if hook is None:
-            logger.warning("Hook '%s' not found", hook_name)
-            return []
-        return hook(**kwargs)
-
-    def mount_routes(self, app: object) -> None:
-        """Mount FastAPI routes from all active plugins.
-
-        Args:
-            app: A FastAPI application instance.
-        """
-        from pluginforge.fastapi_ext import mount_plugin_routes
-
-        mount_plugin_routes(app, self.get_active_plugins())
-
-    def get_text(self, key: str, lang: str | None = None) -> str:
-        """Get an internationalized string.
-
-        Args:
-            key: Dot-notation i18n key.
-            lang: Language code, or None for default.
-
-        Returns:
-            Translated string.
-        """
-        return self._i18n.get_text(key, lang)
-
-    def collect_migrations(self) -> dict[str, str]:
-        """Collect Alembic migration directories from all active plugins.
-
-        Returns:
-            Dict mapping plugin name to migrations directory path.
-        """
-        from pluginforge.alembic_ext import collect_migrations_dirs
-
-        return collect_migrations_dirs(self.get_active_plugins())