michaelschiemer/docs/console-dialog-mode.md

# Console Dialog Mode

## Übersicht

Der Console Dialog Mode bietet eine einfache, textbasierte interaktive Schnittstelle für die Console, ähnlich einem AI-Assistenten. Im Gegensatz zur grafischen TUI (Text User Interface) verwendet der Dialog-Modus eine klassische Prompt-Eingabe mit Command-Vorschlägen und History-Support.

## Features

### ✅ Hauptfunktionen

- **Prompt-basierte Eingabe**: Einfache Text-Eingabe wie bei einem AI-Assistenten
- **Readline-Support**: Tab-Completion und History-Navigation (falls php-readline installiert)
- **Command-Vorschläge**: Automatische Vorschläge bei Tippfehlern
- **Kontextuelle Hilfe**: Hilfe während der Eingabe
- **Command-History**: Nachverfolgung und Anzeige von verwendeten Commands
- **Einfache Ausgabe**: Keine komplexe Terminal-Manipulation

### 🎯 Optional Features

- **Tab-Completion**: Automatische Vervollständigung von Commands
- **History-Navigation**: ↑/↓ Tasten für Command-History (mit Readline)
- **Command-Suggestions**: Intelligente Vorschläge bei Tippfehlern (Levenshtein-Similarity)
- **Kontextuelle Hilfe**: Detaillierte Hilfe während der Eingabe
- **Quoted Arguments**: Unterstützung für Argumente in Anführungszeichen

## Verwendung

### Dialog-Modus starten

```bash
# Dialog-Modus explizit starten
php console.php --dialog

# Alternative (Alias)
php console.php --chat
```

### Vergleich: TUI vs. Dialog-Modus

| Feature | TUI (Standard) | Dialog-Modus |
|---------|----------------|--------------|
| Start | `php console.php` | `php console.php --dialog` |
| Interface | Grafische Navigation | Prompt-Eingabe |
| Navigation | Maus + Tastatur | Nur Tastatur |
| Completion | Limited | Tab-Completion |
| History | ✅ | ✅ (mit Readline) |
| Suggestions | ✅ | ✅ (intelligent) |
| Terminal-Anforderungen | Kompatibles Terminal | Funktioniert überall |

### Standard-Verhalten

Ohne Argumente startet die Console standardmäßig die **TUI**:

```bash
php console.php              # Startet TUI
php console.php --interactive # Startet TUI explizit
php console.php --tui         # Startet TUI explizit
php console.php -i            # Startet TUI explizit
```

## Built-in Commands

Der Dialog-Modus bietet mehrere Built-in Commands:

### `help` - Hilfe anzeigen

Zeigt alle verfügbaren Commands gruppiert nach Kategorien:

```bash
console> help
console> ?
console> :help
console> h
```

### `help <command>` - Detaillierte Hilfe

Zeigt detaillierte Hilfe für einen spezifischen Command:

```bash
console> help db:migrate
console> help user:create
```

### `history` - Command-History

Zeigt die letzten verwendeten Commands:

```bash
console> history
console> :history
```

### `clear` - Bildschirm löschen

Löscht den Bildschirm:

```bash
console> clear
console> :clear
```

### `exit` / `quit` - Beenden

Beendet den Dialog-Modus:

```bash
console> exit
console> quit
console> q
console> :q
```

## Command-Ausführung

### Basis-Commands

Commands werden direkt eingegeben:

```bash
console> db:migrate
console> user:list
console> cache:clear
```

### Commands mit Argumenten

Argumente werden nach dem Command angegeben:

```bash
console> user:create alice@example.com 25
console> db:migrate --force
```

### Quoted Arguments

Argumente mit Leerzeichen können in Anführungszeichen gesetzt werden:

```bash
console> user:create "John Doe" "john@example.com"
console> deploy "production environment"
```

## Readline-Support

### Installation

Für optimale Erfahrung sollte die `php-readline` Extension installiert sein:

```bash
# Ubuntu/Debian
sudo apt-get install php-readline

# macOS (Homebrew)
brew install php-readline

# Alpine
apk add php-readline
```

### Features mit Readline

Wenn Readline verfügbar ist, werden folgende Features aktiviert:

- **Tab-Completion**: Automatische Vervollständigung von Commands
- **History-Navigation**: ↑/↓ Tasten für Command-History
- **History-Persistenz**: History wird zwischen Sessions gespeichert

