michaelschiemer/docs/todo/todo.md

# Console Template System & ConsoleResponse - Implementation Plan

## 📋 Übersicht

Implementierung eines Template-Systems für Console-Ausgaben mit `ConsoleResponse` Value Objects, das nahtlos mit dem bestehenden attribute-basierten Command-System arbeitet.

---

## 🎯 Phase 1: ConsoleResponse Foundation (Woche 1)

### 1.1 Core Interfaces & Base Classes

**Ziel**: Framework-compliant Response-Architektur

**Tasks**:
- [ ] `ConsoleResponse` Interface erstellen
  - `getExitCode(): ExitCode`
  - `render(ConsoleOutputInterface $output): void`
  - `getData(): array`

- [ ] `AbstractConsoleResponse` Base Class
  - Readonly class mit gemeinsamer Logik
  - Constructor mit ExitCode und Data
  - Gemeinsame Methoden-Implementierung

**Files**:
- `src/Framework/Console/Response/ConsoleResponse.php`
- `src/Framework/Console/Response/AbstractConsoleResponse.php`

### 1.2 Response Type Implementations

**Ziel**: 6 konkrete Response-Typen für verschiedene Use Cases

**Tasks**:
- [ ] `ConsoleTextResponse` - Simple Text-Ausgabe
  - Factory Methods: `success()`, `error()`, `warning()`, `info()`
  - Support für ConsoleStyle
  - Readonly Value Object

- [ ] `ConsoleTableResponse` - Table-basierte Ausgabe
  - Wiederverwendung der bestehenden `Table` Klasse
  - Optional: Title Support
  - Headers und Rows als Constructor-Parameter

- [ ] `ConsoleTemplateResponse` - Template-basierte Ausgabe
  - Template Name + Data
  - Integration mit ConsoleTemplateEngine (Phase 2)
  - Lazy Loading von Template

- [ ] `ConsoleLayoutResponse` - Component-basierte Ausgabe
  - ConsoleLayout als Parameter
  - Wiederverwendung von Layout-System
  - Multi-Component Rendering

- [ ] `ConsoleMenuResponse` - Interactive Menu
  - Wiederverwendung von `InteractiveMenu`
  - Items, Title, Interactive-Flag
  - Selected Value in Data speichern

- [ ] `ConsoleCompositeResponse` - Mehrere Responses kombinieren
  - Array von ConsoleResponse
  - Sequential Rendering
  - Exit Code Aggregation (schlechtester gewinnt)

**Files**:
- `src/Framework/Console/Response/ConsoleTextResponse.php`
- `src/Framework/Console/Response/ConsoleTableResponse.php`
- `src/Framework/Console/Response/ConsoleTemplateResponse.php`
- `src/Framework/Console/Response/ConsoleLayoutResponse.php`
- `src/Framework/Console/Response/ConsoleMenuResponse.php`
- `src/Framework/Console/Response/ConsoleCompositeResponse.php`

### 1.3 Response Builder (Fluent API)

**Ziel**: Einfache Erstellung komplexer Responses

**Tasks**:
- [ ] `ConsoleResponseBuilder` implementieren
  - `addText(string, ?ConsoleStyle): self`
  - `addTable(array, array, ?string): self`
  - `addTemplate(string, array): self`
  - `addDivider(): self`
  - `addNewLine(int): self`
  - `withExitCode(ExitCode): self`
  - `withData(array): self`
  - `build(): ConsoleResponse`

**Features**:
- Fluent Interface
- Auto-Composite wenn mehrere Sections
- Single Response wenn nur eine Section

**Files**:
- `src/Framework/Console/Response/ConsoleResponseBuilder.php`

### 1.4 Console Application Integration

**Ziel**: Support für ExitCode UND ConsoleResponse Return-Typen

**Tasks**:
- [ ] `ConsoleApplication` erweitern für beide Return-Typen
  - Pattern Matching für `ExitCode|ConsoleResponse|int`
  - `handleResponse(ConsoleResponse): int` Methode
  - Backward Compatibility sicherstellen

