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

// 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