### Ohne Readline

Wenn Readline nicht verfügbar ist, funktioniert der Dialog-Modus weiterhin, aber ohne Tab-Completion und History-Navigation. Die History wird trotzdem gespeichert.

## Command-Vorschläge

### Automatische Vorschläge

Bei Tippfehlern werden automatisch ähnliche Commands vorgeschlagen:

```bash
console> db:migrat
Command 'db:migrat' not found.

Did you mean one of these?
  • db:migrate (95% match - prefix match)
  • db:migration:status (45% match - fuzzy match)
```

### Vorschlags-Algorithmus

Die Vorschläge basieren auf:

1. **Exact Match**: 100% Ähnlichkeit
2. **Prefix Match**: Command beginnt mit Eingabe (90% Ähnlichkeit)
3. **Contains Match**: Command enthält Eingabe (70% Ähnlichkeit)
4. **Levenshtein Distance**: Edit-Distanz-basierte Ähnlichkeit
5. **Word Similarity**: Wort-basierte Ähnlichkeit für Commands mit Doppelpunkt

### History-basierte Vorschläge

Commands aus der History haben Priorität:

- **Favorites**: Commands, die als Favoriten markiert sind
- **Recent**: Kürzlich verwendete Commands
- **Frequency**: Häufig verwendete Commands

## Kontextuelle Hilfe

### Während der Eingabe

Nach fehlgeschlagenen Commands wird kontextuelle Hilfe angezeigt:

```bash
console> db:migrate
Executing: db:migrate
────────────────────────────────────────────────────────────
✗ Command failed with exit code: 1
────────────────────────────────────────────────────────────

💡 Tip: Use "help db:migrate" for detailed help.
Description: Run database migrations
```

### Detaillierte Hilfe

Die detaillierte Hilfe zeigt:

- Command-Name und Beschreibung
- Usage-Beispiele
- Parameter-Dokumentation
- Optionen und Flags
- Beispiele

```bash
console> help db:migrate

📖 Command Help: db:migrate
════════════════════════════════════════════════════════════

Command: db:migrate
Description: Run database migrations

Usage:
  php console.php db:migrate [options]

Options:
  --force      Force migration execution
  --pretend    Show SQL without executing

Examples:
  php console.php db:migrate
  php console.php db:migrate --force
  php console.php db:migrate --pretend
```

## Command-History

### History-Verwaltung

Die History wird automatisch verwaltet:

- **Automatische Speicherung**: Jeder ausgeführte Command wird gespeichert
- **Persistenz**: History wird zwischen Sessions gespeichert
- **Deduplizierung**: Doppelte Commands werden aktualisiert, nicht dupliziert
- **Limit**: Standardmäßig werden 100 Commands gespeichert

### History anzeigen

```bash
console> history

📜 Command History
════════════════════════════════════════════════════════════

  1. db:migrate (used 5 times, last: 2024-01-15 10:30:45)
  2. user:create (used 3 times, last: 2024-01-15 09:15:22)
  3. cache:clear (used 2 times, last: 2024-01-14 16:45:10)
```

### History-Navigation (mit Readline)

Mit Readline können Sie durch die History navigieren:

- **↑**: Vorheriger Command
- **↓**: Nächster Command
- **Tab**: Command-Vervollständigung

## Workflow-Beispiel

```bash
$ php console.php --dialog

🤖 Console Dialog Mode
════════════════════════════════════════════════════════════

Available commands: 42
✓ Readline support enabled (Tab completion, ↑/↓ history)

Type "help" for available commands or "exit" to quit.

console> help
📚 Available Commands
════════════════════════════════════════════════════════════

Database:
  db:migrate
    Run database migrations
  db:seed
    Seed database with test data

User:
  user:create
    Create a new user
  user:list
    List all users

console> user:create alice@example.com 25
Executing: user:create
Arguments: alice@example.com 25
────────────────────────────────────────────────────────────
✓ Command completed successfully
────────────────────────────────────────────────────────────

console> help user:create
📖 Command Help: user:create
════════════════════════════════════════════════════════════

Command: user:create
Description: Create a new user

Usage:
  php console.php user:create <email> [age] [--admin]

Parameters:
  email (string, required) - User email address
  age (int, optional, default: 18) - User age
  --admin (bool, optional) - Create as admin user

console> history
📜 Command History
════════════════════════════════════════════════════════════

  1. user:create (used 1 times, last: 2024-01-15 10:30:45)
  2. help (used 2 times, last: 2024-01-15 10:30:30)

console> exit
Goodbye! 👋
```