- [ ] Method Signature Patterns dokumentieren
  - Pattern A: `ConsoleResponse` only (Recommended)
  - Pattern B: `ExitCode` only (Legacy)
  - Pattern C: Both (Transition)
  - Pattern D: Union Type (Flexible)

**Files**:
- `src/Framework/Console/ConsoleApplication.php` (Update)

### 1.5 Tests Phase 1

**Ziel**: ≥80% Test Coverage für Response-System

**Tasks**:
- [ ] Unit Tests für alle Response-Typen
  - Constructor-Validierung
  - Rendering-Logik
  - Factory Methods
  - getData() und getExitCode()

- [ ] Integration Tests
  - ConsoleApplication mit verschiedenen Return-Typen
  - ConsoleResponseBuilder Workflows
  - Composite Response mit mehreren Sections

- [ ] Example Commands
  - Beispiel für jede Response-Type
  - Migration-Guide-Examples

**Files**:
- `tests/Unit/Console/Response/*Test.php`
- `tests/Feature/Console/ResponseIntegrationTest.php`

**Deliverables Phase 1**:
- ✅ ConsoleResponse Interface & 6 Typen
- ✅ ConsoleResponseBuilder Fluent API
- ✅ Backward-Compatible Console Application
- ✅ Comprehensive Test Suite
- ✅ Documentation & Examples

---

## 🎨 Phase 2: Console Template System (Woche 2)

### 2.1 String-Based Template Processors

**Ziel**: Template-Verarbeitung ähnlich wie HTML-Template-System

**Tasks**:
- [ ] `ConsoleTemplateProcessor` Interface
  - `process(string $template, array $data): string`
  - String-basiert (nicht DOM!)

- [ ] `ConsolePlaceholderProcessor`
  - `{{ variable }}` - Escaped Output
  - `{{{ raw }}}` - Raw Output (für ANSI codes)
  - `{{ object.property }}` - Dot-Notation
  - `{{ function() }}` - Function Calls
  - Ähnlich wie `PlaceholderReplacer` aus View-System

- [ ] `ConsoleForProcessor`
  - `<for items="..." as="...">` Syntax
  - String-basiertes Loop-Processing
  - Nested Loop Support
  - Dot-Notation für Items-Path

- [ ] `ConsoleIfProcessor` (Optional)
  - `<if condition="...">` Syntax
  - Simple Conditional Logic
  - `<else>` Support

**Files**:
- `src/Framework/Console/Template/ConsoleTemplateProcessor.php`
- `src/Framework/Console/Template/Processors/ConsolePlaceholderProcessor.php`
- `src/Framework/Console/Template/Processors/ConsoleForProcessor.php`
- `src/Framework/Console/Template/Processors/ConsoleIfProcessor.php`

### 2.2 Template Engine & Loader

**Ziel**: Unified Template Processing Pipeline

**Tasks**:
- [ ] `ConsoleTemplateEngine` implementieren
  - Processor Pipeline (ähnlich wie View\Engine)
  - Sequential Processing
  - Processor Registry
  - Error Handling

- [ ] `ConsoleTemplateLoader`
  - Template-Files laden aus `/templates/console/`
  - File Extension: `.console.txt` oder `.console.tpl`
  - Template Caching (optional)
  - Template Not Found Exception

- [ ] Template Syntax Documentation
  - Placeholder Syntax
  - Component Tags
  - Loop Syntax
  - Examples

**Files**:
- `src/Framework/Console/Template/ConsoleTemplateEngine.php`
- `src/Framework/Console/Template/Loading/ConsoleTemplateLoader.php`
- `docs/console-template-syntax.md`

### 2.3 Console Component Tags

**Ziel**: `<console:table>`, `<console:box>` etc. in Templates

**Tasks**:
- [ ] `ConsoleComponentTagProcessor` implementieren
  - Parse `<console:*>` Tags
  - Extract Attributes
  - Extract Content
  - Render via Component Registry

