Brancheneinstufung2/README_dev_session.md

dev_session.py - Notion Development Session Manager

Übersicht

dev_session.py ist ein interaktives Kommandozeilen-Tool (CLI), das den Entwicklungs-Workflow durch die Integration mit Notion optimiert. Es ermöglicht Entwicklern, ein Projekt und einen Task auszuwählen und den Task-Status automatisch zu aktualisieren.

Wichtige Architekturänderung: Das Skript dev_session.py startet die Gemini CLI nicht mehr direkt. Stattdessen generiert es einen formatierten Kontext und gibt diesen auf der Standardausgabe aus. Das übergeordnete start-gemini.sh-Skript fängt diesen Kontext auf und startet dann die Gemini CLI in einer sauberen, interaktiven Sitzung mit dem korrekten Startkontext. Dieser zweistufige Prozess stellt sicher, dass die Gemini CLI mit allen erforderlichen Tools und in der korrekten Umgebung läuft.

Funktionen

• Interaktive Projekt- und Task-Auswahl: Wähle Projekte und Tasks direkt aus deinen Notion-Datenbanken.
• Automatisches Status-Update: Der Status des ausgewählten Tasks wird automatisch auf 'Doing' (oder den ersten verfügbaren Status in neuen Projekten) gesetzt, um deinen Fortschritt in Notion widerzuspiegeln.
• Task-Erstellung: Erstelle neue Tasks direkt über das CLI im Kontext des ausgewählten Projekts.
• Dynamische Status-Erkennung: Fragt Notion API nach verfügbaren Status-Optionen ab, um Kompatibilität mit verschiedenen Notion-Templates zu gewährleisten.
• Gemini CLI Kontext-Generierung: Erzeugt einen strukturierten Kontext-Prompt, der alle relevanten Informationen (Projekt, Task, Task-ID, vorgeschlagener Git-Branch-Name) für die Gemini CLI enthält.
• Vorgeschlagene Git Branch-Benennung: Erstellt einen konsistenten Git-Branch-Namen basierend auf der Task-ID und dem Task-Titel.

Voraussetzungen

• Docker: Das gesamte Setup ist containerisiert, um Abhängigkeitskonflikte zu vermeiden.
• Notion Integration Token: Ein Notion API-Token mit Zugriff auf Ihre "Projects"- und "Tasks"-Datenbanken.

Installation und Einrichtung

Das Setup ist so konzipiert, dass es mit minimalem Aufwand sofort einsatzbereit ist.

1. Notion API Key:

   • Stellen Sie sicher, dass Sie einen Notion Integration Token haben.
   • Das Skript fragt beim ersten Start interaktiv nach dem Token. Sie können es auch als Umgebungsvariable NOTION_API_KEY in einer .env-Datei im Hauptverzeichnis speichern, um diesen Schritt zu überspringen.
   • Gewähren Sie Ihrer Notion-Integration Zugriff auf die relevanten "Projects"- und "Tasks"-Datenbanken.

2. Abhängigkeiten: Alle notwendigen Abhängigkeiten (Python, requests, python-dotenv) sind im Dockerfile (gemini.Dockerfile) definiert und werden automatisch im Container installiert. Es ist keine manuelle Installation via pip erforderlich.

Nutzung

1. Sitzung starten

Das start-gemini.sh-Skript orchestriert den gesamten Startvorgang.

./start-gemini.sh

Was im Hintergrund passiert:

1. Das Skript führt dev_session.py in einem temporären Docker-Container aus.
2. Sie durchlaufen den interaktiven Auswahlprozess für Projekt und Task wie gewohnt.
3. Nach Ihrer Auswahl gibt dev_session.py den generierten Kontext für die Gemini CLI aus und beendet sich.
4. start-gemini.sh fängt diese Ausgabe ab und extrahiert den Kontext.
5. Anschließend startet das Skript einen neuen, sauberen Docker-Container mit der Gemini CLI und übergibt den extrahierten Kontext als Start-Prompt.

Dieser Prozess stellt sicher, dass Ihre interaktive Gemini-Sitzung von der Notion-API-Logik entkoppelt ist und in einer stabilen Umgebung läuft.

2. Sitzung abschließen

Wenn Sie die Arbeit an einem Task beendet haben, können Sie die Sitzung über den folgenden Befehl abschließen. Dieser Befehl muss im Terminal des Hosts ausgeführt werden, während der Container (gemini-session) noch läuft.

docker exec -it gemini-session python3 dev_session.py --done

Dieser Befehl:

• Setzt den Status des Notion-Tasks auf "Done" (oder den finalen Status in Ihrer Konfiguration).
• Löscht die lokale Session-Datei (.session_info.json).
• Deinstalliert den Git-Hook.

3. Automatisches Notion-Feedback (Git-Hook)

Beim Starten einer Sitzung wird automatisch ein post-commit-Git-Hook installiert.

