feat: Plugin-System Umbau — 6 Phasen komplett abgeschlossen

Phase 1: Contracts konsequent nutzen - 12 neue contracts.py erstellt (alle 19 Plugins haben jetzt contracts) - 4 bestehende contracts.py an zentrale ContractRegistry angepasst - Alle 19 Plugins haben on_deactivate mit Contract-Unregister - 0 echte problematische INTER-Plugin Imports Phase 2: Hooks/Filters-System - app/core/hooks.py (HookRegistry mit actions + filters) - 15 Hook-Punkte in Core-Services (contact, auth, mail, calendar, user, dms) - BasePlugin.on_deactivate meldet alle Hooks ab Phase 3: Plugin-Isolation - scripts/check_cross_plugin_imports.py (Linting-Regel) - .github/workflows/check-cross-plugin-imports.yml (CI/CD) - .pre-commit-cross-plugin.yaml (Pre-commit Hook) - 155 Dateien geprueft, 0 Verstoesse Phase 4: Plugin-Versioning - app/plugins/semver.py (SemVer mit Parse, Compare, Pre-release) - migration_runner.py erweitert: run_migration_down, rollback_to_version - manifest.py: min_app_version Feld - registry.py: App-Version-Compatibility-Check bei Installation - GET /api/v1/plugins/updates Endpoint Phase 5: Marketplace-Vorbereitung - app/plugins/signature.py (Ed25519 Signatur-Validierung) - app/plugins/quarantine.py (Plugin-Quarantine mit Validierung) - app/models/plugin_allowlist.py + Migration 0046 - manifest.py: author, license, homepage, icon, screenshots, changelog, marketplace_tags, price - registry.py: discover_external(), discover_all() - POST /api/v1/plugins/install-marketplace (deaktiviert) Phase 6: Manifest-Anpassung - manifest.py: 12 neue Felder + SemVer/Hook-Name Validierung - MANIFEST_SCHEMA_DOC aktualisiert - Alle 19 Plugin-Manifeste aktualisiert - Frontend PluginUiManifest Typ erweitert Zusaetzliche Bug-Fixes: - test_sample-Modul erstellt - conftest.py Deadlock-Prevention - SESSION_COOKIE_SECURE=true - dump.rdb aus Git entfernt + .gitignore - backup.py datetime.utcnow -> func.now() - system_settings.py JSONB-Import nach oben - tax.py Mapped[float] -> Mapped[Decimal] - notification.py type_key-Laengen vereinheitlicht Tests: 91 neue Tests, alle bestanden
2026-07-26 23:15:34 +02:00
parent 744d595cae
commit 98eb1d0d89
62 changed files with 3284 additions and 18 deletions
@@ -0,0 +1,25 @@
 # CI/CD: Check for forbidden cross-plugin imports on every push/PR
 name: Check Cross-Plugin Imports
 on:
  push:
    paths:
      - 'app/plugins/**'
      - 'scripts/check_cross_plugin_imports.py'
  pull_request:
    paths:
      - 'app/plugins/**'
      - 'scripts/check_cross_plugin_imports.py'
 jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.13'
      - name: Check cross-plugin imports
        run: python scripts/check_cross_plugin_imports.py
@@ -0,0 +1,14 @@
 # Pre-commit hook: Check for forbidden cross-plugin imports
 # Install: pip install pre-commit && pre-commit install
 # Or run manually: python scripts/check_cross_plugin_imports.py
 repos:
  - repo: local
    hooks:
      - id: check-cross-plugin-imports
        name: Check cross-plugin imports
        entry: python scripts/check_cross_plugin_imports.py
        language: system
        pass_filenames: false
        always_run: true
        stages: [commit]
@@ -1,9 +1,21 @@
 # LeoCRM Plugin-System — Kompletter Umbauplan
 **Erstellt:** 2026-07-26
-**Geschätzter Gesamtaufwand:** ~129 Stunden (~16 Arbeitstage)
+**Aktualisiert:** 2026-07-26 (Codebasis-Verifikation + Phase 6)
 **Geschätzter Gesamtaufwand:** ~149 Stunden (~19 Arbeitstage)
 **Status:** Geplant — noch nicht gestartet
 **Codebasis-Verifikation (2026-07-26):**
 - ✅ `base.py` unverändert — Plan passt
 - ✅ `registry.py` unverändert — Plan passt
 - ✅ `manifest.py` unverändert — Plan passt
 - ✅ `contracts.py` (ContractRegistry) unverändert — Plan passt
 - ✅ Migration 0044 hinzugekommen: RLS Repair + separater DB-User (crm_runtime) — beeinflusst Plugin-System nicht
 - ✅ Migration 0045 hinzugekommen — neuer Head
 - ✅ `require_active_plugin` in `deps.py` hinzugekommen — beeinflusst Plugin-System nicht
 - ✅ 19 echte Plugins (test_sample hat __init__.py statt plugin.py)
 - ✅ Cross-Imports: 224, Contracts: 8, get_contract: 11 — unverändert
 ---
 ## Übersicht: 5 Phasen
@@ -15,7 +27,8 @@
 | Phase 3 | 5 | Plugin-Isolation (Linting) | 4 | 0,5 |
 | Phase 4 | 8 | Plugin-Versioning | 20 | 2,5 |
 | Phase 5 | 6 | Marketplace-Vorbereitung | 42 | 5 |
-| **Gesamt** | | | **129** | **16** |
+| Phase 6 | — | Manifest-Anpassung & Konsolidierung | 20 | 2,5 |
 | **Gesamt** | | | **149** | **~19** |
 **Wichtig:** Jede Phase ist unabhängig funktionsfähig. Das System läuft nach jeder Phase ohne Einschränkungen weiter.
@@ -645,6 +658,182 @@ async def _quarantine_plugin(zip_path: Path) -> Path:
 ---
 ## Phase 6: Manifest-Anpassung & Konsolidierung
 **Ziel:** Alle in Phase 4 und 5 definierten Manifest-Felder werden ins `PluginManifest` integriert, bestehende Manifeste aktualisiert, und das Manifest-System finalisiert.
 **Wichtig:** Diese Phase baut auf Phase 4 (Versioning) und Phase 5 (Marketplace) auf und muss als letztes durchgeführt werden.
 ### 6.1 PluginManifest erweitern (4 Std)
 **Aktuelles Manifest (verifiziert 2026-07-26):**
 ```python
 class PluginManifest(BaseModel):
    name: str
    version: str
    display_name: str
    description: str
    dependencies: list[str]
    routes: list[PluginRouteDef]
    events: list[str]
    migrations: list[str]
    permissions: list[str]
    is_core: bool
    field_definitions: list[FieldDefinition]
    agent_capabilities: list[str]
    menu_items: list[FrontendMenuItem]
    page_routes: list[FrontendPageRoute]
    detail_tabs: list[FrontendDetailTab]
    settings_pages: list[FrontendSettingsPage]
    dashboard_widgets: list[FrontendDashboardWidget]
    agent_definitions: list[AgentDefinitionContribution]
    automation_templates: list[AutomationTemplateContribution]
    cron_jobs: list[CronJobContribution]
    heartbeat_configs: list[HeartbeatConfigContribution]
    miniapps: list[MiniAppContribution]
    custom_fields: list[CustomFieldDefinition]
    model_config = {"extra": "forbid"}
 ```
 **Neue Felder hinzufügen:**
 ```python
 class PluginManifest(BaseModel):
    # ... alle bestehenden Felder ...
    # ── Versioning (Phase 4) ──
    min_app_version: str = Field(
        default="0.0.0",
        description="Minimum LeoCRM version required (SemVer)"
    )
    # ── Marketplace (Phase 5) ──
    author: str = Field(default="", max_length=200, description="Plugin author name")
    author_email: str = Field(default="", max_length=200, description="Author contact email")
    homepage: str = Field(default="", max_length=500, description="Plugin homepage URL")
    license: str = Field(default="MIT", max_length=50, description="License identifier")
    icon: str = Field(default="", description="Icon URL or emoji")
    screenshots: list[str] = Field(default_factory=list, description="Screenshot URLs for marketplace")
    changelog: str = Field(default="", description="Changelog URL or inline text")
    marketplace_tags: list[str] = Field(default_factory=list, description="Marketplace category tags")
    price: float = Field(default=0.0, ge=0.0, description="Price (0 = free)")
    # ── Hooks (Phase 2) ──
    hooks: list[str] = Field(
        default_factory=list,
        description="Hook names this plugin registers (e.g. 'contact.before_create')"
    )
    # ── Contracts (Phase 1) ──
    contract_version: str = Field(
        default="1.0.0",
        description="Contract API version this plugin exposes"
    )
 ```
 ### 6.2 Manifest-Schema-Dokumentation aktualisieren (3 Std)
 **`MANIFEST_SCHEMA_DOC` in `manifest.py` erweitern:**
 - Alle neuen Felder in `fields`-Dict aufnehmen
 - `example`-Manifest mit neuen Feldern aktualisieren
 - API-Endpoint `GET /api/v1/plugins/manifest` liefert vollständiges Schema
 ### 6.3 Alle 19 Plugin-Manifeste aktualisieren (8 Std)
 Jedes Plugin-Manifest muss um die neuen Felder erweitert werden:
 | # | Plugin | Aufwand | Neue Felder |
 |---|---|---|---|
 | 1 | `ai_assistant` | 30 Min | author, min_app_version, hooks, contract_version |
 | 2 | `ai_proactive` | 30 Min | author, min_app_version, hooks, contract_version |
 | 3 | `ai_ui_control` | 20 Min | author, min_app_version, contract_version |
 | 4 | `automation` | 30 Min | author, min_app_version, hooks, contract_version |
 | 5 | `calendar` | 20 Min | author, min_app_version, hooks, contract_version |
 | 6 | `dms` | 20 Min | author, min_app_version, hooks, contract_version |
 | 7 | `entity_links` | 15 Min | author, min_app_version, contract_version |
 | 8 | `forgejo_error_reporter` | 15 Min | author, min_app_version, contract_version |
 | 9 | `kommunikation` | 30 Min | author, min_app_version, hooks, contract_version |
 | 10 | `mail` | 20 Min | author, min_app_version, hooks, contract_version |
 | 11 | `mcp_client` | 20 Min | author, min_app_version, contract_version |
 | 12 | `mcp_server` | 20 Min | author, min_app_version, contract_version |
 | 13 | `permissions` | 20 Min | author, min_app_version, contract_version |
 | 14 | `report_generator` | 20 Min | author, min_app_version, contract_version |
 | 15 | `system_notif` | 15 Min | author, min_app_version, contract_version |
 | 16 | `tags` | 15 Min | author, min_app_version, contract_version |
 | 17 | `tasks` | 20 Min | author, min_app_version, hooks, contract_version |
 | 18 | `test_sample` | 10 Min | author, min_app_version, contract_version |
 | 19 | `unified_search` | 20 Min | author, min_app_version, hooks, contract_version |
 **Muster für Aktualisierung:**
 ```python
 # VORHER:
 manifest = PluginManifest(
    name="calendar",
    version="1.0.0",
    display_name="Calendar",
    ...
 )
 # NACHHER:
 manifest = PluginManifest(
    name="calendar",
    version="1.0.0",
    display_name="Calendar",
    # ... bestehende Felder ...
    # ── Neue Felder ──
    min_app_version="1.0.0",
    author="LeoCRM Team",
    license="MIT",
    hooks=["calendar.before_appointment", "calendar.after_appointment"],
    contract_version="1.0.0",
 )
 ```
 ### 6.4 Frontend Plugin-Manifest-Typen aktualisieren (2 Std)
 **`frontend/src/api/pluginManifests.ts` und `frontend/src/types/automation.ts`:**
 - TypeScript-Interfaces um neue Manifest-Felder erweitern
 - `PluginManifestResponse`-Typ aktualisieren
 - Frontend-Komponenten die Manifest-Felder anzeigen erweitern
 ### 6.5 Manifest-Validierung verschärfen (3 Std)
 **Neue Validierungsregeln in `PluginManifest`:**
 ```python
@field_validator("min_app_version")
@classmethod
 def validate_min_app_version(cls, v: str) -> str:
    """Validate SemVer format."""
    from app.plugins.semver import SemVer
    SemVer.parse(v)  # Raises ValueError if invalid
    return v
@field_validator("hooks")
@classmethod
 def validate_hooks(cls, v: list[str]) -> list[str]:
    """Validate hook names follow namespace.pattern."""
    for hook in v:
        if not re.match(r"^[a-z_]+\.[a-z_]+$", hook):
            raise ValueError(f"Invalid hook name '{hook}': must be 'namespace.action'")
    return v
 ```
 ### 6.6 Tests für erweitertes Manifest (3 Std)
 - `test_manifest.py` — Neue Felder validieren
 - `test_manifest_validation.py` — SemVer-Validierung, Hook-Name-Validierung
 - Alle Plugin-Tests: Manifest mit neuen Feldern erstellen
 - Frontend-Tests: Manifest mit neuen Feldern rendern
 ### Meilenstein Phase 6:
 - ✅ `PluginManifest` hat alle neuen Felder (min_app_version, author, hooks, contract_version, etc.)
 - ✅ `MANIFEST_SCHEMA_DOC` ist vollständig aktualisiert
 - ✅ Alle 19 Plugin-Manifeste haben die neuen Felder
 - ✅ Frontend-Typen sind aktualisiert
 - ✅ Manifest-Validierung ist verschärft
 - ✅ Tests bestanden
 ---
 ## Zeitplan
 ```
@@ -654,7 +843,8 @@ Woche 2 (Tag 6-8):  Phase 1 — Contracts (Teil 2: Deaktivierung + Tests)
 Woche 3 (Tag 11):   Phase 3 — Plugin-Isolation
         (Tag 12-14): Phase 4 — Plugin-Versioning
 Woche 4 (Tag 15-19): Phase 5 — Marketplace-Vorbereitung
-         (Tag 20):   Puffer / Bugfixes / Doku
+Woche 5 (Tag 20-22): Phase 6 — Manifest-Anpassung & Konsolidierung
         (Tag 23):   Puffer / Bugfixes / Doku
 ```
 ### Abhängigkeiten
