# Portabilität: UNIVERSAL
# Version: 2.1.0
# Zuletzt validiert: 2026-05-06 (Codex)
# Nächste Prüfung: 2026-11-06

BACH PLUGIN-API
===============

Stand: 2026-05-06

Die Plugin-API ermöglicht dynamische Erweiterung von BACH zur Laufzeit.
Plugins können Tools, Hooks, Workflows und Handler registrieren --
imperativ (via Code) oder deklarativ (via `plugin.json`).

CLI-BEFEHLE
-----------
  bach plugins list              Alle geladenen Plugins anzeigen
  bach plugins inspect <pfad>    Manifest-first Vorschau ohne Runtime-Load
  bach plugins load <pfad>       Plugin aus plugin.json laden
  bach plugins unload <name>     Plugin entladen
  bach plugins tools             Alle Plugin-Tools anzeigen
  bach plugins info <name>       Details zu einem Plugin
  bach plugins create <name>     Plugin-Manifest erstellen (Scaffolding)
  bach plugins caps              Capability-Profile anzeigen
  bach plugins trust <name> <l>  Trust-Level eines Plugins ändern
  bach plugins audit [limit]     Letzte Capability-Prüfungen anzeigen

  Kurzform:
  bach plugin list               (Alias: plugin -> plugins)

API-NUTZUNG (Imperativ)
-----------------------
  from core.plugin_api import plugins
  # Oder: from bach_api import plugins

  # Tool registrieren
  def mein_tool(text):
      return f"Verarbeitet: {text}"

  plugins.register_tool("mein_tool", mein_tool, "Beschreibung")
  result = plugins.call_tool("mein_tool", "Eingabe")

  # Hook registrieren
  def on_task(ctx):
      print(f"Task erstellt: {ctx['task_id']}")

  plugins.register_hook("after_task_create", on_task, plugin="mein-plugin")

  # Handler registrieren (neuer CLI-Befehl)
  from hub.base import BaseHandler
  class MeinHandler(BaseHandler):
      ...

  plugins.register_handler("mein_cmd", MeinHandler, plugin="mein-plugin")

  # Workflow erstellen
  plugins.register_workflow("mein-workflow", "# Workflow\n...", plugin="mein-plugin")

  # Verwaltung
  print(plugins.list_plugins())
  plugins.inspect_plugin("plugins/mein-plugin/plugin.json")
  plugins.unload_plugin("mein-plugin")

PLUGIN-MANIFEST (Deklarativ)
----------------------------
Erstelle ein `plugin.json` für automatisches Laden:

  bach plugins create mein-plugin

Manifest-Format (`plugin.json`):
  {
    "name": "mein-plugin",
    "manifest_version": "1.1",
    "version": "1.0.0",
    "description": "Was das Plugin tut",
    "author": "claude",
    "source": "goldstandard",
    "capabilities": ["db_read", "hook_listen"],
    "activation": {"mode": "manual", "enabled": true},
    "providers": [],
    "models": [],
    "setup": {
      "requires": ["Node.js", "Claude Code"],
      "env": ["ANTHROPIC_API_KEY"],
      "notes": "Warum das Setup gebraucht wird",
      "fail_closed": true,
      "surfaces": ["shell", "mcp"],
      "checks": [
        {"type": "command_exists", "command": "npx"},
        {"type": "mcp_server_known", "package": "ellmos-codecommander-mcp"}
      ]
    },
    "hooks": [
      {
        "event": "after_task_done",
        "module": "handlers.py",
        "handler": "on_task_done",
        "priority": 50
      }
    ],
    "handlers": [
      {"name": "mein_cmd", "file": "mein_handler.py"}
    ],
    "workflows": [
      {"name": "mein-workflow", "file": "workflow.md"}
    ]
  }

Laden:
  bach plugins inspect plugins/mein-plugin/plugin.json
  bach plugins load plugins/mein-plugin/plugin.json

REGISTRIERUNGS-TYPEN
--------------------
  Typ          API-Methode              Beschreibung
  ---------    ----------------------   ---------------------------------
  Tool         register_tool()          Callable als Werkzeug registrieren
  Hook         register_hook()          Event-Listener registrieren
  Workflow     register_workflow()      Markdown-Datei erstellen
  Handler      register_handler()       Neuer CLI-Befehl zur Laufzeit

