prompts wip

Author: AzGasim

packages/prompts/README.md

@@ -1,30 +1,36 @@
 # Moox Prompts
 
-CLI- und Web-kompatible Prompts für Laravel Artisan Commands – mit einem Flow, der im Browser Schritt für Schritt weiterläuft.
+CLI- and Web-compatible prompts for Laravel Artisan commands – with a flow that can continue step-by-step in the browser.
 
-## Wie muss ein Flow-Command aussehen?
+## What does a Flow Command look like?
 
-Damit ein Command sowohl in der CLI als auch im Web korrekt als Flow funktioniert, müssen nur diese Regeln erfüllt sein:
+To make a command work as a flow in both CLI and Web, you only need to follow these rules:
+
+- **Extend `FlowCommand`**  
 
-- **Von `FlowCommand` erben**  
   ```php
   use Moox\Prompts\Support\FlowCommand;
   use function Moox\Prompts\text;
   use function Moox\Prompts\select;
+  ```
 
+  ```php
   class ProjectSetupCommand extends FlowCommand
   {
       protected $signature = 'prompts:project-setup';
-      protected $description = 'Projekt Setup Wizard (CLI & Web)';
+      protected $description = 'Project setup wizard (CLI & Web)';
   ```
 
-- **State als Properties ablegen** (werden im Web automatisch zwischen Steps gespeichert)  
+- **Store state as public properties**  
+  (they are automatically persisted between steps in the web flow)
+
   ```php
       public ?string $environment = null;
       public ?string $projectName = null;
   ```
 
-- **Steps über `promptFlowSteps()` definieren** – Reihenfolge = Flow-Reihenfolge  
+- **Define steps via `promptFlowSteps()`** – the array order **is the flow order**
+
   ```php
       public function promptFlowSteps(): array
       {
@@ -37,17 +43,18 @@ Damit ein Command sowohl in der CLI als auch im Web korrekt als Flow funktionier
       }
   ```
 
-- **Jeder Step ist eine `public function stepXyz(): void`** – idealerweise **ein Prompt pro Step**  
+- **Each step is a `public function stepXyz(): void`** – ideally **one prompt per step**
+
   ```php
       public function stepIntro(): void
       {
-          $this->info('=== Projekt Setup ===');
+          $this->info('=== Project Setup ===');
       }
 
       public function stepEnvironment(): void
       {
           $this->environment = select(
-              label: 'Welche Umgebung konfigurierst du?',
+              label: 'Which environment do you want to configure?',
               options: [
                   'local' => 'Local',
                   'staging' => 'Staging',
@@ -60,42 +67,44 @@ Damit ein Command sowohl in der CLI als auch im Web korrekt als Flow funktionier
       public function stepProjectName(): void
       {
           $this->projectName = text(
-              label: 'Wie heißt dein Projekt?',
-              placeholder: 'z.B. MyCoolApp',
+              label: 'What is your project name?',
+              placeholder: 'e.g. MyCoolApp',
               validate: 'required|min:3',
               required: true,
           );
       }
 
       public function stepSummary(): void
       {
-          $this->info('--- Zusammenfassung ---');
-          $this->line('Projekt: '.$this->projectName);
+          $this->info('--- Summary ---');
+          $this->line('Project: '.$this->projectName);
           $this->line('Environment: '.$this->environment);
       }
   }
   ```
 
-- **Optionale Steps** kannst du einfach mit einem Guard am Anfang überspringen:
+- **Optional steps** can simply be skipped with a guard at the beginning:
+
   ```php
   public array $features = [];
 
   public function stepLoggingLevel(): void
   {
       if (! in_array('logging', $this->features, true)) {
-          return; // Step wird übersprungen
+          return; // skip step
       }
 
       // Prompt …
   }
   ```
 