- [ ] `ConsoleComponentRegistry`
  - Registry für Component-Mapping
  - `table` → TableAdapter
  - `box` → TextBoxAdapter
  - `menu` → MenuAdapter
  - `progress` → ProgressBarAdapter

- [ ] Console Component Adapters (Template-friendly)
  - `ConsoleTableComponent`
  - `ConsoleBoxComponent`
  - `ConsoleMenuComponent`
  - `ConsoleProgressComponent`

**Features**:
- Template Tag: `<console:table headers="A,B,C">...</console:table>`
- Nested Content Processing (für Loops in Attributen)
- Attribute Parsing

**Files**:
- `src/Framework/Console/Template/Processors/ConsoleComponentTagProcessor.php`
- `src/Framework/Console/Template/Components/ConsoleComponentRegistry.php`
- `src/Framework/Console/Template/Components/ConsoleTableComponent.php`
- `src/Framework/Console/Template/Components/ConsoleBoxComponent.php`

### 2.4 Template Response Integration

**Ziel**: ConsoleTemplateResponse nutzt Template-System

**Tasks**:
- [ ] `ConsoleTemplateResponse` finalisieren
  - Integration mit ConsoleTemplateEngine
  - Template Loading
  - Data Binding
  - Error Handling

- [ ] Template Examples erstellen
  - `migration-status.console.txt`
  - `user-list.console.txt`
  - `health-check.console.txt`
  - `system-status.console.txt`

**Files**:
- `templates/console/migration-status.console.txt`
- `templates/console/user-list.console.txt`
- `templates/console/health-check.console.txt`

### 2.5 Tests Phase 2

**Ziel**: Template-System vollständig getestet

**Tasks**:
- [ ] Processor Tests
  - PlaceholderProcessor mit verschiedenen Syntaxen
  - ForProcessor mit Nested Loops
  - ComponentTagProcessor mit allen Tags

- [ ] Integration Tests
  - ConsoleTemplateEngine mit kompletten Templates
  - ConsoleTemplateResponse Rendering
  - Error Cases (Template Not Found, Parse Errors)

- [ ] Template Examples Tests
  - Alle Template-Files rendern korrekt
  - Data-Binding funktioniert
  - Component Tags werden ersetzt

**Files**:
- `tests/Unit/Console/Template/*Test.php`
- `tests/Feature/Console/TemplateRenderingTest.php`

**Deliverables Phase 2**:
- ✅ String-based Template Processing System
- ✅ ConsoleTemplateEngine mit Processor Pipeline
- ✅ Console Component Tags Support
- ✅ Template Loader mit Caching
- ✅ Template Examples & Documentation
- ✅ Comprehensive Tests

---

## 🏗️ Phase 3: Component-Based Layout System (Woche 3) - OPTIONAL

### 3.1 ConsoleComponent Interface & Adapters

**Ziel**: Unified Interface für bestehende Console-Components

**Tasks**:
- [ ] `ConsoleComponent` Interface
  - `render(ConsoleOutputInterface $output): void`
  - Standard-Interface für alle Components

- [ ] Adapters für bestehende Components
  - `TableAdapter` - Wrapper für mutable `Table`
  - `TextBoxAdapter` - Wrapper für readonly `TextBox`
  - `MenuAdapter` - Wrapper für `InteractiveMenu`
  - `ProgressBarAdapter` - Wrapper für `ProgressBar`
  - `SpinnerAdapter` - Wrapper für `Spinner`

**Benefits**:
- Readonly Adapters trotz mutable Original-Components
- Unified Interface für Layout-System
- Backward-Compatible

**Files**:
- `src/Framework/Console/Components/ConsoleComponent.php`
- `src/Framework/Console/Components/Adapters/TableAdapter.php`
- `src/Framework/Console/Components/Adapters/TextBoxAdapter.php`
- `src/Framework/Console/Components/Adapters/MenuAdapter.php`
- `src/Framework/Console/Components/Adapters/ProgressBarAdapter.php`
- `src/Framework/Console/Components/Adapters/SpinnerAdapter.php`