## Tipps & Best Practices

### Tab-Completion nutzen

Verwenden Sie Tab für Command-Vervollständigung:

```bash
console> db:mi<Tab>        # Vervollständigt zu db:migrate
console> user:cr<Tab>      # Vervollständigt zu user:create
```

### History effizient nutzen

- **↑/↓**: Navigieren Sie durch die History
- **History-Command**: Zeigen Sie alle Commands an
- **Readline**: Nutzen Sie Readline für bessere Erfahrung

### Hilfe verwenden

- **`help`**: Zeigt alle Commands
- **`help <command>`**: Detaillierte Hilfe für einen Command
- **Kontextuelle Hilfe**: Wird nach Fehlern automatisch angezeigt

### Commands mit Argumenten

- **Quoted Arguments**: Verwenden Sie Anführungszeichen für Argumente mit Leerzeichen
- **Flags**: Verwenden Sie `--flag` für boolesche Optionen
- **Positional Arguments**: Argumente werden in der Reihenfolge der Methoden-Parameter übergeben

## Troubleshooting

### Readline nicht verfügbar

Wenn Readline nicht verfügbar ist, sehen Sie:

```
⚠ Readline not available (install php-readline for better experience)
```

**Lösung**: Installieren Sie die `php-readline` Extension.

### Commands nicht gefunden

Wenn ein Command nicht gefunden wird, werden Vorschläge angezeigt:

```bash
console> db:migrat
Command 'db:migrat' not found.

Did you mean one of these?
  • db:migrate (95% match)
```

### History funktioniert nicht

- **Ohne Readline**: History-Navigation (↑/↓) funktioniert nicht, aber History wird gespeichert
- **Mit Readline**: History-Navigation funktioniert automatisch

### Hilfe generiert Fehler

Wenn die Hilfe-Generierung fehlschlägt, wird eine Fallback-Ausgabe angezeigt:

```bash
console> help invalid:command
Command 'invalid:command' not found.

Did you mean one of these?
  • valid:command (85% match)
```

## Architektur

### Komponenten

- **`ConsoleDialog`**: Haupt-Orchestrator für den Dialog-Modus
- **`DialogCommandExecutor`**: Command-Execution für Dialog-Modus
- **`CommandHistory`**: History-Verwaltung (geteilt mit TUI)
- **`CommandSuggestionEngine`**: Vorschlags-Engine (geteilt mit TUI)
- **`CommandHelpGenerator`**: Hilfe-Generator (geteilt mit TUI)

### Integration

Der Dialog-Modus ist vollständig in `ConsoleApplication` integriert:

```php
// In ConsoleApplication::run()
if (in_array($commandName, ['--dialog', '--chat'])) {
    return $this->launchDialogMode();
}
```

### Wiederverwendung

Der Dialog-Modus nutzt die gleichen Komponenten wie die TUI:

- **CommandRegistry**: Command-Discovery und -Execution
- **CommandGroupRegistry**: Command-Kategorisierung
- **CommandHistory**: History-Verwaltung
- **CommandSuggestionEngine**: Vorschlags-Engine

## Unterschiede zur TUI

| Aspekt | TUI | Dialog-Modus |
|--------|-----|--------------|
| **Interface** | Grafisch mit Navigation | Prompt-basiert |
| **Terminal-Anforderungen** | Kompatibles Terminal erforderlich | Funktioniert überall |
| **Maus-Support** | ✅ | ❌ |
| **Tab-Completion** | Limited | ✅ (mit Readline) |
| **History-Navigation** | Limited | ✅ (mit Readline) |
| **Command-Suggestions** | ✅ | ✅ (intelligenter) |
| **Einfachheit** | Komplexer | Einfacher |
| **Best für** | Visuelle Navigation | Schnelle Eingabe |

## Zusammenfassung

Der Dialog-Modus bietet eine einfache, effiziente Alternative zur TUI für Benutzer, die:

- Eine klassische Prompt-Eingabe bevorzugen
- Schnelle Command-Ausführung ohne Navigation benötigen
- Tab-Completion und History-Navigation nutzen möchten
- In Terminals ohne TUI-Support arbeiten

**Start**: `php console.php --dialog` oder `php console.php --chat`