-- **Andere Artisan-Commands aufrufen** – verwende im Flow immer `$this->call()` statt `Artisan::call()`, damit der Output auch im Web angezeigt wird:
+- **Calling other Artisan commands** – in a flow, always use `$this->call()` instead of `Artisan::call()`, so the output is also visible in the web UI:
+
   ```php
   public function stepPublishConfig(): void
   {
       $shouldPublish = confirm(
-          label: 'Möchtest du die Config jetzt veröffentlichen?',
+          label: 'Publish the config now?',
           default: true,
       );
 
@@ -109,131 +118,201 @@ Damit ein Command sowohl in der CLI als auch im Web korrekt als Flow funktionier
   }
   ```
 
-Mehr ist im Command nicht nötig – keine speziellen Flow-Methoden, keine eigene Persistenz.  
-Der Rest (CLI/Web-Unterschied, State, Web-Oberfläche) wird komplett vom Package übernommen.
+That’s all you need in the command – no special flow methods, no custom persistence.  
+Everything else (CLI/Web differences, state, web UI) is handled by the package.
 
-## Ausführung im Browser (Filament)
+## Running flows in the browser (Filament)
 
-Nachdem du einen Flow-Command erstellt hast, kannst du ihn sowohl in der CLI als auch im Browser ausführen:
+Once you’ve created a flow command, you can run it in both CLI and browser.
 
-### CLI-Ausführung
+### CLI
 
 ```bash
 php artisan prompts:project-setup
 ```
 
-Der Command läuft wie ein normaler Laravel Artisan Command – alle Prompts werden direkt im Terminal angezeigt.
+The command behaves like a normal Laravel Artisan command – all prompts are shown in the terminal.
 
-### Web-Ausführung
+### Web
 
-1. Öffne die Filament-Seite "Run Command" (wird automatisch im Navigation-Menü angezeigt)
-2. Wähle einen Flow-Command aus der Liste
-3. Klicke auf "Command starten"
-4. Der Flow läuft Schritt für Schritt im Browser ab:
-   - Jeder Step zeigt einen Prompt (Text-Input, Select, Multiselect, Confirm, etc.)
-   - Nach jedem Step siehst du den Output des Steps
-   - Du kannst jederzeit mit "Zurück zur Command-Auswahl" abbrechen
-   - Nach erfolgreichem Abschluss wird der Button zu "Start new command" geändert
+1. Open the Filament page **“Run Command”** (automatically added to navigation)
+2. Select your flow command from the list
+3. Click **“Start command”**
+4. The flow runs step by step in the browser:
+   - Every step shows a prompt (text, select, multiselect, confirm, etc.)
+   - After each step you see the step’s output
+   - You can cancel any time with “Back to command selection”
+   - After a successful run the button switches to “Start new command”
 
