feat: add comprehensive framework features and deployment improvements
Major additions: - Storage abstraction layer with filesystem and in-memory implementations - Gitea API integration with MCP tools for repository management - Console dialog mode with interactive command execution - WireGuard VPN DNS fix implementation and documentation - HTTP client streaming response support - Router generic result type - Parameter type validator for framework core Framework enhancements: - Console command registry improvements - Console dialog components - Method signature analyzer updates - Route mapper refinements - MCP server and tool mapper updates - Queue job chain and dependency commands - Discovery tokenizer improvements Infrastructure: - Deployment architecture documentation - Ansible playbook updates for WireGuard client regeneration - Production environment configuration updates - Docker Compose local configuration updates - Remove obsolete docker-compose.yml (replaced by environment-specific configs) Documentation: - PERMISSIONS.md for access control guidelines - WireGuard DNS fix implementation details - Console dialog mode usage guide - Deployment architecture overview Testing: - Multi-purpose attribute tests - Gitea Actions integration tests (typed and untyped)
This commit is contained in:
472
docs/console-dialog-mode.md
Normal file
472
docs/console-dialog-mode.md
Normal file
@@ -0,0 +1,472 @@
|
||||
# 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`
|
||||
|
||||
Reference in New Issue
Block a user