• Funktion: Nach jedem git commit wird die Commit-Nachricht automatisch als Kommentar an den verknüpften Notion-Task gesendet.
• Voraussetzung: Funktioniert nur für Commits, die im gemini-session-Container oder auf dem Host-System (mit installiertem requests) gemacht werden, während die Session aktiv ist.
• Deinstallation: Der Hook wird beim Abschluss der Sitzung mit --done automatisch wieder entfernt.

Beispiel-Interaktion (gekürzt)

Die interaktive Auswahl von Projekt und Task bleibt unverändert:

Starte interaktive Entwicklungs-Session...
Bitte gib deinen Notion API Key ein (Eingabe wird nicht angezeigt): ****************
Suche nach Datenbank 'Projects [UT]' in Notion...
Datenbank 'Projects [UT]' gefunden mit ID: <PROJEKTE_DB_ID>

An welchem Projekt möchtest du arbeiten?
[1] My Awesome Project
[2] Sync Engine
[...]
Bitte wähle eine Nummer: 2
...

Nach der Auswahl wird automatisch die Gemini CLI gestartet.

Git Branch Benennungs-Konvention

Das Skript schlägt automatisch einen Git-Branch-Namen vor, der dem Muster feature/task-{kurze_task_id}-{task_titel_slug} folgt.

• feature/task-: Ein Präfix, das den Branch-Typ und die Beziehung zu einem Notion-Task anzeigt.
• {kurze_task_id}: Die ersten 8 Zeichen der Notion Task ID, für eine eindeutige Referenz.
• {task_titel_slug}: Eine "Slugified"-Version des Task-Titels (Kleinbuchstaben, Leerzeichen durch Bindestriche ersetzt, Sonderzeichen entfernt).

Beispiel: feature/task-2f388f42-create-readmemd-for-devsessionpy

Wichtige Hinweise

• Stelle sicher, dass deine Notion-Datenbanken die Property Status mit mindestens einer Statusoption haben.
• Der Readme Path wird dynamisch aus dem in Notion ausgewählten Projekt geladen. Falls in Notion kein spezifischer Pfad hinterlegt ist, wird standardmäßig readme.md verwendet. Dies eliminiert die Notwendigkeit einer manuellen project_to_path_map im Skript.

Entwicklung & Troubleshooting des Start-Skripts

Das Start-Skript (start-gemini.sh und die Entwicklungsversion start-gemini-dev.sh) hat mehrere Iterationen durchlaufen, um die aktuelle, stabile Funktionalität zu erreichen. Die wesentlichen Herausforderungen und deren Lösungen sind hier dokumentiert.

Problem 1: Fehlende Interaktivität

Die erste Version des Skripts hat die Ausgabe von dev_session.py direkt in eine Variable umgeleitet (OUTPUT=$(docker run ...)), um den Kontext für Gemini zu extrahieren.

• Problem: Die interaktiven input()-Aufforderungen von Python wurden nicht im Terminal des Benutzers angezeigt, da die Standardausgabe (stdout) vollständig in die Variable geschrieben wurde. Die Sitzung schien zu hängen.

• Lösung: Umstellung auf den tee-Befehl. Der docker run-Befehl wird nun so ausgeführt, dass seine Ausgabe gleichzeitig (tee) auf dem Bildschirm angezeigt UND in eine temporäre Datei geschrieben wird. Nachdem der Benutzer seine Auswahl getroffen hat, wird der Kontext aus dieser temporären Datei ausgelesen.

  # Gekürztes Beispiel
  TEMP_FILE=$(mktemp)
  docker run -it ... python3 dev_session.py | tee "$TEMP_FILE"
  CLI_CONTEXT=$(sed ... "$TEMP_FILE")
  rm "$TEMP_FILE"
  

Problem 2: Fehlerhafter Start-Parameter für Gemini

Die Gemini CLI erwartet den initialen Prompt über das Argument --prompt-interactive.

• Problem: Falsche Verwendung von --initial-prompt führte zu einem Fehler und verhinderte, dass der Kontext korrekt an die CLI übergeben wurde.
• Lösung: Korrektur des Arguments im docker run-Befehl für die Gemini CLI zu --prompt-interactive.

Problem 3: Konflikt durch nicht aufgeräumte Container

Der interaktive docker run-Befehl für dev_session.py erstellte einen temporären Container (z.B. gemini-dev-session-temp).

• Problem: Wenn das Skript vorzeitig beendet wurde, blieb dieser Container bestehen und blockierte den nächsten Start mit einem "container name already in use"-Fehler.

• Lösung: Am Anfang des Start-Skripts wurde eine explizite Aufräum-Anweisung hinzugefügt, die sowohl den Haupt-Container als auch den temporären Container vor dem Start entfernt.

  docker rm -f "gemini-dev-session" > /dev/null 2>&1
  docker rm -f "gemini-dev-session-temp" > /dev/null 2>&1
  

Diese Anpassungen haben zu dem robusten, zweistufigen Startprozess geführt, der nun eine nahtlose interaktive Auswahl und den anschließenden Start der Gemini CLI ermöglicht.