# Portabilitaet: UNIVERSAL
# Zuletzt validiert: 2026-01-28 (Gemini)
# Naechste Pruefung: 2027-01-28
# Quellen: [skills/_protocols/cli-aenderung-checkliste.md]

CLI ARCHITEKTUR & AENDERUNGEN (KONZEPT)
=======================================

Stand: 2026-01-28

HINTERGRUND: WARUM DIESER PROZESS?
----------------------------------
Das BACH CLI (`bach.py`) ist der zentrale Einstiegspunkt fuer alle Systeminteraktionen. Wenn hier Befehle "einfach so" hinzugefuegt werden, entsteht ein unwartbarer Monolith. Daher folgt BACH bei CLI-Befehlen strengen Architektur-Prinzipien.

ARCHITEKTUR-PRINZIPIEN
----------------------

### 1. Lazy Loading (Handler-Imports)
Um die Startzeit von `bach.py` minmal zu halten (< 100ms), werden Handler-Klassen nicht global importiert.
Stattdessen nutzen wir ein `handler_imports` Dictionary mit Lambdas:
```python
"<name>": lambda: _import_handler("<name>", "<Name>Handler")
```
Der Import passiert erst, wenn der Befehl tatsaechlich ausgefuehrt wird.

### 2. BaseHandler Pattern
Alle Handler erben von `hub.handlers.base.BaseHandler`. Dies garantiert:
- Konsistentes Error-Handling.
- Einheitliche Methodensignaturen (`handle(args)`).
- Zugriff auf gemeinsame Utilities.

### 3. Dual-Dispatch
Jeder Befehl muss auf zwei Arten aufrufbar sein:
- Als Subcommand: `bach befehl list`
- Als Flag: `bach --befehl list`
Dies erhoeht die Kompatibilitaet mit verschiedenen User-Gewohnheiten und Scripts.

### 4. "Did You Mean" Support
Durch das explizite Auflisten aller Befehle in `KNOWN_COMMANDS` kann das System Tippfehler erkennen und Korrekturen vorschlagen. Das verbessert die DX (Developer Experience) erheblich.

DER LIFECYCLE EINES BEFEHLS
---------------------------
1. **Entwurf:** Definition der Syntax (Arguments, Flags).
2. **Implementierung:** Isolation der Logik im Handler.
3. **Registrierung:** Bekanntmachen im Core (`bach.py`).
4. **Dokumentation:** Erstellung der Help-Datei (`docs/help/X.txt`).
5. **Veroeffentlichung:** Aufnahme in `SKILL.md`.

WARUM HELP-FILES PFLICHT SIND
-----------------------------
BACH verfolgt den Ansatz "Documentation First". Ein Befehl ohne Help-Datei existiert fuer den User (und die KI) faktisch nicht. Die Help-Datei ist die "Source of Truth" fuer die erwartete Funktionsweise.

SIEHE AUCH
----------
docs/help/cli.txt                 CLI-Konventionen
docs/help/coding.txt              Coding-Standards
skills/_protocols/cli-aenderung-checkliste.md  Implementierungs-Checkliste