PLUGIN-LIFECYCLE
----------------
  1. Erstellen:  bach plugins create <name>
  2. Entwickeln: plugin.json + handlers.py bearbeiten
  3. Prüfen:    bach plugins inspect <pfad/plugin.json>
  4. Laden:      bach plugins load <pfad/plugin.json>
  5. Nutzen:     Hooks feuern, Tools aufrufen, CLI-Befehle nutzen
  6. Entladen:   bach plugins unload <name>

CAPABILITY-SYSTEM (Stufe 1 Sandbox)
-----------------------------------
Plugins deklarieren benötigte Fähigkeiten. BACH prüft und
durchsetzt basierend auf dem Trust-Level der Quelle.

  Definierte Capabilities:
    db_read          Datenbank lesen
    db_write         Datenbank schreiben
    file_read        Dateien lesen
    file_write       Dateien schreiben
    hook_listen      Auf Events lauschen
    hook_emit        Events emittieren
    tool_register    Neue Tools registrieren
    handler_register Neue CLI-Handler registrieren
    workflow_create  Workflows erstellen
    network          Netzwerk-Zugriff (HTTP/API)
    shell            Shell-Befehle ausführen
    desktop          Desktop-/GUI-Automation ausführen
    mcp              MCP-Server konfigurieren oder anbinden

  Trust-Profile (verknüpft mit `data/skill_sources.json`):
    goldstandard     trust=100  Alle Capabilities
    trusted          trust=80   Alles ausser shell + desktop + mcp + network
    untrusted        trust=20   Nur db_read, file_read, hook_listen
    blacklist        trust=0    Nichts erlaubt

  Enforcement:
    - register_tool()     prüft `tool_register`
    - register_hook()     prüft `hook_listen`
    - register_handler()  prüft `handler_register`
    - register_workflow() prüft `workflow_create`
    - load_plugin()       prüft alle angeforderten Capabilities
    - inspect/load prüft Setup-Guards fail-closed für shell/desktop/mcp

SETUP-GUARDS (SEC-PLUGIN-003)
-----------------------------
Starker Zugriff über Setup-Metadaten wird vor dem Runtime-Import blockiert,
wenn Voraussetzungen nicht explizit und fail-closed beschrieben sind.

  Gefaehrliche Oberflaechen:
    shell, desktop, mcp

  Pflicht bei solchen Setups:
    - `setup.fail_closed = true`
    - `setup.checks = [...]` mit passenden Guard-Checks

  Unterstützte Check-Typen:
    command_exists
    env_present
    path_exists
    python_import
    mcp_server_known
    desktop_enabled
    permission_flag

  Erwartete Check-Abdeckung:
    shell   -> command_exists, env_present, path_exists, python_import
    desktop -> desktop_enabled, path_exists, command_exists, env_present
    mcp     -> mcp_server_known, command_exists, env_present, path_exists

  Beispiel:
    "setup": {
      "requires": ["Claude Desktop", "Node.js"],
      "fail_closed": true,
      "surfaces": ["mcp"],
      "checks": [
        {"type": "command_exists", "command": "npx"},
        {"type": "mcp_server_known", "package": "ellmos-codecommander-mcp"}
      ]
    }

SICHERHEIT
----------
  - Capability-Enforcement in allen `register_*()` Methoden
  - Trust-Level aus `skill_sources.json` (4-Stufen-System)
  - Manifest-first Inspection: Aktivierung, Provider, Modelle, Setup ohne Runtime-Import
  - Fail-closed Setup-Guards für Shell/Desktop/MCP vor Plugin-Load
  - Statische Code-Analyse: eval, exec, subprocess, os.system
  - Audit-Log für Nachvollziehbarkeit
  - Fehlerhafte Hooks werden gefangen, brechen nichts ab
  - Plugin-Entladen entfernt alle Registrierungen sauber
  - Audit via: `bach plugins audit`, `bach plugins info <name>`

ARCHITEKTUR
-----------
  core/capabilities.py     CapabilityManager-Singleton (Enforcement)
  core/plugin_api.py       PluginRegistry-Singleton (Plugin-Verwaltung)
  hub/plugins.py           CLI-Handler (`bach plugins ...`)
  core/hooks.py            Hook-Framework
  data/skill_sources.json  Trust-Profile und Capability-Zuordnung

SIEHE AUCH
----------
  bach help hooks          Hook-Framework
  bach help skills         Skill-System
  bach help self-extension Selbsterweiterungs-System
  bach help cli            CLI-Konventionen