### 3.2 Layout & Section Value Objects

**Ziel**: Komposition von Components zu Layouts

**Tasks**:
- [ ] `ConsoleLayout` Value Object
  - Array von ConsoleSections
  - Sequential Rendering
  - Readonly Class

- [ ] `ConsoleSection` Value Object
  - ConsoleComponent + Style
  - Margins, Padding, Borders
  - Readonly Class

- [ ] `ConsoleSectionStyle` Value Object
  - Margins (top, bottom)
  - Padding
  - Borders (top, bottom, divider)
  - Background Colors (optional)

**Files**:
- `src/Framework/Console/Layout/ConsoleLayout.php`
- `src/Framework/Console/Layout/ConsoleSection.php`
- `src/Framework/Console/Layout/ConsoleSectionStyle.php`

### 3.3 Layout Builder (Fluent API)

**Ziel**: Einfache Layout-Erstellung

**Tasks**:
- [ ] `ConsoleLayoutBuilder`
  - `addSection(ConsoleComponent): self`
  - `addTable(array, array): self`
  - `addBox(string, ?string): self`
  - `addDivider(): self`
  - `addSpacing(int): self`
  - `build(): ConsoleLayout`

**Files**:
- `src/Framework/Console/Layout/ConsoleLayoutBuilder.php`

### 3.4 Tests Phase 3

**Tasks**:
- [ ] Component Adapter Tests
- [ ] Layout Composition Tests
- [ ] Builder Tests
- [ ] Integration Tests

**Deliverables Phase 3**:
- ✅ ConsoleComponent Interface & 5 Adapters
- ✅ ConsoleLayout System
- ✅ ConsoleLayoutBuilder Fluent API
- ✅ Tests & Documentation

---

## 📚 Documentation & Examples

### Documentation Tasks
- [ ] Console Response Guide
  - Alle Response-Typen mit Beispielen
  - Migration Guide (ExitCode → ConsoleResponse)
  - Best Practices

- [ ] Console Template Guide
  - Template Syntax Reference
  - Component Tags Reference
  - Template Examples

- [ ] Console Layout Guide
  - Component-Based Layouts
  - Builder Pattern Examples
  - Advanced Compositions

### Example Commands
- [ ] Simple Response Examples
  - TextResponse in verschiedenen Commands
  - TableResponse für Listen
  - TemplateResponse für komplexe Ausgaben

- [ ] Template Examples
  - Migration Status Template
  - User List Template
  - Health Check Template
  - System Status Template

- [ ] Layout Examples
  - Dashboard Layout
  - Report Layout
  - Multi-Section Layout

**Files**:
- `docs/console/console-response-guide.md`
- `docs/console/console-template-guide.md`
- `docs/console/console-layout-guide.md`
- `src/Framework/Console/Examples/*` (Update)

---

## 🧪 Testing Strategy

### Unit Tests
- [ ] Alle Response-Typen
- [ ] Alle Processors
- [ ] Alle Adapters
- [ ] Builder Classes

### Integration Tests
- [ ] ConsoleApplication mit verschiedenen Return-Typen
- [ ] Template Rendering End-to-End
- [ ] Layout Composition
- [ ] Backward Compatibility

### Example Tests
- [ ] Alle Example-Commands ausführbar
- [ ] Template-Examples rendern korrekt
- [ ] Layout-Examples funktionieren

**Coverage Goal**: ≥80%

---

## 🚀 Migration Strategy

### Backward Compatibility
- ✅ Alle bestehenden Commands funktionieren unverändert
- ✅ ExitCode Return-Type weiterhin supported
- ✅ Direktes Output-Schreiben weiterhin möglich

### Gradual Adoption
1. **Phase 1**: ConsoleResponse verfügbar, optional nutzbar
2. **Phase 2**: Template-System verfügbar, Commands können migrieren
3. **Phase 3**: Layout-System verfügbar für komplexe Use Cases