-**Wichtig:** Alle Commands, die im Web ausgeführt werden, werden automatisch in der Datenbank geloggt (siehe [Command Execution Logging](#command-execution-logging)).
+**Note:** All commands executed via the web UI are automatically logged in the database (see [Command Execution Logging](#command-execution-logging)).
 
-## Wie und warum wird Reflection verwendet?
+## How and why reflection is used
 
-Wenn du nur Commands schreibst, musst du dich nicht um Reflection kümmern.  
-Damit du aber verstehst, was im Hintergrund passiert, hier eine kurze Erklärung.
+If you’re just writing commands, you don’t need to care about reflection.  
+To understand what happens under the hood, here’s a short overview.
 
-- **Problem 1: Argumente & Optionen im Web setzen**  
-  Laravel speichert Argumente/Optionen intern in einem geschützten Property `$input` deines Commands.  
-  In der CLI kümmert sich der Artisan-Kernel darum, dieses Property zu setzen.  
-  Im Web-Flow erzeugen wir aber selbst neue Command-Instanzen – und müssen `$input` daher manuell setzen.  
-  Genau das macht `PromptFlowRunner::setCommandInput()` mit Reflection:
-  - es findet das `input`-Property auf deinem Command-Objekt,
-  - macht es kurz zugänglich,
-  - und schreibt das aktuelle Input-Objekt hinein.  
-  **Ergebnis:** In Flow-Commands kannst du überall ganz normal `argument()` und `option()` verwenden – egal ob der Command per CLI oder im Browser läuft.
+- **Problem 1: Setting arguments & options in the web flow**  
+  Laravel stores arguments/options internally on a protected `$input` property of your command.  
+  In CLI mode the Artisan kernel takes care of this.  
+  In the web flow, we create fresh command instances – and need to set `$input` ourselves.  
+  That’s what `PromptFlowRunner::setCommandInput()` does via reflection:
+  - finds the `input` property on your command object,
+  - temporarily makes it accessible,
+  - assigns the current `ArrayInput` instance.  
+  **Result:** In flow commands you can keep using `argument()` and `option()` normally – both in CLI and in the browser.
 
-- **Problem 2: Command-State zwischen Web-Requests merken**  
-  Im Web besteht dein Flow aus mehreren HTTP-Requests. Ohne zusätzliche Logik wären Properties wie `$environment`, `$features`, `$projectName` im nächsten Step einfach weg.  
-  `PromptFlowRunner` löst das mit zwei internen Methoden:
+- **Problem 2: Remembering command state between web requests**  
+  In the web flow, your command runs across multiple HTTP requests. Without extra logic, properties like `$environment`, `$features`, `$projectName` would be lost between steps.  
+  `PromptFlowRunner` handles this with two internal methods:
   - `captureCommandContext($command, $state)`  
-    - liest per Reflection alle nicht-statischen Properties deiner konkreten Command-Klasse aus  
-    - speichert einfache Werte (Scalars, Arrays, `null`) im `PromptFlowState::$context`
+    - uses reflection to read all non-static properties of your concrete command class  
+    - stores simple values (scalars, arrays, `null`) into `PromptFlowState::$context`
   - `restoreCommandContext($command, $state)`  
-    - setzt beim nächsten Request alle gespeicherten Werte wieder zurück auf das neue Command-Objekt  
-  **Ergebnis:** Für deinen Code fühlt es sich so an, als würde derselbe Command einfach weiterlaufen – du musst keine eigene Persistenz (Cache, Datenbank, Session, …) schreiben.
+    - restores all stored values back onto the new command instance on the next request  
+  **Result:** For your code it feels like the same command instance keeps running – you don’t need your own persistence layer (cache, DB, session, …).
 
-- **Problem 3: Package-Tools im Web initialisieren**  
-  Viele Packages, die `Spatie\LaravelPackageTools` verwenden, registrieren ihre publishable Ressourcen (Config, Views, Migrations, Assets, …) nur im CLI-Kontext.  
-  `WebCommandRunner` verwendet Reflection, um intern an das `package`-Objekt eines solchen Service Providers zu kommen und die `publishes(...)`-Registrierung auch im Web nachzuholen.  
-  **Ergebnis:** Befehle wie `vendor:publish` funktionieren im Browser genauso zuverlässig wie in der CLI, obwohl Laravel dort eigentlich nicht im Console-Modus läuft.
+- **Problem 3: Initializing package tools in the web context**  
+  Many packages using `Spatie\LaravelPackageTools` only register publishable resources (config, views, migrations, assets, …) in CLI context.  
+  `WebCommandRunner` uses reflection to access the internal `package` object and replay `publishes(...)` registrations for the web context.  
+  **Result:** Commands like `vendor:publish` work just as well in the browser as in CLI, even though Laravel is not running in console mode there.
 
-**Wichtig:**  
-Reflection wird nur in diesen internen Klassen des Packages verwendet, nicht in deinen Commands.  
-Deine Commands bleiben normale Laravel-Commands – du musst nur:
+**Important:**  
+Reflection is only used inside the package internals, not in your flow commands.  
+Your commands remain normal Laravel commands – you only need to:
 
-- von `FlowCommand` erben,
-- Properties für den State definieren,
-- Steps in `promptFlowSteps()` auflisten,
-- `step*`-Methoden schreiben (am besten ein Prompt pro Step).
+- extend `FlowCommand`,
+- define properties for your state,
+- list steps in `promptFlowSteps()`,
+- implement `step*` methods (ideally one prompt per step).
 
-Den Rest (Reflection, State, Web-Flow) übernimmt das Package für dich.
+The package takes care of the rest (reflection, state, web flow).
 
-### Gibt es Alternativen ohne Reflection?
+### Are there alternatives without reflection?
 
-Ja – theoretisch könnten wir auf Reflection verzichten, aber das hätte Nachteile für dich als Nutzer:
+Yes – technically we could avoid reflection, but it would degrade the DX:
 
-- Für **Argumente & Optionen** könnten wir eine eigene API einführen (statt `argument()/option()`), oder erzwingen, dass du alles manuell über Properties/Arrays verwaltest. Das wäre weniger “Laravel-typisch” und schwerer zu verstehen.
-- Für den **Command-State zwischen Steps** könnten wir dich z.B. eine Methode wie `flowContextKeys()` implementieren lassen, in der du alle zu speichernden Properties auflistest, oder dich zwingen, selbst Cache/DB/Session zu benutzen. Das wäre mehr Boilerplate und eine zusätzliche Fehlerquelle.
-- Für **Spatie Package Tools im Web** bräuchten wir entweder Änderungen im Spatie-Package selbst oder eine eigene, manuelle Konfiguration aller publishbaren Pfade – beides würde die Einrichtung deutlich komplizierter machen.
+- For **arguments & options** we’d need a custom API instead of `argument()/option()`, or force you to manage everything via properties/arrays. That’s less “Laravel-ish” and harder to learn.
+- For **state between steps** we could ask you to manually list all properties to persist (e.g. `flowContextKeys()`), or manage cache/DB/session yourself. That’s more boilerplate and error-prone.
+- For **Spatie Package Tools in the web** we’d either need changes in the Spatie package or manual configuration of all publishable paths – both would make setup more complex.
 
-Aus diesen Gründen kapseln wir die Reflection-Nutzung bewusst im Package und halten die API für deine Commands so einfach wie möglich.
+That’s why we intentionally keep reflection encapsulated in the package and keep your command API as simple as possible.
 
 ## Command Execution Logging
 
-Alle Commands, die über das Web-Interface ausgeführt werden, werden automatisch in der Datenbank geloggt. Du kannst die Ausführungen in der Filament-Resource "Command Executions" einsehen.
+All commands executed via the web interface are automatically logged in the database.  
+You can inspect them via the Filament resource **“Command Executions”**.
 
 ### Status
 
-Jede Command-Ausführung hat einen der folgenden Status:
+Each execution has one of the following statuses:
+
+- **`running`**: The command is currently running
+- **`completed`**: The command finished successfully
+- **`failed`**: The command failed with an error
+- **`cancelled`**: The command was cancelled by the user or aborted mid-flow
+
+### Stored information
+
+For each execution we store:
+
+- **Basic information**: command name, description, status, timestamps
+- **Steps**: ordered list of all defined steps
+- **Step outputs**: output of each step (JSON)
+- **Context**: all command properties (e.g. `$environment`, `$projectName`, `$features`, …)
+- **Failure details**: for `failed` status – the error message and the step where it occurred (`failed_at_step`)
+- **Cancellation details**: for `cancelled` status – the step where cancellation happened (`cancelled_at_step`)
+- **User**: polymorphic relation to the user who started the command (`created_by`)
+
+### Important: `step_outputs` vs `context`
 
-- **`running`**: Der Command läuft gerade
-- **`completed`**: Der Command wurde erfolgreich abgeschlossen
-- **`failed`**: Der Command ist mit einem Fehler fehlgeschlagen
-- **`cancelled`**: Der Command wurde vom Benutzer abgebrochen
+It’s important to understand the difference between these two fields:
 
-### Gespeicherte Informationen
+- **`step_outputs`**  
+  - Contains the **console output** of each step.  
+  - This is everything you print via `$this->info()`, `$this->line()`, `$this->warn()`, etc.  
+  - Example:
+
+    ```php
+    public function stepEnvironment(): void
+    {
+        $this->environment = select(...);
+        $this->info("✅ Environment: {$this->environment}");
+    }
+    ```
+
+    will result in e.g.:
+
+    ```json
+    "stepEnvironment": "✅ Environment: production\n"
+    ```
+
+- **`context`**  
+  - Contains the **raw state** of your command – all public, non-static properties from your concrete command class.  
+  - This includes values returned from `text()`, `select()`, `multiselect()`, `confirm()`, etc.
+  - Example:
+
+    ```php
+    public ?bool $publishConfig = null;
+
+    public function stepPublishConfigConfirm(): void
+    {
+        $this->publishConfig = confirm(
+            label: 'Publish the config now?',
+            default: true,
+        );
+    }
+    ```
+
+    will store in `context` something like:
+
+    ```json
+    {
+      "publishConfig": true
+    }
+    ```
+
+    but `step_outputs["stepPublishConfigConfirm"]` will be an **empty string**, because `confirm()` itself doesn’t print anything.
+
+If you want to see the user’s choice in the **step output** as well, you can explicitly print it:
+
+```php
+public function stepPublishConfigConfirm(): void
+{
+    $this->publishConfig = confirm(
+        label: 'Publish the config now?',
+        default: true,
+    );
+
+    $this->info('✅ Publish config: ' . ($this->publishConfig ? 'yes' : 'no'));
+}
+```
 
-Für jede Ausführung werden folgende Daten gespeichert:
+This way you have:
 
-- **Basis-Informationen**: Command-Name, Beschreibung, Status, Zeitstempel
-- **Steps**: Liste aller Steps, die ausgeführt wurden
-- **Step-Outputs**: Output jedes einzelnen Steps (als JSON)
-- **Context**: Alle Command-Properties (z.B. `$environment`, `$projectName`, etc.)
-- **Fehler-Informationen**: Bei `failed` Status: Fehlermeldung und der Step, bei dem der Fehler aufgetreten ist (`failed_at_step`)
-- **Abbruch-Informationen**: Bei `cancelled` Status: Der Step, bei dem abgebrochen wurde (`cancelled_at_step`)
-- **Benutzer**: Polymorphe Beziehung zu dem Benutzer, der den Command gestartet hat (`created_by`)
+- the decision in `context.publishConfig`, and
+- a readable line in `step_outputs.stepPublishConfigConfirm` for the history/inspector UI.
 
-### Migration ausführen
+### Running the migration
 
-Um das Logging zu aktivieren, führe die Migration aus:
+To enable logging, run:
 
 ```bash
 php artisan migrate
 ```
 
-Die Migration erstellt die Tabelle `command_executions` mit allen notwendigen Feldern.
+This creates the `command_executions` table with all necessary fields.
 
-### Filament Resource
+### Filament resource
 
-Die Filament-Resource "Command Executions" ist automatisch im Filament-Navigation-Menü verfügbar (falls aktiviert). Dort kannst du:
+The Filament resource **“Command Executions”** is automatically available in the Filament navigation (if enabled). There you can:
 
-- Alle vergangenen Command-Ausführungen einsehen
-- Nach Status filtern
-- Details zu jeder Ausführung ansehen (Steps, Outputs, Context, etc.)
-- Fehlgeschlagene oder abgebrochene Commands analysieren
+- inspect all past command executions,
+- filter by status,
+- see details per execution (steps, outputs, context, errors),
+- analyze failed or cancelled commands.
 
-Die Resource zeigt auch an, bei welchem Step ein Command fehlgeschlagen (`failed_at_step`) oder abgebrochen (`cancelled_at_step`) wurde.
+The resource also shows which step a command **failed** on (`failed_at_step`) or where it was **cancelled** (`cancelled_at_step`).
 
 ## License
 
-Siehe [LICENSE.md](LICENSE.md)
+See [LICENSE.md](LICENSE.md)