# Portabilität: UNIVERSAL
# Version: 1.0.0
# Zuletzt validiert: 2026-03-04

EXTENSIONS - Desktop-Tools und Spezial-Apps
=============================================

STAND: 2026-03-04

Der Extensions Handler verwaltet externe BACH-Extensions: Desktop-Anwendungen,
Spezial-Tools und Desktop-GUIs, die nicht Teil des Kern-Systems sind.
Extensions werden im Verzeichnis extensions/ abgelegt und können synchronisiert,
durchsucht und gestartet werden.

STRUKTUR
--------

  extensions/
    ext1/
      SKILL.md            Extension-Metadaten
      START.bat           Startdatei (Windows)
      README.md           Dokumentation
      main.py             Hauptprogramm
      requirements.txt    Python-Dependencies
    ext2/
      ...

HANDLER-NAME
------------

extensions

CLI-BEFEHLE (bach extensions)
-----------------------------

  list                  Alle Extensions auflisten
  show <name>           Details zu einer Extension anzeigen
  run <name>            Extension starten (START.bat oder main.py)
  sync                  Extensions mit Datenbank synchronisieren
  search <term>         Extensions durchsuchen

BESCHREIBUNG
------------

Extensions sind modulare, portable Desktop-Anwendungen mit folgenden Merkmalen:

- Jede Extension hat ein eigenes Verzeichnis mit SKILL.md
- START.bat optional für Windows-Start (Fallback: direkte Python-Ausführung)
- SKILL.md oder README.md enthalten Beschreibungen
- Automatische Erkennung von Hauptdateien: main.py, app.py, <name>.py
- Sync in DB registriert Extensions als Skills (type='extension')

OPERATIONEN
-----------

list:    Auflistung aller vorhandenen Extensions mit:
         - Anzahl .py-Dateien
         - Flags: [SKILL] wenn SKILL.md, [START] wenn START.bat
         - Beschreibung (aus SKILL.md oder README.md)
         - Speicherort

show:    Detailanzeige einer Extension:
         - Vollständiger Pfad
         - Dateiauflistung mit Grossen
         - SKILL.md Vorschau (bis 500 Zeichen)
         - Fuzzy-Matching bei nicht exaktem Namen

run:     Startet eine Extension:
         - Windows: START.bat ausführen (neues Fenster)
         - Fallback: Hauptdatei direkt mit Python starten
         - Hauptdatei nach Priorität: main.py > app.py > <name>.py

sync:    Synchronisiert Extensions mit Datenbank (bach.db):
         - Fügt neue Extensions hinzu (type='extension')
         - Aktualisiert Pfade und Beschreibungen existierender Extensions
         - --dry-run zeigt Änderungen an ohne zu schreiben

search:  Volltextsuche nach:
         - Extension-Name (Case-insensitive)
         - Beschreibung (Case-insensitive)
         - Zeigt Treffer mit Snippet

BEISPIELE
---------

  # Alle Extensions auflisten
  bach extensions list

  # Details zu einer Extension (z.B. 'myapp')
  bach extensions show myapp

  # Extension starten
  bach extensions run myapp
  bach extensions run knowledgedigest

  # In Datenbank synchronisieren (neu erkannte Extensions hinzufügen)
  bach extensions sync
  bach extensions sync --dry-run      # Vorschau ohne Änderungen

  # Nach Extension suchen
  bach extensions search "data"
  bach extensions search "analysis"

DATEIEN
-------

  hub/extensions.py                  Handler-Implementation
  extensions/                        Extensions-Verzeichnis (relativ zu system/)
  extensions/<name>/SKILL.md         Extension-Metadaten
  extensions/<name>/START.bat        Windows-Startdatei
  extensions/<name>/README.md        Dokumentation
  extensions/<name>/requirements.txt Dependencies (optional)
  data/bach.db                       Datenbank mit Extension-Registry

DATENBANK
---------

  bach.db:
    skills                Table mit type='extension'
      - name              Extension-Name
      - type              'extension'
      - category          Kategorie (z.B. 'extension')
      - path              Verzeichnispfad
      - description       Beschreibung
      - is_active         1 (enabled) oder 0 (disabled)
      - version           Version (default: 1.0.0)
      - dist_type         2 (Extension)

SKILL.md FORMAT
---------------

Minimales Format:

  description: Kurzbeschreibung der Extension
  author: Name
  version: 1.0.0
  category: tool|gui|analysis|utils

Die Beschreibung wird vom Handler automatisch aus SKILL.md oder README.md
extrahiert und in der Datenbankabgelegt.

STARTMECHANISMUS
----------------

1. bash extensions run <name> wird aufgerufen
2. Handler sucht in extensions/<name>/
3. START.bat vorhanden? -> Windows: cmd /c start <START.bat>
4. Sonst: Hauptdatei suchen (main.py, app.py, <name>.py)
5. Hauptdatei vorhanden? -> python <hauptdatei>
6. Fehler wenn keine Startdatei gefunden

Auf Non-Windows-Systemen: START.bat wird ignoriert, nur Python-Fallback

SIEHE AUCH
----------

  bach --help skills          SKILL.md-System (Metadaten)
  bach --help dist            Distribution und Packaging
  extensions/                 Extensions-Verzeichnis
  Forschung/_tools/           Forschungs-Tools (Beispiele)