### Migration Patterns
```php
// Old: ExitCode + Direct Output
#[ConsoleCommand(name: 'old')]
public function old(ConsoleInput $input, ConsoleOutput $output): ExitCode
{
    $output->writeLine("Done");
    return ExitCode::SUCCESS;
}

// New: ConsoleResponse
#[ConsoleCommand(name: 'new')]
public function new(ConsoleInput $input): ConsoleResponse
{
    return ConsoleTextResponse::success("Done");
}

// Transition: Both
#[ConsoleCommand(name: 'transition')]
public function transition(ConsoleInput $input, ConsoleOutput $output): ConsoleResponse
{
    $output->writeLine("Processing..."); // Progress output
    return ConsoleTextResponse::success("Done"); // Final result
}
```

---

## ✅ Success Criteria

### Phase 1 Complete When:
- [ ] All 6 Response-Typen implementiert und getestet
- [ ] ConsoleResponseBuilder funktional
- [ ] ConsoleApplication unterstützt beide Return-Typen
- [ ] ≥80% Test Coverage
- [ ] Documentation vollständig

### Phase 2 Complete When:
- [ ] Template-System funktional (Placeholder, For, Component Tags)
- [ ] ConsoleTemplateResponse integriert
- [ ] Template-Examples funktionieren
- [ ] ≥80% Test Coverage
- [ ] Documentation vollständig

### Phase 3 Complete When:
- [ ] Component Adapters funktional
- [ ] Layout-System implementiert
- [ ] Builder Pattern verfügbar
- [ ] ≥80% Test Coverage
- [ ] Documentation vollständig

---

## 🎯 Quick Start (Phase 1 only - Minimum Viable)

**Minimal Implementation für sofortige Nutzbarkeit**:

1. ConsoleResponse Interface
2. ConsoleTextResponse (mit Factory Methods)
3. ConsoleTableResponse
4. ConsoleCompositeResponse
5. ConsoleResponseBuilder
6. ConsoleApplication Update

**Result**: Commands können sofort ConsoleResponse nutzen ohne Template-System!

---

## 📊 Timeline Estimate

- **Phase 1**: 1 Woche (Foundation - ESSENTIAL)
- **Phase 2**: 1 Woche (Template System - RECOMMENDED)
- **Phase 3**: 1 Woche (Layout System - OPTIONAL)

**Minimum Viable**: Phase 1 only (1 Woche)
**Recommended**: Phase 1 + 2 (2 Wochen)
**Complete**: Phase 1 + 2 + 3 (3 Wochen)

---

## 🔗 Related Systems

### Integration Points
- **Console Module**: Bestehende Components (Table, TextBox, Menu, etc.)
- **View System**: Template-Processor-Pattern wiederverwenden
- **HTTP System**: Response-Pattern analog zu JsonResponse, ViewResult
- **Testing**: Pest Framework für alle Tests

### Dependencies
- Bestehende Console Components (keine Änderungen)
- ConsoleOutput Interface (keine Änderungen)
- ExitCode Enum (keine Änderungen)
- ConsoleStyle, ConsoleColor (keine Änderungen)

---

## 📝 Notes & Decisions

### Design Decisions
1. **String-based Templates** (nicht DOM) - Einfacher für Console-Output
2. **Method-based Commands** - Kompatibel mit `#[ConsoleCommand]` Attribute
3. **Backward Compatible** - Beide Return-Typen (ExitCode | ConsoleResponse)
4. **Adapter Pattern** - Wrapper für bestehende mutable Components
5. **Composition** - Layout aus Components komponieren, nicht erben

### Open Questions
- [ ] Template-Caching Strategy?
- [ ] Performance-Optimierung für große Outputs?
- [ ] ANSI-Code-Handling in Templates?
- [ ] Interactive Components in Templates?

### Future Enhancements
- Progress Bars in Templates
- Animated Spinners in Templates
- Color Themes für Templates
- Template Inheritance/Extends
- Custom Template Functions