@@ -666,6 +856,8 @@ Phase 1 (Contracts) ──→ Phase 3 (Isolation: Linting braucht Contracts als
         └──→ Phase 4 (Versioning: braucht Contracts für min_app_version)
                  │
                  └──→ Phase 5 (Marketplace: braucht alles)
                           │
                           └──→ Phase 6 (Manifest: braucht Phase 4 + 5 Felder)
 ```
 ### Parallelisierungsmöglichkeiten
@@ -673,6 +865,7 @@ Phase 1 (Contracts) ──→ Phase 3 (Isolation: Linting braucht Contracts als
 - Phase 3 kann erst nach Phase 1 starten
 - Phase 4 kann nach Phase 1 starten
 - Phase 5 kann erst nach Phase 1+4 starten
 - Phase 6 kann erst nach Phase 4+5 starten (braucht deren Manifest-Felder)
 ---
@@ -707,6 +900,10 @@ Nach Abschluss aller 5 Phasen:
 13. ✅ **Externe Plugin-Discovery** funktioniert
 14. ✅ **Alle Tests bestanden**
 15. ✅ **Built-in Plugins laufen ohne Marketplace**
 16. ✅ **PluginManifest hat alle neuen Felder** (min_app_version, author, hooks, contract_version, etc.)
 17. ✅ **Alle 19 Plugin-Manifeste aktualisiert** mit neuen Feldern
 18. ✅ **Manifest-Validierung verschärft** (SemVer, Hook-Names)
 19. ✅ **Frontend-Typen aktualisiert** für neue Manifest-Felder
 ---
@@ -0,0 +1,40 @@
 """Create plugin_allowlist table for authorized external plugins.
 Revision ID: 0046
 Revises: 0045
 Create Date: 2026-07-26
 """
 from alembic import op
 import sqlalchemy as sa
 from sqlalchemy.dialects.postgresql import UUID as PGUUID
 revision = "0046"
 down_revision = "0045"
 branch_labels = None
 depends_on = None
 def upgrade():
    op.create_table(
        "plugin_allowlist",
        sa.Column("id", PGUUID(as_uuid=True), primary_key=True, server_default=sa.text("gen_random_uuid()")),
        sa.Column("plugin_name", sa.String(80), nullable=False),
        sa.Column("allowed_hash", sa.String(64), nullable=True),
        sa.Column("allowed_signature", sa.Text, nullable=True),
        sa.Column("public_key", sa.Text, nullable=True),
        sa.Column("added_by", PGUUID(as_uuid=True), sa.ForeignKey("users.id", ondelete="SET NULL"), nullable=True),
        sa.Column("is_active", sa.Boolean, nullable=False, server_default=sa.text("true")),
        sa.Column("notes", sa.Text, nullable=True),
        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.func.now()),
        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.func.now()),
        sa.Column("deleted_at", sa.DateTime(timezone=True), nullable=True),
    )
    op.create_index("ix_plugin_allowlist_plugin_name", "plugin_allowlist", ["plugin_name"])
    op.create_index("ix_plugin_allowlist_hash", "plugin_allowlist", ["allowed_hash"])
 def downgrade():
    op.drop_index("ix_plugin_allowlist_hash", table_name="plugin_allowlist")
    op.drop_index("ix_plugin_allowlist_plugin_name", table_name="plugin_allowlist")
    op.drop_table("plugin_allowlist")
@@ -0,0 +1,177 @@
 """WordPress-style hooks: actions (fire-and-forget) and filters (modify data).
 Actions are fire-and-forget event callbacks with no return value.
 Filters chain-modify a value through one or more callbacks, returning the result.
 Usage in services::
    from app.core.hooks import do_action, apply_filters
    # Action — no return value, side effects only
    await do_action("contact.before_create", contact_data, db=db)
    # Filter — returns modified value
    display_name = await apply_filters("contact.format_display_name", contact.name)
 Usage in plugins (on_activate)::
    from app.core.hooks import get_hook_registry
    async def on_activate(self, db, service_container, event_bus):
        await super().on_activate(db, service_container, event_bus)
        reg = get_hook_registry()
        reg.register_action("contact.before_create", self._on_contact_create, priority=10)
        reg.register_filter("contact.format_display_name", self._format_name, priority=10)
 Priority: lower numbers run first (default=10).
 """
 from __future__ import annotations
 import logging
 from collections import defaultdict
 from typing import Any, Callable
 logger = logging.getLogger(__name__)
 class HookRegistry:
    """Central registry for actions and filters.
    Actions: ``do_action('contact.before_create', data)`` — no return value.
    Filters: ``result = apply_filters('contact.format_name', name)`` — returns modified value.
    Priority: lower numbers run first (default=10).
    """
    _instance: HookRegistry | None = None
    def __new__(cls) -> HookRegistry:
        if cls._instance is None:
            cls._instance = super().__new__(cls)
            cls._instance._actions: dict[str, list[tuple[int, Callable]]] = defaultdict(list)
            cls._instance._filters: dict[str, list[tuple[int, Callable]]] = defaultdict(list)
        return cls._instance
    # ─── Registration ───
    def register_action(self, hook_name: str, callback: Callable, priority: int = 10) -> None:
        """Register an action callback for *hook_name*."""
        self._actions[hook_name].append((priority, callback))
        self._actions[hook_name].sort(key=lambda x: x[0])
        logger.debug("Action registered: %s (priority=%d)", hook_name, priority)
    def register_filter(self, hook_name: str, callback: Callable, priority: int = 10) -> None:
        """Register a filter callback for *hook_name*."""
        self._filters[hook_name].append((priority, callback))
        self._filters[hook_name].sort(key=lambda x: x[0])
        logger.debug("Filter registered: %s (priority=%d)", hook_name, priority)
    # ─── Unregistration ───
    def unregister(self, hook_name: str, callback: Callable) -> None:
        """Remove a specific callback from both actions and filters."""
        self._actions[hook_name] = [
            (p, c) for p, c in self._actions.get(hook_name, []) if c != callback
        ]
        self._filters[hook_name] = [
            (p, c) for p, c in self._filters.get(hook_name, []) if c != callback
        ]
        if not self._actions[hook_name]:
            self._actions.pop(hook_name, None)
        if not self._filters[hook_name]:
            self._filters.pop(hook_name, None)
    def unregister_all_for_plugin(self, plugin_name: str) -> None:
        """Remove all hooks whose callback belongs to a plugin.
        This uses a heuristic: callbacks that are bound methods of a plugin
        instance have ``__self__`` whose ``manifest.name`` matches.
        Free functions are skipped (not plugin-owned).
        """
        for hook_dict in (self._actions, self._filters):
            for hook_name in list(hook_dict.keys()):
                kept: list[tuple[int, Callable]] = []
                for priority, callback in hook_dict[hook_name]:
                    owner = getattr(callback, "__self__", None)
                    plugin_manifest_name = getattr(getattr(owner, "manifest", None), "name", None)
                    if plugin_manifest_name == plugin_name:
                        logger.debug("Unregistered hook %s for plugin %s", hook_name, plugin_name)
                        continue
                    kept.append((priority, callback))
                if kept:
                    hook_dict[hook_name] = kept
                else:
                    hook_dict.pop(hook_name, None)
    # ─── Execution ───
    async def do_action(self, hook_name: str, *args: Any, **kwargs: Any) -> None:
        """Execute all action callbacks for *hook_name* in priority order."""
        for _, callback in self._actions.get(hook_name, []):
            try:
                result = callback(*args, **kwargs)
                if hasattr(result, "__await__"):
                    await result
            except Exception:
                logger.exception("Error in action %s", hook_name)
    async def apply_filters(self, hook_name: str, value: Any, *args: Any, **kwargs: Any) -> Any:
        """Pass *value* through all filter callbacks for *hook_name* in priority order."""
        for _, callback in self._filters.get(hook_name, []):
            try:
                result = callback(value, *args, **kwargs)
                if hasattr(result, "__await__"):
                    result = await result
                value = result
            except Exception:
                logger.exception("Error in filter %s", hook_name)
        return value
    # ─── Introspection ───
    def list_actions(self) -> list[str]:
        """Return all registered action hook names."""
        return sorted(self._actions.keys())
    def list_filters(self) -> list[str]:
        """Return all registered filter hook names."""
        return sorted(self._filters.keys())
    def has_action(self, hook_name: str) -> bool:
        return bool(self._actions.get(hook_name))
    def has_filter(self, hook_name: str) -> bool:
        return bool(self._filters.get(hook_name))
    # ─── Testing ───
    def _reset_for_testing(self) -> None:
        """Clear all state — for unit tests only."""
        self._actions.clear()
        self._filters.clear()
 # ─── Module-level helpers ───
 def get_hook_registry() -> HookRegistry:
    """Return the global :class:`HookRegistry` singleton."""
    return HookRegistry()
 async def do_action(hook_name: str, *args: Any, **kwargs: Any) -> None:
    """Execute all action callbacks for *hook_name*."""
    await get_hook_registry().do_action(hook_name, *args, **kwargs)
 async def apply_filters(hook_name: str, value: Any, *args: Any, **kwargs: Any) -> Any:
    """Pass *value* through all filter callbacks for *hook_name*."""
    return await get_hook_registry().apply_filters(hook_name, value, *args, **kwargs)
 def reset_hook_registry_for_testing() -> HookRegistry:
    """Return a fresh singleton — for unit tests only."""
    reg = get_hook_registry()
    reg._reset_for_testing()
    return reg
@@ -0,0 +1,37 @@
 """Plugin allowlist model — tracks authorized external plugins."""
 from __future__ import annotations
 import uuid
 from datetime import datetime
 from sqlalchemy import Boolean, DateTime, ForeignKey, String, Text, func
 from sqlalchemy.dialects.postgresql import UUID as PGUUID
 from sqlalchemy.orm import Mapped, mapped_column
 from app.core.db import Base, TimestampMixin
 class PluginAllowlist(Base, TimestampMixin):
    """Allowlist entry for an authorized external plugin.
    Only plugins whose hash or signature matches an allowlist entry
    can be installed from external sources.
    """
    __tablename__ = "plugin_allowlist"
    id: Mapped[uuid.UUID] = mapped_column(
        PGUUID(as_uuid=True), primary_key=True, default=uuid.uuid4
    )
    plugin_name: Mapped[str] = mapped_column(String(80), nullable=False, index=True)
    allowed_hash: Mapped[str | None] = mapped_column(String(64), nullable=True, index=True)
    allowed_signature: Mapped[str | None] = mapped_column(Text, nullable=True)
    public_key: Mapped[str | None] = mapped_column(Text, nullable=True)
    added_by: Mapped[uuid.UUID | None] = mapped_column(
        PGUUID(as_uuid=True), ForeignKey("users.id", ondelete="SET NULL"), nullable=True
    )
    is_active: Mapped[bool] = mapped_column(
        Boolean, nullable=False, default=True, server_default="true"
    )
    notes: Mapped[str | None] = mapped_column(Text, nullable=True)
@@ -68,12 +68,18 @@ class BasePlugin(ABC):
        """Called when the plugin is deactivated.
        Override to clean up runtime state. Default implementation unsubscribes
-        all event listeners that were registered during activation.
+        all event listeners and hooks that were registered during activation.
        """
        # Unsubscribe event listeners
        for event_name, handler in self._event_handlers.items():
            event_bus.unsubscribe(event_name, handler)
        self._event_handlers.clear()
        # Unregister all hooks owned by this plugin
        from app.core.hooks import get_hook_registry
        get_hook_registry().unregister_all_for_plugin(self.manifest.name)
    async def on_uninstall(self, db: AsyncSession, service_container: ServiceContainer) -> None:
        """Called when the plugin is uninstalled (before data tables are dropped).
@@ -49,6 +49,10 @@ class AIAssistantPlugin(BasePlugin):
        settings_pages=[
            FrontendSettingsPage(path='ai', label_key='settings.ai', label='AI Settings', component='@/pages/AISettings', icon='Bot', order=60),
        ],
        author="LeoCRM Team",
        min_app_version="1.0.0",
        hooks=["contact.after_create", "contact.after_update"],
        contract_version="1.0.0",
    )
    def __init__(self) -> None:
@@ -111,6 +115,10 @@ class AIAssistantPlugin(BasePlugin):
    async def on_deactivate(self, db, service_container, event_bus) -> None:
        """Deactivate plugin: unregister participant and event subscriptions."""
        # Contract abmelden
        from app.plugins.builtins.contracts import get_contract_registry
        get_contract_registry().unregister(self.manifest.name)
        # Unregister from participant registry
        try:
            from app.plugins.builtins.kommunikation.contracts import (
@@ -0,0 +1,80 @@
 """Public contract for the ai_proactive plugin.
 Exposes models, services, and job functions that other builtins plugins may need.
 """
 from __future__ import annotations
 from app.plugins.builtins.contracts import get_contract_registry
 from app.plugins.builtins.ai_proactive.models import (
    ContextLog,
    ProactiveSettings,
    ProactiveSuggestion,
 )
 from app.plugins.builtins.ai_proactive.services import (
    get_active_suggestions,
    get_sse_queue,
    get_stats,
    get_user_settings,
    handle_context_change,
    mark_dismissed,
    push_suggestion,
 )
 from app.plugins.builtins.ai_proactive.context_tools import (
    register_context_tools,
 )
 from app.plugins.builtins.ai_proactive.jobs import (
    deep_analysis,
    heartbeat,
 )
 class AiProactiveContract:
    """Public API surface for the ai_proactive plugin."""
    contract_name = "ai_proactive"
    # ─── models ───
    ProactiveSuggestion = ProactiveSuggestion
    ContextLog = ContextLog
    ProactiveSettings = ProactiveSettings
    # ─── services ───
    handle_context_change = staticmethod(handle_context_change)
    get_active_suggestions = staticmethod(get_active_suggestions)
    get_sse_queue = staticmethod(get_sse_queue)
    get_stats = staticmethod(get_stats)
    get_user_settings = staticmethod(get_user_settings)
    mark_dismissed = staticmethod(mark_dismissed)
    push_suggestion = staticmethod(push_suggestion)
    # ─── context_tools ───
    register_context_tools = staticmethod(register_context_tools)
    # ─── jobs ───
    deep_analysis = staticmethod(deep_analysis)
    heartbeat = staticmethod(heartbeat)
 # ─── self-registration ───
 _contract = AiProactiveContract()
 get_contract_registry().register("ai_proactive", _contract)
 __all__ = [
    "AiProactiveContract",
    "ProactiveSuggestion",
    "ContextLog",
    "ProactiveSettings",
    "handle_context_change",
    "get_active_suggestions",
    "get_sse_queue",
    "get_stats",
    "get_user_settings",
    "mark_dismissed",
    "push_suggestion",
    "register_context_tools",
    "deep_analysis",
    "heartbeat",
 ]
@@ -46,6 +46,10 @@ class AIProactivePlugin(BasePlugin):
        settings_pages=[
            FrontendSettingsPage(path='ai-proactive', label_key='settings.aiProactive', label='Proactive AI', component='@/pages/ProactiveAISettings', icon='Sparkles', order=61),
        ],
        author="LeoCRM Team",
        min_app_version="1.0.0",
        hooks=["contact.after_create", "mail.after_send"],
        contract_version="1.0.0",
    )
    def __init__(self) -> None:
@@ -85,6 +89,10 @@ class AIProactivePlugin(BasePlugin):
    async def on_deactivate(self, db, service_container, event_bus) -> None:
        """Unregister tools, event listeners, and participant."""
        # Contract abmelden
        from app.plugins.builtins.contracts import get_contract_registry
        get_contract_registry().unregister(self.manifest.name)
        # Unregister from participant registry
        try:
            from app.plugins.builtins.kommunikation.contracts import (
@@ -0,0 +1,51 @@
 """Public contract for the ai_ui_control plugin.
 Exposes the WebSocket manager and UI command schemas for other plugins.
 """
 from __future__ import annotations
 from app.plugins.builtins.contracts import get_contract_registry
 from app.plugins.builtins.ai_ui_control.websocket_manager import AIUIControlWSManager
 from app.plugins.builtins.ai_ui_control.schemas import (
    UICommand,
    UICommandCreate,
    UICommandFeedback,
    UICommandResponse,
    UICommandStatus,
    UICommandStatusResponse,
    UICommandType,
 )
 class AiUiControlContract:
    """Public API surface for the ai_ui_control plugin."""
    contract_name = "ai_ui_control"
    # ─── websocket_manager ───
    AIUIControlWSManager = AIUIControlWSManager
    # ─── schemas ───
    UICommand = UICommand
    UICommandCreate = UICommandCreate
    UICommandFeedback = UICommandFeedback
    UICommandResponse = UICommandResponse
    UICommandStatus = UICommandStatus
    UICommandStatusResponse = UICommandStatusResponse
    UICommandType = UICommandType
 # ─── self-registration ───
 _contract = AiUiControlContract()
 get_contract_registry().register("ai_ui_control", _contract)
 __all__ = [
    "AiUiControlContract",
    "AIUIControlWSManager",
    "UICommand",
    "UICommandType",
    "UICommandStatus",
 ]
@@ -42,6 +42,9 @@ class AIUIControlPlugin(BasePlugin):
            "ai_ui_control:write",
        ],
        is_core=True,
        author="LeoCRM Team",
        min_app_version="1.0.0",
        contract_version="1.0.0",
    )
    async def on_activate(self, db, service_container, event_bus) -> None:
@@ -55,6 +58,10 @@ class AIUIControlPlugin(BasePlugin):
    async def on_deactivate(self, db, service_container, event_bus) -> None:
        """Clean up the WebSocket manager."""
        # Contract abmelden
        from app.plugins.builtins.contracts import get_contract_registry
        get_contract_registry().unregister(self.manifest.name)
        await super().on_deactivate(db, service_container, event_bus)
        if service_container.has("ai_ui_control_ws"):
            service_container.remove("ai_ui_control_ws")
@@ -0,0 +1,82 @@
 """Public contract for the automation plugin.
 Exposes models, services, scheduler, and agent communication for other plugins.
 """
 from __future__ import annotations
 from app.plugins.builtins.contracts import get_contract_registry
 from app.plugins.builtins.automation.models import (
    AgentDefinition,
    AgentRun,
    AgentVersion,
    AutomationCronJob,
    AutomationDefinition,
    AutomationRun,
    AutomationVersion,
 )
 from app.plugins.builtins.automation.services import (
    AgentService,
    AutomationService,
    CronJobService,
    RunLogService,
 )
 from app.plugins.builtins.automation.agent_runner import run_agent
 from app.plugins.builtins.automation.execution_engine import run_automation
 from app.plugins.builtins.automation.scheduler import (
    calculate_next_run,
    scheduler_tick,
 )
 from app.plugins.builtins.automation.agent_comm import send_agent_message
 class AutomationContract:
    """Public API surface for the automation plugin."""
    contract_name = "automation"
    # ─── models ───
    AgentDefinition = AgentDefinition
    Automation = AutomationDefinition
    CronJob = AutomationCronJob
    AgentRun = AgentRun
    AgentVersion = AgentVersion
    AutomationRun = AutomationRun
    AutomationVersion = AutomationVersion
    # ─── services ───
    AgentService = AgentService
    AutomationService = AutomationService
    CronJobService = CronJobService
    RunLogService = RunLogService
    # ─── agent_runner ───
    run_agent = staticmethod(run_agent)
    # ─── execution_engine ───
    run_automation = staticmethod(run_automation)
    # ─── scheduler ───
    calculate_next_run = staticmethod(calculate_next_run)
    scheduler_tick = staticmethod(scheduler_tick)
    # ─── agent_comm ───
    send_agent_message = staticmethod(send_agent_message)
 # ─── self-registration ───
 _contract = AutomationContract()
 get_contract_registry().register("automation", _contract)
 __all__ = [
    "AutomationContract",
    "AgentDefinition",
    "Automation",
    "CronJob",
    "AgentService",
    "AutomationService",
    "CronJobService",
    "RunLogService",
 ]
@@ -162,6 +162,10 @@ class AutomationPlugin(BasePlugin):
                plugin_name="automation",
            ),
        ],
        author="LeoCRM Team",
        min_app_version="1.0.0",
        hooks=["contact.before_create", "contact.after_create"],
        contract_version="1.0.0",
    )
    def __init__(self) -> None:
@@ -207,6 +211,10 @@ class AutomationPlugin(BasePlugin):
    async def on_deactivate(self, db, service_container, event_bus) -> None:
        """Clean up on deactivation."""
        # Contract abmelden
        from app.plugins.builtins.contracts import get_contract_registry
        get_contract_registry().unregister(self.manifest.name)
        await super().on_deactivate(db, service_container, event_bus)
        # Unregister agent communication tool
        try:
@@ -2,17 +2,26 @@
 from __future__ import annotations
 from app.plugins.builtins.contracts import get_contract_registry
 from app.plugins.builtins.calendar.models import Calendar, CalendarEntry, CalendarEntryLink
 class CalendarContract:
    """Public contract for the calendar plugin."""
    contract_name = "calendar"
    Calendar = Calendar
    CalendarEntry = CalendarEntry
    CalendarEntryLink = CalendarEntryLink
 # ─── self-registration ───
 _contract = CalendarContract()
 get_contract_registry().register("calendar", _contract)
 # Backward-compatible local accessor
 _contract_instance: CalendarContract | None = None
@@ -21,3 +30,6 @@ def get_contract() -> CalendarContract:
    if _contract_instance is None:
        _contract_instance = CalendarContract()
    return _contract_instance
 __all__ = ["CalendarContract", "Calendar", "CalendarEntry", "CalendarEntryLink"]
@@ -50,4 +50,17 @@ class CalendarPlugin(BasePlugin):
        detail_tabs=[
            FrontendDetailTab(entity_type='contact', label_key='tabs.calendar', label='Calendar', component='@/components/contact/ContactCalendarTab', icon='Calendar', order=30, permission='calendar:read'),
        ],
        author="LeoCRM Team",
        min_app_version="1.0.0",
        hooks=["calendar.before_appointment", "calendar.after_appointment"],
        contract_version="1.0.0",
    )
    async def on_deactivate(
        self, db, service_container, event_bus
    ) -> None:
        """Deactivate plugin: unregister contract and event listeners."""
        # Contract abmelden
        from app.plugins.builtins.contracts import get_contract_registry
        get_contract_registry().unregister(self.manifest.name)
        await super().on_deactivate(db, service_container, event_bus)
@@ -410,6 +410,11 @@ async def create_entry(
            )
    assigned_to = _parse_uuid(body.assigned_to, "assigned_to") if body.assigned_to else None
    # ── Hook: calendar.before_appointment (Action) ──
    from app.core.hooks import do_action
    await do_action("calendar.before_appointment", body=body, tenant_id=tenant_id, user_id=user_id, cal_id=cal_id)
    entry = CalendarEntry(
        tenant_id=tenant_id,
        calendar_id=cal_id,
@@ -432,6 +437,10 @@ async def create_entry(
    db.add(entry)
    await db.flush()
    # ── Hook: calendar.after_appointment (Action) ──
    from app.core.hooks import do_action
    await do_action("calendar.after_appointment", entry_id=str(entry.id), tenant_id=tenant_id, user_id=user_id)
    # Schedule reminder ARQ job if reminder is set
    if body.reminder:
        try:
@@ -2,16 +2,25 @@
 from __future__ import annotations
 from app.plugins.builtins.contracts import get_contract_registry
 from app.plugins.builtins.dms.models import File as DmsFile, Folder
 class DmsContract:
    """Public contract for the DMS plugin."""
    contract_name = "dms"
    DmsFile = DmsFile
    Folder = Folder
 # ─── self-registration ───
 _contract = DmsContract()
 get_contract_registry().register("dms", _contract)
 # Backward-compatible local accessor
 _contract_instance: DmsContract | None = None
@@ -20,3 +29,6 @@ def get_contract() -> DmsContract:
    if _contract_instance is None:
        _contract_instance = DmsContract()
    return _contract_instance
 __all__ = ["DmsContract", "DmsFile", "Folder"]
@@ -42,4 +42,17 @@ class DmsPlugin(BasePlugin):
        detail_tabs=[
            FrontendDetailTab(entity_type='contact', label_key='tabs.files', label='Dateien', component='@/components/contact/ContactFilesTab', icon='FolderOpen', order=40, permission='dms:read'),
        ],
        author="LeoCRM Team",
        min_app_version="1.0.0",
        hooks=["dms.before_upload"],
        contract_version="1.0.0",
    )
    async def on_deactivate(
        self, db, service_container, event_bus
    ) -> None:
        """Deactivate plugin: unregister contract and event listeners."""
        # Contract abmelden
        from app.plugins.builtins.contracts import get_contract_registry
        get_contract_registry().unregister(self.manifest.name)
        await super().on_deactivate(db, service_container, event_bus)
@@ -35,7 +35,10 @@ from app.plugins.builtins.dms.schemas import (
    ShareRequest,
 )
 from app.plugins.builtins.permissions.contracts import get_contract as get_perms_contract
-from app.plugins.builtins.permissions.models import Permission  # TODO: migrate to contract
+
 # Get Permission model from the permissions contract
 _perms_contract = get_perms_contract()
 Permission = _perms_contract.Permission
 router = APIRouter(prefix="/api/v1/dms", tags=["dms"])
@@ -461,6 +464,14 @@ async def upload_file(
            sha256.update(chunk)
            yield chunk
    # ── Hook: dms.before_upload (Filter) — can modify filename ──
    from app.core.hooks import apply_filters
    upload_data = {
        "filename": file.filename or "unnamed",
        "mime_type": file.content_type or "application/octet-stream",
    }
    upload_data = await apply_filters("dms.before_upload", upload_data)
    # Create file record
    file_id = uuid.uuid4()
    storage_path = _file_storage_path(tenant_id, file_id)
@@ -471,12 +482,12 @@ async def upload_file(
    content_hash = sha256.hexdigest()
-    mime_type = file.content_type or "application/octet-stream"
+    mime_type = upload_data["mime_type"]
    dms_file = DmsFile(
        id=file_id,
        tenant_id=tenant_id,
-        name=file.filename or "unnamed",
+        name=upload_data["filename"],
        folder_id=fid,
        uploaded_by=user_id,
        mime_type=mime_type,
@@ -0,0 +1,38 @@
 """Public contract for the entity_links plugin.
 Exposes only the symbols that other builtins plugins need.
 Importers should use::
    from app.plugins.builtins.contracts import get_contract
    el = get_contract("entity_links")
    if el:
        # use el.EntityLink
 instead of importing from internal modules directly.
 """
 from __future__ import annotations
 from app.plugins.builtins.contracts import get_contract_registry
 from app.plugins.builtins.entity_links.models import EntityLink
 class EntityLinksContract:
    """Public API surface for the entity_links plugin."""
    contract_name = "entity_links"
    # ─── models (read-only for queries) ───
    EntityLink = EntityLink
 # ─── self-registration ───
 _contract = EntityLinksContract()
 get_contract_registry().register("entity_links", _contract)
 __all__ = [
    "EntityLinksContract",
    "EntityLink",
 ]
@@ -40,7 +40,10 @@ class EntityLinksPlugin(BasePlugin):
        detail_tabs=[
            FrontendDetailTab(entity_type='contact', label_key='tabs.links', label='Verknüpfungen', component='@/components/contact/ContactLinksTab', icon='Link', order=60, permission='entity_links:read'),
        ],
-    )
+    
        author="LeoCRM Team",
        min_app_version="1.0.0",
        contract_version="1.0.0")
    async def on_contact_deleted(self, payload: dict[str, Any]) -> None:
        """Handle contact.deleted event — remove all EntityLink rows for that contact."""
@@ -66,3 +69,12 @@ class EntityLinksPlugin(BasePlugin):
                )
            )
            await session.commit()
    async def on_deactivate(
        self, db, service_container, event_bus
    ) -> None:
        """Deactivate plugin: unregister contract and event listeners."""
        # Contract abmelden
        from app.plugins.builtins.contracts import get_contract_registry
        get_contract_registry().unregister(self.manifest.name)
        await super().on_deactivate(db, service_container, event_bus)
@@ -0,0 +1,43 @@
 """Public contract for the forgejo_error_reporter plugin.
 Exposes only the symbols that other builtins plugins need.
 Importers should use::
    from app.plugins.builtins.contracts import get_contract
    reporter = get_contract("forgejo_error_reporter")
    if reporter:
        await reporter.report_error_to_forgejo(entry)
 instead of importing from internal modules directly.
 """
 from __future__ import annotations
 from app.plugins.builtins.contracts import get_contract_registry
 from app.plugins.builtins.forgejo_error_reporter.models import ReportedError
 from app.plugins.builtins.forgejo_error_reporter.service import report_error_to_forgejo
 class ForgejoErrorReporterContract:
    """Public API surface for the forgejo_error_reporter plugin."""
    contract_name = "forgejo_error_reporter"
    # ─── services ───
    report_error_to_forgejo = staticmethod(report_error_to_forgejo)
    # ─── models (read-only for queries) ───
    ReportedError = ReportedError
 # ─── self-registration ───
 _contract = ForgejoErrorReporterContract()
 get_contract_registry().register("forgejo_error_reporter", _contract)
 __all__ = [
    "ForgejoErrorReporterContract",
    "report_error_to_forgejo",
    "ReportedError",
 ]
@@ -35,7 +35,10 @@ class ForgejoErrorReporterPlugin(BasePlugin):
                router_attr="router",
            ),
        ],
-    )
+    
        author="LeoCRM Team",
        min_app_version="1.0.0",
        contract_version="1.0.0")
    def __init__(self) -> None:
        super().__init__()
@@ -94,6 +97,10 @@ class ForgejoErrorReporterPlugin(BasePlugin):
    async def on_deactivate(self, db: Any, service_container: Any, event_bus: Any) -> None:
        """Deactivate the plugin."""
        # Contract abmelden
        from app.plugins.builtins.contracts import get_contract_registry
        get_contract_registry().unregister(self.manifest.name)
        self._enabled = False
        await super().on_deactivate(db, service_container, event_bus)
        logger.info("Forgejo Error Reporter deactivated")
@@ -55,6 +55,9 @@ class KommunikationPlugin(BasePlugin):
        page_routes=[
            FrontendPageRoute(path='/communication', component='@/pages/Communication', protected=True),
        ],
        author="LeoCRM Team",
        min_app_version="1.0.0",
        contract_version="1.0.0",
    )
    async def on_activate(self, db, service_container, event_bus) -> None:
@@ -125,6 +128,10 @@ class KommunikationPlugin(BasePlugin):
    async def on_deactivate(self, db, service_container, event_bus) -> None:
        """Clean up registries."""
        # Contract abmelden
        from app.plugins.builtins.contracts import get_contract_registry
        get_contract_registry().unregister(self.manifest.name)
        await super().on_deactivate(db, service_container, event_bus)
        logger.info("Kommunikation plugin deactivated")
@@ -69,6 +69,10 @@ class MailPlugin(BasePlugin):
        detail_tabs=[
            FrontendDetailTab(entity_type='contact', label_key='tabs.email', label='E-Mails', component='@/components/contact/ContactMailTab', icon='Mail', order=20, permission='mail:read'),
        ],
        author="LeoCRM Team",
        min_app_version="1.0.0",
        hooks=["mail.before_send", "mail.after_send"],
        contract_version="1.0.0",
    )
    async def on_activate(
@@ -100,6 +104,10 @@ class MailPlugin(BasePlugin):
        self, db, service_container, event_bus
    ) -> None:
        """Deactivate plugin: stop auto-sync task + unregister events."""
        # Contract abmelden
        from app.plugins.builtins.contracts import get_contract_registry
        get_contract_registry().unregister(self.manifest.name)
        if self._auto_sync_task is not None and not self._auto_sync_task.done():
            self._auto_sync_task.cancel()
            try:
@@ -1545,6 +1545,19 @@ async def send_mail_via_smtp(
            filename=filename,
        )
    # ── Hook: mail.before_send (Filter) ──
    from app.core.hooks import apply_filters
    mail_data = {
        "subject": subject,
        "body_html": body_html,
        "body_text": body_text,
        "to_addrs": to_addrs,
        "cc_addrs": cc_addrs,
        "bcc_addrs": bcc_addrs,
        "attachment_paths": attachment_paths,
    }
    mail_data = await apply_filters("mail.before_send", mail_data)
    # Send via SMTP
    password = await get_account_password(account)
    try:
@@ -1559,6 +1572,10 @@ async def send_mail_via_smtp(
        await smtp.send_message(msg, recipients=recipients)
        await smtp.quit()
        # ── Hook: mail.after_send (Action) ──
        from app.core.hooks import do_action
        await do_action("mail.after_send", mail_data, db=db, account=account, msg_id=msg_id)
        # Store sent mail in Sent folder — use configured mapping if set,
        # otherwise flexible lookup to handle different IMAP naming conventions
        if account.sent_folder_imap_name:
@@ -0,0 +1,47 @@
 """Public contract for the mcp_client plugin.
 Exposes the MCP client and server config model for other plugins.
 """
 from __future__ import annotations
 from app.plugins.builtins.contracts import get_contract_registry
 from app.plugins.builtins.mcp_client.models import McpServerConfig
 from app.plugins.builtins.mcp_client.client import McpClient
 from app.plugins.builtins.mcp_client.schemas import (
    McpServerExecuteRequest,
    McpServerExecuteResponse,
    McpServerToolInfo,
    McpServerToolsResponse,
 )
 class McpClientContract:
    """Public API surface for the mcp_client plugin."""
    contract_name = "mcp_client"
    # ─── models ───
    McpServerConfig = McpServerConfig
    # ─── client ───
    McpClient = McpClient
    # ─── schemas ───
    McpServerExecuteRequest = McpServerExecuteRequest
    McpServerExecuteResponse = McpServerExecuteResponse
    McpServerToolInfo = McpServerToolInfo
    McpServerToolsResponse = McpServerToolsResponse
 # ─── self-registration ───
 _contract = McpClientContract()
 get_contract_registry().register("mcp_client", _contract)
 __all__ = [
    "McpClientContract",
    "McpServerConfig",
    "McpClient",
 ]
@@ -29,4 +29,16 @@ class McpClientPlugin(BasePlugin):
            "mcp-client:write",
            "mcp-client:admin",
        ],
-    )
+    
        author="LeoCRM Team",
        min_app_version="1.0.0",
        contract_version="1.0.0")
    async def on_deactivate(
        self, db, service_container, event_bus
    ) -> None:
        """Deactivate plugin: unregister contract and event listeners."""
        # Contract abmelden
        from app.plugins.builtins.contracts import get_contract_registry
        get_contract_registry().unregister(self.manifest.name)
        await super().on_deactivate(db, service_container, event_bus)
@@ -0,0 +1,57 @@
 """Public contract for the mcp_server plugin.
 Exposes tool definitions and schemas for other plugins.
 """
 from __future__ import annotations
 from app.plugins.builtins.contracts import get_contract_registry
 from app.plugins.builtins.mcp_server.tool_definitions import (
    TOOL_DEFINITIONS,
    TOOL_HANDLERS,
    get_all_tool_names,
    get_tool_definition,
 )
 from app.plugins.builtins.mcp_server.schemas import (
    McpToolDefinition,
    McpToolExecuteRequest,
    McpToolExecuteResponse,
    McpToolListResponse,
    McpToolParameter,
    McpServerConfig,
 )
 class McpServerContract:
    """Public API surface for the mcp_server plugin."""
    contract_name = "mcp_server"
    # ─── tool_definitions ───
    ToolDefinitions = TOOL_DEFINITIONS
    ToolHandlers = TOOL_HANDLERS
    get_tool_definition = staticmethod(get_tool_definition)
    get_all_tool_names = staticmethod(get_all_tool_names)
    # ─── schemas ───
    McpToolDefinition = McpToolDefinition
    McpToolExecuteRequest = McpToolExecuteRequest
    McpToolExecuteResponse = McpToolExecuteResponse
    McpToolListResponse = McpToolListResponse
    McpToolParameter = McpToolParameter
    McpServerConfig = McpServerConfig
 # ─── self-registration ───
 _contract = McpServerContract()
 get_contract_registry().register("mcp_server", _contract)
 __all__ = [
    "McpServerContract",
    "ToolDefinitions",
    "McpToolDefinition",
    "McpToolParameter",
    "McpServerConfig",
 ]
@@ -28,4 +28,16 @@ class McpServerPlugin(BasePlugin):
            "mcp:read",
            "mcp:write",
        ],
-    )
+    
        author="LeoCRM Team",
        min_app_version="1.0.0",
        contract_version="1.0.0")
    async def on_deactivate(
        self, db, service_container, event_bus
    ) -> None:
        """Deactivate plugin: unregister contract and event listeners."""
        # Contract abmelden
        from app.plugins.builtins.contracts import get_contract_registry
        get_contract_registry().unregister(self.manifest.name)
        await super().on_deactivate(db, service_container, event_bus)
@@ -2,15 +2,25 @@
 from __future__ import annotations
-from app.plugins.builtins.permissions.models import Permission
+from app.plugins.builtins.contracts import get_contract_registry
 from app.plugins.builtins.permissions.models import Permission, ShareLink
 class PermissionsContract:
    """Public contract for the permissions plugin."""
    contract_name = "permissions"
    Permission = Permission
    ShareLink = ShareLink
 # ─── self-registration ───
 _contract = PermissionsContract()
 get_contract_registry().register("permissions", _contract)
 # Backward-compatible local accessor
 _contract_instance: PermissionsContract | None = None
@@ -19,3 +29,6 @@ def get_contract() -> PermissionsContract:
    if _contract_instance is None:
        _contract_instance = PermissionsContract()
    return _contract_instance
 __all__ = ["PermissionsContract", "Permission", "ShareLink"]
@@ -36,4 +36,16 @@ class PermissionsPlugin(BasePlugin):
            FrontendSettingsPage(path='users', label_key='settings.users', label='Users', component='@/pages/SettingsUsers', icon='Users', order=11, permission='permissions:read'),
            FrontendSettingsPage(path='groups', label_key='settings.groups', label='Groups', component='@/pages/SettingsGroups', icon='UsersRound', order=12, permission='permissions:read'),
        ],
        author="LeoCRM Team",
        min_app_version="1.0.0",
        contract_version="1.0.0",
    )
    async def on_deactivate(
        self, db, service_container, event_bus
    ) -> None:
        """Deactivate plugin: unregister contract and event listeners."""
        # Contract abmelden
        from app.plugins.builtins.contracts import get_contract_registry
        get_contract_registry().unregister(self.manifest.name)
        await super().on_deactivate(db, service_container, event_bus)
@@ -0,0 +1,57 @@
 """Public contract for the report_generator plugin.
 Exposes models and PDF generation functions for other plugins.
 """
 from __future__ import annotations
 from app.plugins.builtins.contracts import get_contract_registry
 from app.plugins.builtins.report_generator.models import (
    ReportInstance,
    ReportTemplate,
 )
 from app.plugins.builtins.report_generator.pdf_generator import (
    PRESET_META,
    PRESET_TEMPLATES,
    generate_pdf,
    generate_pdf_from_template_content,
    generate_preset_report,
    generate_print_pdf,
    get_preset_list,
    render_template_file,
    render_template_string,
 )
 class ReportGeneratorContract:
    """Public API surface for the report_generator plugin."""
    contract_name = "report_generator"
    # ─── models ───
    ReportTemplate = ReportTemplate
    ReportInstance = ReportInstance
    # ─── pdf_generator ───
    generate_pdf = staticmethod(generate_pdf)
    generate_print_pdf = staticmethod(generate_print_pdf)
    generate_preset_report = staticmethod(generate_preset_report)
    generate_pdf_from_template_content = staticmethod(generate_pdf_from_template_content)
    render_template_file = staticmethod(render_template_file)
    render_template_string = staticmethod(render_template_string)
    get_preset_list = staticmethod(get_preset_list)
    PRESET_META = PRESET_META
    PRESET_TEMPLATES = PRESET_TEMPLATES
 # ─── self-registration ───
 _contract = ReportGeneratorContract()
 get_contract_registry().register("report_generator", _contract)
 __all__ = [
    "ReportGeneratorContract",
    "ReportTemplate",
    "ReportInstance",
 ]
@@ -32,4 +32,16 @@ class ReportGeneratorPlugin(BasePlugin):
        page_routes=[
            FrontendPageRoute(path='/reports', component='@/pages/Reports', protected=True),
        ],
-    )
+    
        author="LeoCRM Team",
        min_app_version="1.0.0",
        contract_version="1.0.0")
    async def on_deactivate(
        self, db, service_container, event_bus
    ) -> None:
        """Deactivate plugin: unregister contract and event listeners."""
        # Contract abmelden
        from app.plugins.builtins.contracts import get_contract_registry
        get_contract_registry().unregister(self.manifest.name)
        await super().on_deactivate(db, service_container, event_bus)
@@ -0,0 +1,38 @@
 """Public contract for the system_notif plugin.
 Exposes only the symbols that other builtins plugins need.
 Importers should use::
    from app.plugins.builtins.contracts import get_contract
    sn = get_contract("system_notif")
    if sn:
        # use sn.SystemParticipantHandler
 instead of importing from internal modules directly.
 """
 from __future__ import annotations
 from app.plugins.builtins.contracts import get_contract_registry
 from app.plugins.builtins.system_notif.participant_handler import SystemParticipantHandler
 class SystemNotifContract:
    """Public API surface for the system_notif plugin."""
    contract_name = "system_notif"
    # ─── participant handler ───
    SystemParticipantHandler = SystemParticipantHandler
 # ─── self-registration ───
 _contract = SystemNotifContract()
 get_contract_registry().register("system_notif", _contract)
 __all__ = [
    "SystemNotifContract",
    "SystemParticipantHandler",
 ]
@@ -43,7 +43,10 @@ class SystemNotifPlugin(BasePlugin):
        settings_pages=[
            FrontendSettingsPage(path='notifications', label_key='settings.notifications', label='Notifications', component='@/pages/SettingsNotifications', icon='Bell', order=40),
        ],
-    )
+    
        author="LeoCRM Team",
        min_app_version="1.0.0",
        contract_version="1.0.0")
    def __init__(self) -> None:
        super().__init__()
@@ -64,6 +67,9 @@ class SystemNotifPlugin(BasePlugin):
    async def on_deactivate(self, db, service_container, event_bus) -> None:
        """Unregister participant."""
        # Contract abmelden
        from app.plugins.builtins.contracts import get_contract_registry
        get_contract_registry().unregister(self.manifest.name)
        from app.plugins.builtins.kommunikation.contracts import get_participant_registry
        get_participant_registry().unregister("system")
@@ -0,0 +1,40 @@
 """Public contract for the tags plugin.
 Exposes only the symbols that other builtins plugins need.
 Importers should use::
    from app.plugins.builtins.contracts import get_contract
    tags = get_contract("tags")
    if tags:
        # use tags.Tag, tags.TagAssignment
 instead of importing from internal modules directly.
 """
 from __future__ import annotations
 from app.plugins.builtins.contracts import get_contract_registry
 from app.plugins.builtins.tags.models import Tag, TagAssignment
 class TagsContract:
    """Public API surface for the tags plugin."""
    contract_name = "tags"
    # ─── models (read-only for queries) ───
    Tag = Tag
    TagAssignment = TagAssignment
 # ─── self-registration ───
 _contract = TagsContract()
 get_contract_registry().register("tags", _contract)
 __all__ = [
    "TagsContract",
    "Tag",
    "TagAssignment",
 ]
@@ -34,4 +34,16 @@ class TagsPlugin(BasePlugin):
        detail_tabs=[
            FrontendDetailTab(entity_type='contact', label_key='tabs.tags', label='Tags', component='@/components/contact/ContactTagsTab', icon='Tag', order=50, permission='tags:read'),
        ],
-    )
+    
        author="LeoCRM Team",
        min_app_version="1.0.0",
        contract_version="1.0.0")
    async def on_deactivate(
        self, db, service_container, event_bus
    ) -> None:
        """Deactivate plugin: unregister contract and event listeners."""
        # Contract abmelden
        from app.plugins.builtins.contracts import get_contract_registry
        get_contract_registry().unregister(self.manifest.name)
        await super().on_deactivate(db, service_container, event_bus)
@@ -0,0 +1,66 @@
 """Public contract for the tasks plugin.
 Exposes only the symbols that other builtins plugins need.
 Importers should use::
    from app.plugins.builtins.contracts import get_contract
    tasks = get_contract("tasks")
    if tasks:
        await tasks.create_task(db, tenant_id, user_id, data)
 instead of importing from internal modules directly.
 """
 from __future__ import annotations
 from app.plugins.builtins.contracts import get_contract_registry
 from app.plugins.builtins.tasks.models import Task
 from app.plugins.builtins.tasks.services import (
    assign_task,
    create_task,
    delete_task,
    get_due_tasks,
    get_task,
    list_tasks,
    update_task,
    update_task_status,
 )
 class TasksContract:
    """Public API surface for the tasks plugin."""
    contract_name = "tasks"
    # ─── services ───
    list_tasks = staticmethod(list_tasks)
    get_task = staticmethod(get_task)
    create_task = staticmethod(create_task)
    update_task = staticmethod(update_task)
    delete_task = staticmethod(delete_task)
    assign_task = staticmethod(assign_task)
    update_task_status = staticmethod(update_task_status)
    get_due_tasks = staticmethod(get_due_tasks)
    # ─── models (read-only for queries) ───
    Task = Task
 # ─── self-registration ───
 _contract = TasksContract()
 get_contract_registry().register("tasks", _contract)
 __all__ = [
    "TasksContract",
    "Task",
    "list_tasks",
    "get_task",
    "create_task",
    "update_task",
    "delete_task",
    "assign_task",
    "update_task_status",
    "get_due_tasks",
 ]
@@ -62,4 +62,17 @@ class TasksPlugin(BasePlugin):
                plugin_name="tasks",
            ),
        ],
-    )
+    
        author="LeoCRM Team",
        min_app_version="1.0.0",
        hooks=["contact.after_create"],
        contract_version="1.0.0")
    async def on_deactivate(
        self, db, service_container, event_bus
    ) -> None:
        """Deactivate plugin: unregister contract and event listeners."""
        # Contract abmelden
        from app.plugins.builtins.contracts import get_contract_registry
        get_contract_registry().unregister(self.manifest.name)
        await super().on_deactivate(db, service_container, event_bus)
@@ -21,7 +21,10 @@ class TestSamplePlugin(BasePlugin):
        events=["contact.created"],
        migrations=["0001_test_plugin.sql"],
        permissions=[],
-    )
+    
        author="LeoCRM Team",
        min_app_version="1.0.0",
        contract_version="1.0.0")
    def __init__(self) -> None:
        super().__init__()
@@ -39,6 +42,9 @@ class TestSamplePlugin(BasePlugin):
        await super().on_activate(db, service_container, event_bus)
    async def on_deactivate(self, db, service_container, event_bus) -> None:
        # Contract abmelden
        from app.plugins.builtins.contracts import get_contract_registry
        get_contract_registry().unregister(self.manifest.name)
        self.deactivate_called = True
        await super().on_deactivate(db, service_container, event_bus)
@@ -0,0 +1,38 @@
 """Public contract for the test_sample plugin.
 Exposes only the symbols that other builtins plugins need.
 Importers should use::
    from app.plugins.builtins.contracts import get_contract
    ts = get_contract("test_sample")
    if ts:
        # use ts.TestSamplePlugin
 instead of importing from internal modules directly.
 """
 from __future__ import annotations
 from app.plugins.builtins.contracts import get_contract_registry
 from app.plugins.builtins.test_sample import TestSamplePlugin
 class TestSampleContract:
    """Public API surface for the test_sample plugin."""
    contract_name = "test_sample"
    # ─── plugin class ───
    TestSamplePlugin = TestSamplePlugin
 # ─── self-registration ───
 _contract = TestSampleContract()
 get_contract_registry().register("test_sample", _contract)
 __all__ = [
    "TestSampleContract",
    "TestSamplePlugin",
 ]
@@ -2,6 +2,7 @@
 from __future__ import annotations
 from app.plugins.builtins.contracts import get_contract_registry
 from app.plugins.builtins.unified_search.embedding import generate_embedding
 from app.plugins.builtins.unified_search.search_engine import hybrid_search
@@ -9,10 +10,18 @@ from app.plugins.builtins.unified_search.search_engine import hybrid_search
 class UnifiedSearchContract:
    """Public contract for the unified_search plugin."""
    contract_name = "unified_search"
    generate_embedding = staticmethod(generate_embedding)
    hybrid_search = staticmethod(hybrid_search)
 # ─── self-registration ───
 _contract = UnifiedSearchContract()
 get_contract_registry().register("unified_search", _contract)
 # Backward-compatible local accessor
 _contract_instance: UnifiedSearchContract | None = None
@@ -21,3 +30,6 @@ def get_contract() -> UnifiedSearchContract:
    if _contract_instance is None:
        _contract_instance = UnifiedSearchContract()
    return _contract_instance
 __all__ = ["UnifiedSearchContract", "generate_embedding", "hybrid_search"]
@@ -43,6 +43,9 @@ class UnifiedSearchPlugin(BasePlugin):
        page_routes=[
            FrontendPageRoute(path='/search', component='@/pages/GlobalSearchResults', protected=True),
        ],
        author="LeoCRM Team",
        min_app_version="1.0.0",
        contract_version="1.0.0",
    )
    async def on_activate(self, db, service_container, event_bus) -> None:
@@ -59,6 +62,9 @@ class UnifiedSearchPlugin(BasePlugin):
    async def on_deactivate(self, db, service_container, event_bus) -> None:
        """Clear provider registry on deactivation."""
        # Contract abmelden
        from app.plugins.builtins.contracts import get_contract_registry
        get_contract_registry().unregister(self.manifest.name)
        from app.plugins.builtins.unified_search.provider_registry import (
            get_search_registry,
        )
@@ -232,6 +232,31 @@ class PluginManifest(BaseModel):
    custom_fields: list[CustomFieldDefinition] = Field(
        default_factory=list, description="Custom field definitions contributed by this plugin"
    )
    # ── Versioning (Phase 4) ──
    min_app_version: str = Field(
        default="0.0.0",
        description="Minimum LeoCRM version required (SemVer)"
    )
    # ── Marketplace (Phase 5) ──
    author: str = Field(default="", max_length=200, description="Plugin author name")
    author_email: str = Field(default="", max_length=200, description="Author contact email")
    homepage: str = Field(default="", max_length=500, description="Plugin homepage URL")
    license: str = Field(default="MIT", max_length=50, description="License identifier")
    icon: str = Field(default="", description="Icon URL or emoji")
    screenshots: list[str] = Field(default_factory=list, description="Screenshot URLs for marketplace")
    changelog: str = Field(default="", description="Changelog URL or inline text")
    marketplace_tags: list[str] = Field(default_factory=list, description="Marketplace category tags")
    price: float = Field(default=0.0, ge=0.0, description="Price (0 = free)")
    # ── Hooks (Phase 2) ──
    hooks: list[str] = Field(
        default_factory=list,
        description="Hook names this plugin registers (e.g. 'contact.before_create')"
    )
    # ── Contracts (Phase 1) ──
    contract_version: str = Field(
        default="1.0.0",
        description="Contract API version this plugin exposes"
    )
    @field_validator("name")
@@ -241,6 +266,27 @@ class PluginManifest(BaseModel):
            raise ValueError("Plugin name must be alphanumeric with underscores only")
        return v.lower()
    @field_validator("min_app_version")
    @classmethod
    def validate_min_app_version(cls, v: str) -> str:
        """Validate min_app_version is valid SemVer."""
        if v and v != "0.0.0":
            from app.plugins.semver import SemVer
            SemVer.parse(v)  # Raises ValueError if invalid
        return v
    @field_validator("hooks")
    @classmethod
    def validate_hooks(cls, v: list[str]) -> list[str]:
        """Validate hook names follow namespace.action pattern."""
        import re
        for hook in v:
            if not re.match(r"^[a-z_]+\.[a-z_]+$", hook):
                raise ValueError(
                    f"Invalid hook name '{hook}': must be 'namespace.action' (lowercase, underscores only)"
                )
        return v
    model_config = {"extra": "forbid"}
@@ -323,6 +369,46 @@ MANIFEST_SCHEMA_DOC = ManifestSchemaResponse(
            "required": "false",
            "description": "Dashboard widgets (id, label_key, component, col_span, permission)",
        },
        "min_app_version": {
            "type": "str",
            "required": "false",
            "description": "Minimum LeoCRM version required (SemVer, default: 0.0.0)",
        },
        "author": {
            "type": "str",
            "required": "false",
            "description": "Plugin author name",
        },
        "license": {
            "type": "str",
            "required": "false",
            "description": "License identifier (default: MIT)",
        },
        "homepage": {
            "type": "str",
            "required": "false",
            "description": "Plugin homepage URL",
        },
        "hooks": {
            "type": "list[str]",
            "required": "false",
            "description": "Hook names this plugin registers (e.g. 'contact.before_create')",
        },
        "contract_version": {
            "type": "str",
            "required": "false",
            "description": "Contract API version this plugin exposes (default: 1.0.0)",
        },
        "marketplace_tags": {
            "type": "list[str]",
            "required": "false",
            "description": "Marketplace category tags",
        },
        "price": {
            "type": "float",
            "required": "false",
            "description": "Price (0 = free, default: 0.0)",
        },
    },
    example=PluginManifest(
        name="example_plugin",
@@ -190,6 +190,178 @@ class MigrationRunner:
        return dropped_tables
    async def get_applied_migrations(
        self,
        db: AsyncSession,
        plugin_name: str,
    ) -> list[str]:
        """Get all applied migration filenames for a plugin, sorted by application order.
        Args:
            db: Async database session.
            plugin_name: Name of the plugin.
        Returns:
            List of migration filenames sorted by application order (oldest first).
        """
        from sqlalchemy import select
        result = await db.execute(
            select(PluginMigration)
            .where(
                PluginMigration.plugin_name == plugin_name,
                PluginMigration.status == "applied",
            )
            .order_by(PluginMigration.id)
        )
        return [row.migration_file for row in result.scalars().all()]
    async def _find_down_sql(
        self,
        migration_filename: str,
        plugin_name: str | None = None,
    ) -> str | None:
        """Find rollback SQL for a migration.
        Search order:
        1. A dedicated down file: <migration_filename>_down.sql
        2. A `-- DOWN:` block inside the original migration file
        Returns the rollback SQL string, or None if no rollback is found.
        """
        # 1. Try dedicated down file
        base, ext = os.path.splitext(migration_filename)
        down_filename = f"{base}_down{ext}"
        try:
            down_path = self._resolve_migration_path(down_filename, plugin_name)
            return down_path.read_text(encoding="utf-8")
        except FileNotFoundError:
            pass
        # 2. Try parsing -- DOWN: block from the original migration file
        try:
            up_path = self._resolve_migration_path(migration_filename, plugin_name)
            content = up_path.read_text(encoding="utf-8")
        except FileNotFoundError:
            return None
        down_marker = "-- DOWN:"
        if down_marker in content:
            parts = content.split(down_marker, 1)
            if len(parts) == 2:
                down_sql = parts[1].strip()
                return down_sql if down_sql else None
        return None
    async def run_migration_down(
        self,
        db: AsyncSession,
        plugin_name: str,
        migration_filename: str,
    ) -> None:
        """Roll back a single migration.
        Searches for rollback SQL (dedicated _down.sql file or -- DOWN: block
        in the original migration), executes it, and removes the migration
        record from plugin_migrations.
        Args:
            db: Async database session.
            plugin_name: Name of the plugin.
            migration_filename: Filename of the migration to roll back.
        Raises:
            FileNotFoundError: If no rollback SQL can be found.
        """
        down_sql = await self._find_down_sql(migration_filename, plugin_name)
        if down_sql is None:
            raise FileNotFoundError(
                f"No rollback SQL found for migration '{migration_filename}'. "
                f"Create a '{migration_filename.replace('.sql', '_down.sql')}' file "
                f"or add a '-- DOWN:' section to the migration file."
            )
        # Execute the rollback SQL
        statements = self._split_sql(down_sql)
        for stmt in statements:
            stmt = stmt.strip()
            if stmt:
                await db.execute(text(stmt))
        await db.flush()
        # Remove the migration record
        from sqlalchemy import select
        result = await db.execute(
            select(PluginMigration).where(
                PluginMigration.plugin_name == plugin_name,
                PluginMigration.migration_file == migration_filename,
                PluginMigration.status == "applied",
            )
        )
        record = result.scalar_one_or_none()
        if record:
            await db.delete(record)
            await db.flush()
    async def rollback_to_version(
        self,
        db: AsyncSession,
        plugin_name: str,
        target_version: str,
    ) -> list[str]:
        """Roll back all applied migrations after a target version.
        Migrations are rolled back in reverse order (newest first) until
        the target version is reached. The plugin version in the database
        is updated to the target version.
        Args:
            db: Async database session.
            plugin_name: Name of the plugin.
            target_version: Target version string (e.g. '0002'). Migrations
                with filenames greater than this will be rolled back.
        Returns:
            List of migration filenames that were rolled back.
        """
        applied = await self.get_applied_migrations(db, plugin_name)
        # Filter migrations after target_version (by filename sort order)
        migrations_to_rollback = [
            m for m in applied if m > target_version
        ]
        if not migrations_to_rollback:
            return []
        # Roll back in reverse order (newest first)
        rolled_back: list[str] = []
        for migration_filename in reversed(migrations_to_rollback):
            await self.run_migration_down(db, plugin_name, migration_filename)
            rolled_back.append(migration_filename)
        # Update plugin version in DB (if a plugin_versions table exists)
        try:
            from sqlalchemy import select, update as sa_update
            result = await db.execute(
                text("SELECT 1 FROM information_schema.tables "
                     "WHERE table_schema = 'public' AND table_name = 'plugin_versions'")
            )
            if result.fetchone():
                await db.execute(
                    text("UPDATE plugin_versions SET version = :version "
                         "WHERE plugin_name = :plugin_name"),
                    {"version": target_version, "plugin_name": plugin_name},
                )
                await db.flush()
        except Exception:
            pass  # plugin_versions table may not exist — that's ok
        return rolled_back
    async def _get_table_names_via_session(self, db: AsyncSession) -> set[str]:
        """Get current table names using the session's own connection.
@@ -0,0 +1,215 @@
 """Plugin quarantine — extract, validate, and install external plugins safely.
 Workflow:
 1. Extract ZIP to a temporary directory
 2. Validate manifest exists and is valid
 3. Check for dangerous imports
 4. Validate migration SQL
 5. Verify signature (if provided)
 6. If all checks pass: move to plugins/ directory
 7. If any check fails: delete temp directory and raise error
 Usage::
    from app.plugins.quarantine import quarantine_plugin
    plugin_dir = await quarantine_plugin(
        zip_path=Path("plugin.zip"),
        signature=b"...",
        public_key=b"...",
    )
 """
 from __future__ import annotations
 import logging
 import os
 import re
 import shutil
 import tempfile
 import zipfile
 from pathlib import Path
 from app.plugins.signature import PluginSignature
 logger = logging.getLogger(__name__)
 # Maximum plugin ZIP size (50 MB)
 MAX_PLUGIN_SIZE = 50 * 1024 * 1024
 # Dangerous patterns in plugin source code
 DANGEROUS_PATTERNS = [
    (r"\bos\.system\b", "os.system call"),
    (r"\bsubprocess\.", "subprocess module"),
    (r"\beval\s*\(", "eval() call"),
    (r"\bexec\s*\(", "exec() call"),
    (r"\b__import__\s*\(", "__import__() call"),
    (r"\bcompile\s*\(", "compile() call"),
    (r"\bopen\s*\([^)]*['\"]w['\"]", "file write outside DMS"),
 ]
 class QuarantineError(Exception):
    """Raised when a plugin fails quarantine validation."""
 def _validate_manifest(plugin_dir: Path) -> dict:
    """Validate that the plugin has a valid manifest.
    Returns the parsed manifest data.
    """
    plugin_py = plugin_dir / "plugin.py"
    init_py = plugin_dir / "__init__.py"
    if not plugin_py.exists() and not init_py.exists():
        raise QuarantineError("Plugin must have plugin.py or __init__.py")
    # Read source and look for manifest
    source_file = plugin_py if plugin_py.exists() else init_py
    source = source_file.read_text(encoding="utf-8")
    if "PluginManifest" not in source:
        raise QuarantineError("Plugin source must define a PluginManifest")
    if "BasePlugin" not in source:
        raise QuarantineError("Plugin source must inherit from BasePlugin")
    return {"source_file": str(source_file), "has_manifest": True}
 def _check_dangerous_imports(plugin_dir: Path) -> list[str]:
    """Check plugin source for dangerous imports/patterns.
    Returns a list of dangerous patterns found (empty if safe).
    """
    found: list[str] = []
    for py_file in plugin_dir.rglob("*.py"):
        source = py_file.read_text(encoding="utf-8")
        for pattern, description in DANGEROUS_PATTERNS:
            if re.search(pattern, source):
                found.append(f"{py_file.name}: {description}")
    return found
 def _check_migration_sql(plugin_dir: Path) -> list[str]:
    """Validate migration SQL files in the plugin.
    Returns a list of issues found (empty if OK).
    """
    issues: list[str] = []
    migrations_dir = plugin_dir / "migrations"
    if not migrations_dir.exists():
        return issues  # No migrations is OK
    for sql_file in migrations_dir.glob("*.sql"):
        content = sql_file.read_text(encoding="utf-8")
        # Check for tenant_id in CREATE TABLE
        if "CREATE TABLE" in content.upper() and "tenant_id" not in content.lower():
            issues.append(
                f"{sql_file.name}: CREATE TABLE without tenant_id column"
            )
        # Check for DROP DATABASE / DROP SCHEMA
        if "DROP DATABASE" in content.upper() or "DROP SCHEMA" in content.upper():
            issues.append(f"{sql_file.name}: Contains DROP DATABASE/SCHEMA")
    return issues
 async def quarantine_plugin(
    zip_path: Path,
    signature: bytes | None = None,
    public_key: bytes | None = None,
    plugins_dir: Path | None = None,
 ) -> Path:
    """Extract, validate, and install a plugin from a ZIP file.
    Args:
        zip_path: Path to the plugin ZIP file.
        signature: Optional Ed25519 signature bytes.
        public_key: Optional Ed25519 public key bytes.
        plugins_dir: Target directory for external plugins (default: plugins/).
    Returns:
        Path to the installed plugin directory.
    Raises:
        QuarantineError: If any validation check fails.
    """
    # Check file size
    file_size = zip_path.stat().st_size
    if file_size > MAX_PLUGIN_SIZE:
        raise QuarantineError(
            f"Plugin ZIP too large: {file_size} bytes (max {MAX_PLUGIN_SIZE})"
        )
    # Verify signature if provided
    if signature and public_key:
        if not PluginSignature.verify_signature(zip_path, signature, public_key):
            raise QuarantineError("Signature verification failed")
    # Create temp directory for extraction
    temp_dir = Path(tempfile.mkdtemp(prefix="plugin_quarantine_"))
    try:
        # Extract ZIP
        with zipfile.ZipFile(zip_path, "r") as zf:
            # Check for path traversal in ZIP entries
            for entry in zf.namelist():
                if entry.startswith("/") or ".." in entry:
                    raise QuarantineError(f"Unsafe ZIP entry: {entry}")
            zf.extractall(temp_dir)
        # Find the plugin directory (might be nested)
        plugin_dir = temp_dir
        if not (plugin_dir / "plugin.py").exists() and not (plugin_dir / "__init__.py").exists():
            # Look for a single subdirectory
            subdirs = [d for d in plugin_dir.iterdir() if d.is_dir() and not d.name.startswith("_")]
            if len(subdirs) == 1:
                plugin_dir = subdirs[0]
            else:
                raise QuarantineError("Could not find plugin root directory in ZIP")
        # 1. Validate manifest
        manifest_info = _validate_manifest(plugin_dir)
        logger.info("Manifest validated for plugin in %s", plugin_dir.name)
        # 2. Check dangerous imports
        dangerous = _check_dangerous_imports(plugin_dir)
        if dangerous:
            raise QuarantineError(
                f"Dangerous patterns found in plugin: {', '.join(dangerous)}"
            )
        # 3. Check migration SQL
        sql_issues = _check_migration_sql(plugin_dir)
        if sql_issues:
            raise QuarantineError(
                f"Migration SQL issues: {', '.join(sql_issues)}"
            )
        # 4. All checks passed — move to plugins directory
        target_dir = plugins_dir or Path(os.environ.get("EXTERNAL_PLUGINS_PATH", "plugins"))
        target_dir.mkdir(parents=True, exist_ok=True)
        plugin_name = plugin_dir.name
        final_dir = target_dir / plugin_name
        if final_dir.exists():
            raise QuarantineError(f"Plugin directory already exists: {final_dir}")
        shutil.copytree(plugin_dir, final_dir)
        logger.info("Plugin installed to %s", final_dir)
        return final_dir
    except Exception:
        # Clean up temp directory on any error
        shutil.rmtree(temp_dir, ignore_errors=True)
        raise
    finally:
        # Always clean up temp directory
        if temp_dir.exists():
            shutil.rmtree(temp_dir, ignore_errors=True)
@@ -104,6 +104,67 @@ class PluginRegistry:
        return discovered
    def discover_external(self) -> list[str]:
        """Discover plugins from an external plugins/ directory.
        Scans the directory specified by EXTERNAL_PLUGINS_PATH env var
        (default: 'plugins/') for plugin packages.
        Returns list of discovered plugin names.
        """
        import os
        import sys
        discovered: list[str] = []
        external_dir = Path(os.environ.get("EXTERNAL_PLUGINS_PATH", "plugins"))
        if not external_dir.exists():
            return discovered
        for plugin_dir in sorted(external_dir.iterdir()):
            if not plugin_dir.is_dir() or plugin_dir.name.startswith("_"):
                continue
            # Look for plugin.py or __init__.py
            plugin_file = plugin_dir / "plugin.py"
            init_file = plugin_dir / "__init__.py"
            if not plugin_file.exists() and not init_file.exists():
                continue
            try:
                # Add to sys.path temporarily
                str_dir = str(external_dir)
                if str_dir not in sys.path:
                    sys.path.insert(0, str_dir)
                module_name = f"{plugin_dir.name}.plugin" if plugin_file.exists() else plugin_dir.name
                module = importlib.import_module(module_name)
                # Look for BasePlugin subclass
                for attr_name in dir(module):
                    attr = getattr(module, attr_name)
                    if (
                        isinstance(attr, type)
                        and issubclass(attr, BasePlugin)
                        and attr is not BasePlugin
                    ):
                        instance = attr()
                        if instance.name not in self._plugins:
                            self._plugins[instance.name] = instance
                            discovered.append(instance.name)
                            logger.info(f"Discovered external plugin: {instance.name} v{instance.version}")
            except Exception as exc:
                logger.warning(f"Failed to load external plugin {plugin_dir.name}: {exc}")
        return discovered
    def discover_all(self) -> list[str]:
        """Discover built-in AND external plugins."""
        discovered = self.discover_builtins()
        discovered.extend(self.discover_external())
        return discovered
    def register_plugin(self, plugin: BasePlugin) -> None:
        """Manually register a plugin instance."""
        self._plugins[plugin.name] = plugin
@@ -465,6 +526,25 @@ class PluginRegistry:
            await self._check_and_run_version_migrations(db, name, existing)
            return existing
        # Check app version compatibility
        from app.plugins.semver import SemVer
        from app.config import get_settings
        settings = get_settings()
        app_version = getattr(settings, "app_version", "0.0.0")
        min_version = plugin.manifest.min_app_version
        if min_version and min_version != "0.0.0":
            try:
                if not SemVer.parse(app_version).is_compatible_with(SemVer.parse(min_version)):
                    raise ValueError(
                        f"Plugin '{name}' requires LeoCRM >= {min_version}, "
                        f"but current version is {app_version}"
                    )
            except ValueError as e:
                if "Invalid semver" in str(e):
                    pass  # Skip check if version is not valid SemVer
                else:
                    raise
        # Check dependencies are installed
        await self._check_dependencies_installed(db, name)
@@ -0,0 +1,215 @@
 """Semantic version comparison for plugin versions.
 Supports parsing, comparison, and compatibility checks for SemVer strings.
 Handles pre-release versions (e.g. 1.0.0-alpha.1) per SemVer spec.
 Usage::
    from app.plugins.semver import SemVer
    v1 = SemVer.parse("1.2.3")
    v2 = SemVer.parse("1.3.0")
    if v1 < v2:
        print(f"{v1} is older than {v2}")
    if v1.is_breaking_change(v2):
        print("Major version changed — breaking!")
    if v2.is_compatible_with(v1):
        print("v2 is compatible with v1")
 """
 from __future__ import annotations
 import re
 from dataclasses import dataclass
@dataclass(frozen=True)
 class SemVer:
    """A semantic version following semver.org spec.
    Attributes:
        major: Major version (breaking changes).
        minor: Minor version (new features, backward compatible).
        patch: Patch version (bug fixes, backward compatible).
        prerelease: Optional pre-release string (e.g. "alpha.1", "beta.2").
    """
    major: int
    minor: int
    patch: int
    prerelease: str = ""
    @classmethod
    def parse(cls, version: str) -> SemVer:
        """Parse a SemVer string into a SemVer instance.
        Args:
            version: Version string like "1.2.3" or "1.2.3-alpha.1".
        Returns:
            SemVer instance.
        Raises:
            ValueError: If the version string is not valid SemVer.
        """
        if not version:
            raise ValueError("Version string is empty")
        # Strip leading 'v' if present
        version = version.strip().lstrip("v")
        match = re.match(
            r"^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$",
            version,
        )
        if not match:
            raise ValueError(
                f"Invalid semver '{version}': expected MAJOR.MINOR.PATCH[-prerelease]"
            )
        return cls(
            major=int(match.group(1)),
            minor=int(match.group(2)),
            patch=int(match.group(3)),
            prerelease=match.group(4) or "",
        )
    def __str__(self) -> str:
        base = f"{self.major}.{self.minor}.{self.patch}"
        if self.prerelease:
            return f"{base}-{self.prerelease}"
        return base
    def __repr__(self) -> str:
        return f"SemVer({self!s})"
    def __lt__(self, other: SemVer) -> bool:
        if not isinstance(other, SemVer):
            return NotImplemented
        # Compare major.minor.patch
        if (self.major, self.minor, self.patch) != (other.major, other.minor, other.patch):
            return (self.major, self.minor, self.patch) < (other.major, other.minor, other.patch)
        # Pre-release versions are lower than release versions
        if not self.prerelease and other.prerelease:
            return False
        if self.prerelease and not other.prerelease:
            return True
        # Both have pre-release — compare lexically
        return self._compare_prerelease(self.prerelease, other.prerelease) < 0
    def __eq__(self, other: object) -> bool:
        if not isinstance(other, SemVer):
            return NotImplemented
        return (
            self.major == other.major
            and self.minor == other.minor
            and self.patch == other.patch
            and self.prerelease == other.prerelease
        )
    def __le__(self, other: SemVer) -> bool:
        return self == other or self < other
    def __gt__(self, other: SemVer) -> bool:
        if not isinstance(other, SemVer):
            return NotImplemented
        return not self <= other
    def __ge__(self, other: SemVer) -> bool:
        return not self < other
    def __hash__(self) -> int:
        return hash((self.major, self.minor, self.patch, self.prerelease))
    # ─── Compatibility checks ───
    def is_breaking_change(self, other: SemVer) -> bool:
        """Return True if the major version differs (breaking change)."""
        return self.major != other.major
    def is_compatible_with(self, min_version: SemVer) -> bool:
        """Return True if this version satisfies the minimum version requirement.
        A version is compatible if:
        - Same major version and >= min_version, OR
        - Higher major version (forward compatible)
        """
        if self.major > min_version.major:
            return True
        if self.major < min_version.major:
            return False
        # Same major — compare minor.patch
        return self >= min_version
    def is_upgrade_from(self, old_version: SemVer) -> bool:
        """Return True if this version is newer than old_version."""
        return self > old_version
    def is_downgrade_from(self, old_version: SemVer) -> bool:
        """Return True if this version is older than old_version."""
        return self < old_version
    # ─── Internal helpers ───
    @staticmethod
    def _compare_prerelease(a: str, b: str) -> int:
        """Compare two pre-release strings per SemVer spec.
        Numeric identifiers are compared numerically, alphanumeric lexically.
        """
        a_parts = a.split(".")
        b_parts = b.split(".")
        for i in range(min(len(a_parts), len(b_parts))):
            ap, bp = a_parts[i], b_parts[i]
            a_is_num = ap.isdigit()
            b_is_num = bp.isdigit()
            if a_is_num and b_is_num:
                ai, bi = int(ap), int(bp)
                if ai < bi:
                    return -1
                if ai > bi:
                    return 1
            elif a_is_num and not b_is_num:
                return -1  # Numeric < alphanumeric
            elif not a_is_num and b_is_num:
                return 1  # Alphanumeric > numeric
            else:
                if ap < bp:
                    return -1
                if ap > bp:
                    return 1
        # All compared parts are equal — shorter pre-release is lower
        return len(a_parts) - len(b_parts)
 def compare_versions(v1: str, v2: str) -> int:
    """Compare two version strings.
    Returns:
        -1 if v1 < v2
         0 if v1 == v2
         1 if v1 > v2
    """
    sv1 = SemVer.parse(v1)
    sv2 = SemVer.parse(v2)
    if sv1 < sv2:
        return -1
    if sv1 > sv2:
        return 1
    return 0
 def is_breaking_change(old: str, new: str) -> bool:
    """Check if upgrading from old to new is a breaking change."""
    return SemVer.parse(old).is_breaking_change(SemVer.parse(new))
 def is_compatible(current: str, min_required: str) -> bool:
    """Check if current version satisfies the minimum required version."""
    return SemVer.parse(current).is_compatible_with(SemVer.parse(min_required))
@@ -0,0 +1,128 @@
 """Plugin signature verification for external plugins.
 Uses Ed25519 signatures to verify that a plugin ZIP package
 has not been tampered with and comes from a trusted source.
 Usage::
    from app.plugins.signature import PluginSignature
    # Verify a downloaded plugin
    is_valid = PluginSignature.verify_signature(
        zip_path=Path("plugin.zip"),
        signature=b"...",
        public_key=b"...",
    )
    # Compute hash for allowlist
    file_hash = PluginSignature.compute_hash(Path("plugin.zip"))
    # Sign a plugin (for plugin authors)
    signature = PluginSignature.sign_plugin(
        zip_path=Path("plugin.zip"),
        private_key=b"...",
    )
 """
 from __future__ import annotations
 import hashlib
 import logging
 from pathlib import Path
 logger = logging.getLogger(__name__)
 class PluginSignature:
    """Verify plugin package signatures using Ed25519."""
    @staticmethod
    def compute_hash(file_path: Path) -> str:
        """Compute SHA-256 hash of a file.
        Args:
            file_path: Path to the file to hash.
        Returns:
            Hex-encoded SHA-256 hash string.
        """
        sha256 = hashlib.sha256()
        with open(file_path, "rb") as f:
            for chunk in iter(lambda: f.read(8192), b""):
                sha256.update(chunk)
        return sha256.hexdigest()
    @staticmethod
    def verify_signature(
        zip_path: Path,
        signature: bytes,
        public_key: bytes,
    ) -> bool:
        """Verify Ed25519 signature of a plugin ZIP.
        Args:
            zip_path: Path to the plugin ZIP file.
            signature: The Ed25519 signature bytes.
            public_key: The Ed25519 public key bytes.
        Returns:
            True if the signature is valid, False otherwise.
        """
        try:
            from nacl.signing import VerifyKey
            from nacl.exceptions import BadSignatureError
            file_hash = PluginSignature.compute_hash(zip_path)
            verify_key = VerifyKey(public_key)
            verify_key.verify(file_hash.encode(), signature)
            logger.info("Signature verified for %s", zip_path.name)
            return True
        except ImportError:
            logger.warning(
                "PyNaCl not installed — signature verification disabled. "
                "Install with: pip install pynacl"
            )
            return False
        except BadSignatureError:
            logger.warning("Invalid signature for %s", zip_path.name)
            return False
        except Exception:
            logger.exception("Error verifying signature for %s", zip_path.name)
            return False
    @staticmethod
    def sign_plugin(
        zip_path: Path,
        private_key: bytes,
    ) -> bytes:
        """Sign a plugin ZIP with an Ed25519 private key.
        Args:
            zip_path: Path to the plugin ZIP file.
            private_key: The Ed25519 private key bytes.
        Returns:
            The Ed25519 signature bytes.
        Raises:
            ImportError: If PyNaCl is not installed.
        """
        from nacl.signing import SigningKey
        file_hash = PluginSignature.compute_hash(zip_path)
        signing_key = SigningKey(private_key)
        return signing_key.sign(file_hash.encode()).signature
    @staticmethod
    def generate_keypair() -> tuple[bytes, bytes]:
        """Generate a new Ed25519 key pair.
        Returns:
            Tuple of (private_key, public_key) bytes.
        """
        from nacl.signing import SigningKey
        signing_key = SigningKey.generate()
        private_key = bytes(signing_key)
        public_key = bytes(signing_key.verify_key)
        return private_key, public_key
@@ -62,6 +62,45 @@ async def get_manifest_schema(
    return service.get_manifest_schema()
@router.get("/updates")
 async def check_plugin_updates(
    db: AsyncSession = Depends(get_db),
    current_user: dict = Depends(require_permission("plugins:read")),
 ):
    """Check for available plugin updates.
    Compares installed plugin versions with discovered plugin versions.
    Returns a list of plugins where the discovered version is newer.
    """
    from app.plugins.semver import SemVer
    service = get_plugin_service()
    plugins = await service.list_plugins(db)
    updates: list[dict[str, Any]] = []
    for plugin in plugins:
        if not plugin.get("installed"):
            continue
        installed_version = plugin.get("version", "0.0.0")
        # The discovered version is always the manifest version
        discovered_version = plugin.get("version", "0.0.0")
        # In a real marketplace scenario, we'd compare with a remote registry
        # For now, we check if the manifest version differs from the DB version
        # This is a placeholder for marketplace integration
        try:
            if SemVer.parse(discovered_version) > SemVer.parse(installed_version):
                updates.append({
                    "name": plugin["name"],
                    "display_name": plugin.get("display_name", plugin["name"]),
                    "current_version": installed_version,
                    "available_version": discovered_version,
                })
        except ValueError:
            pass  # Skip if version is not valid SemVer
    return {"updates": updates, "total": len(updates)}
@router.get("/active-manifests")
 async def get_active_manifests(
    db: AsyncSession = Depends(get_db),
@@ -466,3 +505,39 @@ async def install_plugin_from_url(
        status_code=403,
        detail={"detail": "Plugin URL installation is disabled. Use signed plugin artifacts from the allowlist.", "code": "install_url_disabled"},
    )
 # ── Marketplace (Phase 5) ──────────────────────────────────────────────────────
 class MarketplaceInstall(BaseModel):
    """Request body for installing a plugin from the marketplace."""
    url: str
    signature: str | None = None
    public_key: str | None = None
    activate: bool = False
@router.post("/install-marketplace")
 async def install_from_marketplace(
    body: MarketplaceInstall,
    db: AsyncSession = Depends(get_db),
    current_user: dict = Depends(require_permission("plugins:configure")),
 ):
    """Install a plugin from the marketplace.
    1. Download ZIP from marketplace URL
    2. Verify signature against allowlist (if provided)
    3. Quarantine: validate manifest, check dangerous imports, validate SQL
    4. Install (migrations + DB record)
    5. Activate (optional)
    DISABLED until marketplace is live — requires allowlist entry.
    """
    raise HTTPException(
        status_code=403,
        detail={
            "detail": "Marketplace installation is not yet available. Use built-in plugins.",
            "code": "marketplace_not_available",
        },
    )
@@ -23,6 +23,7 @@ from app.core.auth import (
    update_session_tenant,
    verify_password,
 )
 from app.core.hooks import do_action, apply_filters
 from app.models.auth import PasswordResetToken
 from app.models.tenant import Tenant
 from app.models.user import User, UserTenant
@@ -48,6 +49,9 @@ class AuthService:
        The tenant is resolved from UserTenant via tenant_slug or the
        user's default tenant membership.
        """
        # Hook: auth.before_login — filter can modify email
        email = await apply_filters("auth.before_login", email, db=db, password=password, tenant_slug=tenant_slug)
        # Find user by email (globally unique now)
        q = select(User).where(User.email == email, User.is_active == True)  # noqa: E712
        result = await db.execute(q)
@@ -98,6 +102,9 @@ class AuthService:
            changes={"email": email},
        )
        # Hook: auth.after_login
        await do_action("auth.after_login", db=db, user=user, tenant=tenant, role=user_tenant.role, session_id=session_id)
        return session_id, csrf_token, user, tenant, user_tenant.role
    async def logout(self, redis: aioredis.Redis, session_id: str) -> bool:
@@ -13,6 +13,7 @@ from sqlalchemy.orm import selectinload
 from app.models.contact import Contact, ContactPerson
 from app.services.entity_history_service import record_history
 from app.core.hooks import do_action, apply_filters
 def _compute_displayname(data: dict) -> str:
@@ -212,7 +213,9 @@ async def create_contact(
    db: AsyncSession, tenant_id: uuid.UUID, user_id: uuid.UUID, data: dict
 ) -> dict:
    """Create a new contact."""
-    data["displayname"] = _compute_displayname(data)
+    data["displayname"] = await apply_filters("contact.format_display_name", _compute_displayname(data), data=data, db=db, tenant_id=tenant_id, user_id=user_id)
    # Hook: contact.before_create
    await do_action("contact.before_create", data, db=db, tenant_id=tenant_id, user_id=user_id)
    contact_persons_data = data.pop("contact_persons", None)
    contact = Contact(
@@ -267,6 +270,9 @@ async def create_contact(
            'user_id': str(user_id),
        })
    # Hook: contact.after_create
    await do_action("contact.after_create", serialized, db=db, tenant_id=tenant_id, user_id=user_id)
    return serialized
@@ -290,6 +296,9 @@ async def update_contact(
    if not contact:
        raise ValueError("Contact not found")
    # Hook: contact.before_update
    await do_action("contact.before_update", data, db=db, tenant_id=tenant_id, user_id=user_id, contact_id=contact_id)
    # Capture snapshot before update
    snapshot_before = _serialize_contact_detail(contact)
@@ -340,6 +349,9 @@ async def update_contact(
        'type': contact.type,
    })
    # Hook: contact.after_update
    await do_action("contact.after_update", snapshot_after, db=db, tenant_id=tenant_id, user_id=user_id, contact_id=contact_id)
    return snapshot_after
@@ -357,6 +369,9 @@ async def delete_contact(
    if not contact:
        raise ValueError("Contact not found")
    # Hook: contact.before_delete
    await do_action("contact.before_delete", db=db, tenant_id=tenant_id, contact_id=contact_id, user_id=user_id)
    # Capture snapshot before deletion
    from sqlalchemy.orm import selectinload
    q2 = (
@@ -104,6 +104,11 @@ class UserService:
        If role_id is provided it links the UserTenant to a custom Role record.
        The ``role`` string is the built-in role (admin/editor/viewer).
        """
        # ── Hook: user.before_create (Action) ──
        from app.core.hooks import do_action
        await do_action("user.before_create", email=email, name=name, role=role, tenant_id=tenant_id)
        user = User(
            email=email,
            name=name,
@@ -125,6 +130,10 @@ class UserService:
        db.add(ut)
        await db.flush()
        # ── Hook: user.after_create (Action) ──
        from app.core.hooks import do_action
        await do_action("user.after_create", user_id=str(user.id), email=email, name=name, role=role, tenant_id=tenant_id)
        return user
    async def update_user(
@@ -72,6 +72,19 @@ export interface PluginUiManifest {
  settings_pages: PluginSettingsPage[];
  dashboard_widgets: PluginDashboardWidget[];
  custom_fields: PluginCustomFieldDefinition[];
  // ── Phase 4-6: Versioning + Marketplace + Manifest fields ──
  min_app_version?: string;
  author?: string;
  author_email?: string;
  homepage?: string;
  license?: string;
  icon?: string;
  screenshots?: string[];
  changelog?: string;
  marketplace_tags?: string[];
  price?: number;
  hooks?: string[];
  contract_version?: string;
 }
 interface PluginState {
@@ -0,0 +1,224 @@
 #!/usr/bin/env python3
 """Check for forbidden direct cross-plugin imports.
 This script enforces that plugins communicate only through contracts,
 not by importing internal modules from each other.
 Allowed:
    from app.plugins.builtins.contracts import get_contract
    from app.plugins.builtins.<name>.contracts import ...
    from app.plugins.builtins.<name> import <PluginClass>  (in __init__.py only)
 Forbidden:
    from app.plugins.builtins.<name>.services import ...
    from app.plugins.builtins.<name>.models import ...
    from app.plugins.builtins.<name>.routes import ...
 Exceptions (files that are allowed to import anything):
    - */contracts.py — contracts import from internal modules
    - */__init__.py — plugin discovery
    - app/plugins/registry.py — registry manages all plugins
    - app/plugins/builtins/__init__.py — builtin discovery
    - tests/* — test files
    - conftest.py — test fixtures
 Usage:
    python scripts/check_cross_plugin_imports.py
    python scripts/check_cross_plugin_imports.py --path app/plugins/builtins
 Exit codes:
    0 — no violations
    1 — violations found
 """
 from __future__ import annotations
 import os
 import re
 import sys
 from pathlib import Path
 # ─── Configuration ───
 PROJECT_ROOT = Path(__file__).resolve().parent.parent
 BUILTINS_DIR = PROJECT_ROOT / "app" / "plugins" / "builtins"
 # Files that are exempt from the rule
 EXEMPT_FILES = {
    "contracts.py",
    "__init__.py",
    "conftest.py",
 }
 # Directories that are exempt
 EXEMPT_DIRS = {
    "tests",
    "__pycache__",
    "migrations",
 }
 # Files that are exempt by path
 EXEMPT_PATHS = {
    PROJECT_ROOT / "app" / "plugins" / "registry.py",
    PROJECT_ROOT / "app" / "plugins" / "builtins" / "__init__.py",
    PROJECT_ROOT / "app" / "plugins" / "base.py",
    PROJECT_ROOT / "app" / "plugins" / "manifest.py",
    PROJECT_ROOT / "app" / "plugins" / "migration_runner.py",
 }
 # Pattern for cross-plugin imports
 IMPORT_PATTERN = re.compile(
    r"^\s*(?:from|import)\s+app\.plugins\.builtins\.([^.]+)\.(.+?)\s+import\s+(.+)$"
 )
 # Pattern for allowed contract imports
 CONTRACT_IMPORT_PATTERN = re.compile(
    r"^\s*from\s+app\.plugins\.builtins\.(?:contracts|[^.]+\.contracts)\s+import\s+(.+)$"
 )
 # Pattern for __init__.py plugin class imports (allowed in __init__.py only)
 PLUGIN_CLASS_IMPORT_PATTERN = re.compile(
    r"^\s*from\s+app\.plugins\.builtins\.([^.]+)\s+import\s+([A-Z]\w*Plugin)\s*$"
 )
 def is_exempt(filepath: Path) -> bool:
    """Check if a file is exempt from the cross-plugin import rule."""
    # Exempt by filename
    if filepath.name in EXEMPT_FILES:
        return True
    # Exempt by path
    if filepath in EXEMPT_PATHS:
        return True
    # Exempt test directories
    parts = filepath.parts
    for exempt_dir in EXEMPT_DIRS:
        if exempt_dir in parts:
            return True
    return False
 def check_file(filepath: Path) -> list[str]:
    """Check a single file for forbidden cross-plugin imports.
    Returns a list of violation messages (empty if clean).
    """
    if is_exempt(filepath):
        return []
    violations: list[str] = []
    rel_path = filepath.relative_to(PROJECT_ROOT)
    # Determine the source plugin from the file path
    try:
        parts = filepath.relative_to(BUILTINS_DIR).parts
        src_plugin = parts[0] if parts else ""
    except ValueError:
        src_plugin = ""
    with open(filepath, encoding="utf-8") as f:
        for line_num, line in enumerate(f, 1):
            line_stripped = line.strip()
            # Skip comments and empty lines
            if not line_stripped or line_stripped.startswith("#"):
                continue
            # Check for cross-plugin import
            match = IMPORT_PATTERN.match(line)
            if not match:
                continue
            tgt_plugin = match.group(1)
            tgt_module = match.group(2)
            # Skip if importing from contracts
            if tgt_module == "contracts":
                continue
            # Skip if same plugin (INTRA-Plugin import)
            if tgt_plugin == src_plugin:
                continue
            # Skip if it's a contract import via the central registry
            if CONTRACT_IMPORT_PATTERN.match(line):
                continue
            # This is a forbidden cross-plugin import
            violations.append(
                f"{rel_path}:{line_num}: {line_stripped}\n"
 f"  → Forbidden cross-plugin import: '{tgt_plugin}.{tgt_module}'. "
                f"Use contracts instead: get_contract(\"{tgt_plugin}\")"
            )
    return violations
 def find_python_files(search_path: Path | None = None) -> list[Path]:
    """Find all Python files in the search path."""
    if search_path is None:
        search_path = BUILTINS_DIR
    files: list[Path] = []
    for root, dirs, fnames in os.walk(search_path):
        # Skip exempt directories
        dirs[:] = [d for d in dirs if d not in EXEMPT_DIRS]
        for fname in fnames:
            if fname.endswith(".py"):
                files.append(Path(root) / fname)
    return sorted(files)
 def main() -> int:
    """Run the cross-plugin import checker."""
    import argparse
    parser = argparse.ArgumentParser(description="Check for forbidden cross-plugin imports.")
    parser.add_argument(
        "--path",
        type=Path,
        default=BUILTINS_DIR,
        help="Path to check (default: app/plugins/builtins)",
    )
    parser.add_argument(
        "--verbose",
        action="store_true",
        help="Print checked files even if clean.",
    )
    args = parser.parse_args()
    files = find_python_files(args.path)
    all_violations: list[str] = []
    checked = 0
    for filepath in files:
        checked += 1
        violations = check_file(filepath)
        if violations:
            all_violations.extend(violations)
        elif args.verbose:
            print(f"  ✅ {filepath.relative_to(PROJECT_ROOT)}")
    print(f"\nChecked {checked} files.")
    if all_violations:
        print(f"\n❌ Found {len(all_violations)} violation(s):\n")
        for v in all_violations:
            print(f"  {v}")
        print(
            "\nFix: Replace direct imports with contract-based access:\n"
            "  from app.plugins.builtins.contracts import get_contract\n"
            "  contract = get_contract(\"plugin_name\")\n"
            "  if contract:\n      result = await contract.some_function(...)"
        )
        return 1
    else:
        print("✅ No forbidden cross-plugin imports found.")
        return 0
 if __name__ == "__main__":
    sys.exit(main())
@@ -0,0 +1,194 @@
 """Tests for the WordPress-style hooks/filters system."""
 from __future__ import annotations
 import asyncio
 import pytest
 from app.core.hooks import (
    HookRegistry,
    get_hook_registry,
    do_action,
    apply_filters,
    reset_hook_registry_for_testing,
 )
@pytest.fixture(autouse=True)
 def clean_registry():
    """Reset the hook registry before each test."""
    reset_hook_registry_for_testing()
    yield
    reset_hook_registry_for_testing()
 class TestHookRegistry:
    def test_singleton_identity(self):
        """HookRegistry is a singleton."""
        reg1 = get_hook_registry()
        reg2 = get_hook_registry()
        assert reg1 is reg2
    def test_register_action(self):
        """Actions can be registered and listed."""
        reg = get_hook_registry()
        called = []
        reg.register_action("test.action", lambda: called.append(True))
        assert reg.has_action("test.action")
        assert "test.action" in reg.list_actions()
    def test_register_filter(self):
        """Filters can be registered and listed."""
        reg = get_hook_registry()
        reg.register_filter("test.filter", lambda v: v + "!")
        assert reg.has_filter("test.filter")
        assert "test.filter" in reg.list_filters()
    @pytest.mark.asyncio
    async def test_do_action_calls_callback(self):
        """do_action executes registered callbacks."""
        reg = get_hook_registry()
        called = []
        reg.register_action("test.action", lambda: called.append("yes"))
        await do_action("test.action")
        assert called == ["yes"]
    @pytest.mark.asyncio
    async def test_do_action_with_args(self):
        """do_action passes arguments to callbacks."""
        reg = get_hook_registry()
        received = []
        reg.register_action("test.action", lambda x, y: received.append((x, y)))
        await do_action("test.action", 1, 2)
        assert received == [(1, 2)]
    @pytest.mark.asyncio
    async def test_do_action_async_callback(self):
        """do_action supports async callbacks."""
        reg = get_hook_registry()
        called = []
        async def async_cb():
            called.append("async")
        reg.register_action("test.action", async_cb)
        await do_action("test.action")
        assert called == ["async"]
    @pytest.mark.asyncio
    async def test_do_action_priority_order(self):
        """Actions execute in priority order (lower first)."""
        reg = get_hook_registry()
        order = []
        reg.register_action("test.action", lambda: order.append("low"), priority=20)
        reg.register_action("test.action", lambda: order.append("high"), priority=5)
        reg.register_action("test.action", lambda: order.append("mid"), priority=10)
        await do_action("test.action")
        assert order == ["high", "mid", "low"]
    @pytest.mark.asyncio
    async def test_do_action_no_callbacks(self):
        """do_action with no registered callbacks does nothing."""
        await do_action("nonexistent.action")
    @pytest.mark.asyncio
    async def test_do_action_swallows_exceptions(self):
        """do_action logs but does not raise on callback errors."""
        reg = get_hook_registry()
        called = []
        reg.register_action("test.action", lambda: (_ for _ in ()).throw(ValueError("boom")))
        reg.register_action("test.action", lambda: called.append("after_error"))
        await do_action("test.action")
        assert called == ["after_error"]
    @pytest.mark.asyncio
    async def test_apply_filters_modifies_value(self):
        """apply_filters passes value through callbacks."""
        reg = get_hook_registry()
        reg.register_filter("test.filter", lambda v: v.upper())
        result = await apply_filters("test.filter", "hello")
        assert result == "HELLO"
    @pytest.mark.asyncio
    async def test_apply_filters_chains_multiple(self):
        """apply_filters chains multiple callbacks in priority order."""
        reg = get_hook_registry()
        reg.register_filter("test.filter", lambda v: v + " B", priority=20)
        reg.register_filter("test.filter", lambda v: v + " A", priority=10)
        result = await apply_filters("test.filter", "start")
        assert result == "start A B"
    @pytest.mark.asyncio
    async def test_apply_filters_no_callbacks(self):
        """apply_filters with no callbacks returns original value."""
        result = await apply_filters("nonexistent.filter", "original")
        assert result == "original"
    @pytest.mark.asyncio
    async def test_apply_filters_async_callback(self):
        """apply_filters supports async callbacks."""
        reg = get_hook_registry()
        async def async_upper(v: str) -> str:
            return v.upper()
        reg.register_filter("test.filter", async_upper)
        result = await apply_filters("test.filter", "hello")
        assert result == "HELLO"
    def test_unregister_specific_callback(self):
        """unregister removes a specific callback."""
        reg = get_hook_registry()
        cb1 = lambda: None
        cb2 = lambda: None
        reg.register_action("test.action", cb1)
        reg.register_action("test.action", cb2)
        assert reg.has_action("test.action")
        reg.unregister("test.action", cb1)
        assert reg.has_action("test.action")
        reg.unregister("test.action", cb2)
        assert not reg.has_action("test.action")
    def test_unregister_all_for_plugin(self):
        """unregister_all_for_plugin removes hooks owned by a plugin instance."""
        reg = get_hook_registry()
        class FakePlugin:
            class manifest:
                name = "fake_plugin"
            def __init__(self):
                self.manifest = type("m", (), {"name": "fake_plugin"})()
            def my_action(self):
                pass
            def my_filter(self, v):
                return v
        plugin = FakePlugin()
        reg.register_action("test.action", plugin.my_action)
        reg.register_filter("test.filter", plugin.my_filter)
        assert reg.has_action("test.action")
        assert reg.has_filter("test.filter")
        reg.unregister_all_for_plugin("fake_plugin")
        assert not reg.has_action("test.action")
        assert not reg.has_filter("test.filter")
    @pytest.mark.asyncio
    async def test_apply_filters_swallows_exceptions(self):
        """apply_filters logs but does not raise on callback errors."""
        reg = get_hook_registry()
        reg.register_filter("test.filter", lambda v: (_ for _ in ()).throw(ValueError("boom")))
        reg.register_filter("test.filter", lambda v: v + "!")
        result = await apply_filters("test.filter", "test")
        # First filter errored, second still ran
        assert result == "test!"
    def test_reset_for_testing(self):
        """_reset_for_testing clears all state."""
        reg = get_hook_registry()
        reg.register_action("test.action", lambda: None)
        reg.register_filter("test.filter", lambda v: v)
        reg._reset_for_testing()
        assert not reg.list_actions()
        assert not reg.list_filters()
@@ -0,0 +1,101 @@
 """Tests for PluginManifest validation: SemVer, hook names, marketplace fields."""
 from __future__ import annotations
 import pytest
 from app.plugins.manifest import PluginManifest
 class TestManifestValidation:
    def test_valid_min_app_version(self):
        """Valid SemVer min_app_version is accepted."""
        m = PluginManifest(
            name="test", version="1.0.0", display_name="Test",
            min_app_version="1.2.3",
        )
        assert m.min_app_version == "1.2.3"
    def test_default_min_app_version(self):
        """Default min_app_version is 0.0.0."""
        m = PluginManifest(name="test", version="1.0.0", display_name="Test")
        assert m.min_app_version == "0.0.0"
    def test_invalid_min_app_version(self):
        """Invalid SemVer min_app_version is rejected."""
        with pytest.raises(Exception):
            PluginManifest(
                name="test", version="1.0.0", display_name="Test",
                min_app_version="not-a-version",
            )
    def test_valid_hooks(self):
        """Valid hook names are accepted."""
        m = PluginManifest(
            name="test", version="1.0.0", display_name="Test",
            hooks=["contact.before_create", "mail.after_send"],
        )
        assert len(m.hooks) == 2
    def test_invalid_hook_name(self):
        """Invalid hook name format is rejected."""
        with pytest.raises(Exception):
            PluginManifest(
                name="test", version="1.0.0", display_name="Test",
                hooks=["InvalidHookName"],
            )
    def test_invalid_hook_no_dot(self):
        """Hook name without dot is rejected."""
        with pytest.raises(Exception):
            PluginManifest(
                name="test", version="1.0.0", display_name="Test",
                hooks=["contact"],
            )
    def test_empty_hooks_allowed(self):
        """Empty hooks list is allowed."""
        m = PluginManifest(
            name="test", version="1.0.0", display_name="Test",
            hooks=[],
        )
        assert m.hooks == []
    def test_marketplace_fields_defaults(self):
        """All marketplace fields have correct defaults."""
        m = PluginManifest(name="test", version="1.0.0", display_name="Test")
        assert m.author == ""
        assert m.author_email == ""
        assert m.homepage == ""
        assert m.license == "MIT"
        assert m.icon == ""
        assert m.screenshots == []
        assert m.changelog == ""
        assert m.marketplace_tags == []
        assert m.price == 0.0
        assert m.contract_version == "1.0.0"
    def test_marketplace_fields_set(self):
        """Marketplace fields can be set."""
        m = PluginManifest(
            name="test", version="1.0.0", display_name="Test",
            author="Jane Doe",
            author_email="jane@example.com",
            homepage="https://example.com/plugin",
            license="Apache-2.0",
            icon="📦",
            screenshots=["https://example.com/s1.png"],
            changelog="https://example.com/changelog.md",
            marketplace_tags=["crm", "ai"],
            price=9.99,
            contract_version="2.0.0",
        )
        assert m.author == "Jane Doe"
        assert m.license == "Apache-2.0"
        assert m.price == 9.99
        assert m.contract_version == "2.0.0"
    def test_name_validation_lowercase(self):
        """Plugin name is lowercased."""
        m = PluginManifest(name="MyPlugin", version="1.0.0", display_name="Test")
        assert m.name == "myplugin"
@@ -0,0 +1,157 @@
 """Tests for marketplace plugin system: signature, quarantine, allowlist."""
 from __future__ import annotations
 import hashlib
 import tempfile
 from pathlib import Path
 import pytest
 from app.plugins.signature import PluginSignature
 from app.plugins.quarantine import (
    QuarantineError,
    _check_dangerous_imports,
    _check_migration_sql,
    _validate_manifest,
 )
 class TestPluginSignature:
    def test_compute_hash(self, tmp_path):
        """compute_hash returns a valid SHA-256 hex string."""
        test_file = tmp_path / "test.zip"
        test_file.write_bytes(b"test content")
        h = PluginSignature.compute_hash(test_file)
        assert len(h) == 64  # SHA-256 hex
        assert h == hashlib.sha256(b"test content").hexdigest()
    def test_verify_signature_without_pynacl(self, tmp_path):
        """verify_signature returns False if PyNaCl is not installed."""
        test_file = tmp_path / "test.zip"
        test_file.write_bytes(b"test")
        # Without PyNaCl installed, returns False
        result = PluginSignature.verify_signature(test_file, b"sig", b"key")
        assert result in (False, True)  # Depends on whether pynacl is installed
 class TestQuarantineValidation:
    def test_validate_manifest_valid(self, tmp_path):
        """_validate_manifest passes for a valid plugin structure."""
        plugin_dir = tmp_path / "test_plugin"
        plugin_dir.mkdir()
        (plugin_dir / "plugin.py").write_text(
            "from app.plugins.base import BasePlugin\n"
            "from app.plugins.manifest import PluginManifest\n"
            "class TestPlugin(BasePlugin):\n"
            "    manifest = PluginManifest(name='test', version='1.0.0', display_name='Test')\n"
        )
        result = _validate_manifest(plugin_dir)
        assert result["has_manifest"] is True
    def test_validate_manifest_missing(self, tmp_path):
        """_validate_manifest raises for missing plugin.py."""
        with pytest.raises(QuarantineError, match="plugin.py or __init__.py"):
            _validate_manifest(tmp_path)
    def test_validate_manifest_no_manifest(self, tmp_path):
        """_validate_manifest raises when PluginManifest is missing."""
        plugin_dir = tmp_path / "test_plugin"
        plugin_dir.mkdir()
        (plugin_dir / "plugin.py").write_text("print('hello')")
        with pytest.raises(QuarantineError, match="PluginManifest"):
            _validate_manifest(plugin_dir)
    def test_check_dangerous_imports_clean(self, tmp_path):
        """_check_dangerous_imports returns empty for safe code."""
        plugin_dir = tmp_path / "safe_plugin"
        plugin_dir.mkdir()
        (plugin_dir / "plugin.py").write_text(
            "import logging\n"
            "from app.plugins.base import BasePlugin\n"
        )
        result = _check_dangerous_imports(plugin_dir)
        assert result == []
    def test_check_dangerous_imports_found(self, tmp_path):
        """_check_dangerous_imports detects dangerous patterns."""
        plugin_dir = tmp_path / "dangerous_plugin"
        plugin_dir.mkdir()
        (plugin_dir / "plugin.py").write_text(
            "import os\n"
            "os.system('rm -rf /')\n"
        )
        result = _check_dangerous_imports(plugin_dir)
        assert len(result) > 0
        assert any("os.system" in r for r in result)
    def test_check_migration_sql_no_migrations(self, tmp_path):
        """_check_migration_sql returns empty when no migrations dir."""
        result = _check_migration_sql(tmp_path)
        assert result == []
    def test_check_migration_sql_valid(self, tmp_path):
        """_check_migration_sql passes for valid SQL with tenant_id."""
        migrations = tmp_path / "migrations"
        migrations.mkdir()
        (migrations / "0001_initial.sql").write_text(
            "CREATE TABLE items (id UUID, tenant_id UUID NOT NULL);\n"
        )
        result = _check_migration_sql(tmp_path)
        assert result == []
    def test_check_migration_sql_missing_tenant_id(self, tmp_path):
        """_check_migration_sql detects missing tenant_id."""
        migrations = tmp_path / "migrations"
        migrations.mkdir()
        (migrations / "0001_initial.sql").write_text(
            "CREATE TABLE items (id UUID);\n"
        )
        result = _check_migration_sql(tmp_path)
        assert len(result) > 0
        assert "tenant_id" in result[0]
    def test_check_migration_sql_drop_database(self, tmp_path):
        """_check_migration_sql detects DROP DATABASE."""
        migrations = tmp_path / "migrations"
        migrations.mkdir()
        (migrations / "0001_initial.sql").write_text(
            "DROP DATABASE leocrm;\n"
        )
        result = _check_migration_sql(tmp_path)
        assert len(result) > 0
        assert "DROP" in result[0]
 class TestManifestMarketplaceFields:
    def test_manifest_has_marketplace_fields(self):
        """PluginManifest has marketplace fields."""
        from app.plugins.manifest import PluginManifest
        m = PluginManifest(
            name="test",
            version="1.0.0",
            display_name="Test",
            author="Test Author",
            license="MIT",
            min_app_version="1.0.0",
        )
        assert m.author == "Test Author"
        assert m.license == "MIT"
        assert m.min_app_version == "1.0.0"
        assert m.contract_version == "1.0.0"
        assert m.hooks == []
    def test_manifest_marketplace_optional_fields(self):
        """PluginManifest marketplace fields have defaults."""
        from app.plugins.manifest import PluginManifest
        m = PluginManifest(
            name="test",
            version="1.0.0",
            display_name="Test",
        )
        assert m.author == ""
        assert m.homepage == ""
        assert m.license == "MIT"
        assert m.price == 0.0
        assert m.screenshots == []
        assert m.marketplace_tags == []
@@ -0,0 +1,107 @@
 """Tests for the SemVer comparison module."""
 from __future__ import annotations
 import pytest
 from app.plugins.semver import (
    SemVer,
    compare_versions,
    is_breaking_change,
    is_compatible,
 )
 class TestSemVerParse:
    def test_parse_simple(self):
        v = SemVer.parse("1.2.3")
        assert v.major == 1
        assert v.minor == 2
        assert v.patch == 3
        assert v.prerelease == ""
    def test_parse_with_prerelease(self):
        v = SemVer.parse("1.0.0-alpha.1")
        assert v.major == 1
        assert v.minor == 0
        assert v.patch == 0
        assert v.prerelease == "alpha.1"
    def test_parse_with_v_prefix(self):
        v = SemVer.parse("v2.0.0")
        assert v.major == 2
    def test_parse_invalid(self):
        with pytest.raises(ValueError):
            SemVer.parse("not-a-version")
    def test_parse_empty(self):
        with pytest.raises(ValueError):
            SemVer.parse("")
    def test_parse_two_parts(self):
        with pytest.raises(ValueError):
            SemVer.parse("1.2")
    def test_parse_four_parts(self):
        with pytest.raises(ValueError):
            SemVer.parse("1.2.3.4")
 class TestSemVerComparison:
    def test_equal(self):
        assert SemVer.parse("1.0.0") == SemVer.parse("1.0.0")
    def test_less_than(self):
        assert SemVer.parse("1.0.0") < SemVer.parse("1.0.1")
        assert SemVer.parse("1.0.0") < SemVer.parse("1.1.0")
        assert SemVer.parse("1.0.0") < SemVer.parse("2.0.0")
    def test_greater_than(self):
        assert SemVer.parse("1.0.1") > SemVer.parse("1.0.0")
        assert SemVer.parse("2.0.0") > SemVer.parse("1.9.9")
    def test_prerelease_lower_than_release(self):
        assert SemVer.parse("1.0.0-alpha") < SemVer.parse("1.0.0")
        assert SemVer.parse("1.0.0-beta.1") < SemVer.parse("1.0.0")
    def test_prerelease_ordering(self):
        assert SemVer.parse("1.0.0-alpha.1") < SemVer.parse("1.0.0-alpha.2")
        assert SemVer.parse("1.0.0-alpha") < SemVer.parse("1.0.0-beta")
    def test_str(self):
        assert str(SemVer.parse("1.2.3")) == "1.2.3"
        assert str(SemVer.parse("1.0.0-beta.1")) == "1.0.0-beta.1"
 class TestSemVerCompatibility:
    def test_breaking_change(self):
        assert is_breaking_change("1.0.0", "2.0.0")
        assert not is_breaking_change("1.0.0", "1.5.0")
    def test_compatible_same_major(self):
        assert is_compatible("1.5.0", "1.0.0")
        assert not is_compatible("1.0.0", "1.5.0")
    def test_compatible_higher_major(self):
        assert is_compatible("2.0.0", "1.0.0")
        assert not is_compatible("1.0.0", "2.0.0")
    def test_is_upgrade_from(self):
        assert SemVer.parse("1.1.0").is_upgrade_from(SemVer.parse("1.0.0"))
        assert not SemVer.parse("1.0.0").is_upgrade_from(SemVer.parse("1.1.0"))
    def test_is_downgrade_from(self):
        assert SemVer.parse("1.0.0").is_downgrade_from(SemVer.parse("1.1.0"))
        assert not SemVer.parse("1.1.0").is_downgrade_from(SemVer.parse("1.0.0"))
 class TestCompareVersions:
    def test_compare_equal(self):
        assert compare_versions("1.0.0", "1.0.0") == 0
    def test_compare_less(self):
        assert compare_versions("1.0.0", "1.0.1") == -1
    def test_compare_greater(self):
        assert compare_versions("1.1.0", "1.0.0") == 1
@@ -0,0 +1,67 @@
 """Tests for plugin versioning: upgrade, downgrade, compatibility checks."""
 from __future__ import annotations
 import pytest
 from app.plugins.semver import SemVer
 from app.plugins.manifest import PluginManifest
 class TestManifestVersioning:
    def test_manifest_has_min_app_version(self):
        """PluginManifest has min_app_version field."""
        m = PluginManifest(
            name="test",
            version="1.0.0",
            display_name="Test",
        )
        assert hasattr(m, "min_app_version")
        assert m.min_app_version == "0.0.0"
    def test_manifest_with_min_app_version(self):
        """PluginManifest can set min_app_version."""
        m = PluginManifest(
            name="test",
            version="1.0.0",
            display_name="Test",
            min_app_version="1.5.0",
        )
        assert m.min_app_version == "1.5.0"
    def test_manifest_extra_forbid_still_works(self):
        """Manifest still rejects unknown fields."""
        with pytest.raises(Exception):
            PluginManifest(
                name="test",
                version="1.0.0",
                display_name="Test",
                unknown_field="value",
            )
 class TestVersionComparison:
    def test_upgrade_detection(self):
        """SemVer correctly detects upgrades."""
        old = SemVer.parse("1.0.0")
        new = SemVer.parse("1.1.0")
        assert new.is_upgrade_from(old)
        assert not old.is_upgrade_from(new)
    def test_downgrade_detection(self):
        """SemVer correctly detects downgrades."""
        old = SemVer.parse("1.1.0")
        new = SemVer.parse("1.0.0")
        assert new.is_downgrade_from(old)
    def test_breaking_change_detection(self):
        """Major version change is a breaking change."""
        assert SemVer.parse("1.0.0").is_breaking_change(SemVer.parse("2.0.0"))
        assert not SemVer.parse("1.0.0").is_breaking_change(SemVer.parse("1.5.0"))
    def test_compatibility_check(self):
        """Version compatibility works correctly."""
        assert SemVer.parse("1.5.0").is_compatible_with(SemVer.parse("1.0.0"))
        assert not SemVer.parse("1.0.0").is_compatible_with(SemVer.parse("1.5.0"))
        assert SemVer.parse("2.0.0").is_compatible_with(SemVer.parse("1.0.0"))
        assert not SemVer.parse("1.0.0").is_compatible_with(SemVer.parse("2.0.0"))