Merge pull request #8 from theokeist/codex/update-documentation-with-types-and-arguments-uey0pt

Add colored CLI help output

Author: theokeist

docs/CLI.md

@@ -203,6 +203,24 @@ php pipeflow make:channel <Name>
 
 ---
 
+### `make:service`
+
+**Purpose:** Generate a service class.
+
+**Usage:**
+```bash
+php pipeflow make:service <Name>
+```
+
+**Output:**
+- Writes `app/Services/<Name>Service.php`.
+
+**Related classes:**
+- `PipeFlow\Console\Commands\MakeServiceCommand`
+- [`PipeFlow\Scaffold\Generator`](reference/src__Scaffold__Generator.php.md)
+
+---
+
 ### `make:test`
 
 **Purpose:** Generate a PHPUnit test class.

docs/GETTING_STARTED.md

@@ -498,7 +498,7 @@ This is useful for dashboard widgets or front-end frameworks.
 
 For more complex apps, move logic into a service class:
 
-Create `app/Services/PostPublisher.php`:
+Create `app/Services/PostPublisherService.php`:
 
 ```php
 <?php
@@ -509,7 +509,7 @@ namespace App\Services;
 
 use App\Models\Post;
 
-final class PostPublisher
+final class PostPublisherService
 {
     /** @param array<string, mixed> $data */
     public function publish(array $data): Post
@@ -520,10 +520,18 @@ final class PostPublisher
 }
 ```
 
+You can generate a service class with:
+
+```bash
+php pipeflow make:service PostPublisher
+```
+
+This creates `app/Services/PostPublisherService.php`.
+
 Then inject it in your controller:
 
 ```php
-public function store(Request $request, PostPublisher $publisher, Conn $conn): Response
+public function store(Request $request, PostPublisherService $publisher, Conn $conn): Response
 {
     $data = $request->only(['title', 'body']);
     $errors = $this->validate($data);
@@ -541,6 +549,32 @@ public function store(Request $request, PostPublisher $publisher, Conn $conn): R
 }
 ```
 
+### When to use services (external APIs, AI, cloud)
+
+Services are the right place to integrate with third‑party APIs (payment, email, cloud storage, AI). They should:
+
+- Accept plain data in method arguments (avoid storing request-specific state).
+- Wrap external SDK clients (Stripe, OpenAI, S3) behind a tiny interface.
+- Return plain PHP arrays or value objects so controllers remain thin.
+
+Example skeleton for an external API service:
+
+```php
+namespace App\Services;
+
+final class AiSummaryService
+{
+    public function summarize(string $text): string
+    {
+        // Call a 3rd-party SDK or HTTP client here.
+        // Return a string so controllers/views stay simple.
+        return $text;
+    }
+}
+```
+
+If you need framework config, read it inside the method (or inject via constructor) and keep the service stateless.
+
 ## 6.10.1) Public vs private helpers in controllers
 
 Keep controller actions `public` and push shared logic into `private` helpers:
@@ -782,6 +816,18 @@ php pipeflow route:list
 
 You’ll see all route patterns, names, and target controllers in a table.
 
+Example output (indented columns):
+
+```
+GET     /posts             posts.index
+GET     /posts/create      posts.create
+POST    /posts             posts.store
+GET     /posts/{id}        posts.show
+GET     /posts/{id}/edit   posts.edit
+POST    /posts/{id}        posts.update
+POST    /posts/{id}/delete posts.destroy
+```
+
 ## 8) Add flash feedback (optional)
 
 PipeFlow ships with a flash system so you can show one-time notices after redirects.

docs/WORKERS.md

@@ -30,6 +30,16 @@ $kernel = new PipeFlow\Foundation\Kernel($app);
 - Use the request-scoped container (`Application::newRequestContainer()`) for
   anything that is request-specific.
 - Avoid static caches that capture user-specific data.
+- **Clear view/shared state** if you push globals or shared view data.
+- **Reset per-request timers/metrics** in `beforeRequest` hooks.
+- **Avoid global mutable config** unless it is read-only.
+
+## Typical leak sources (checklist)
+
+- Static properties on services holding the last request/user.
+- Global arrays like `$_SESSION` or `$GLOBALS['__pipeflow_view_data']` reused across requests.
+- Cached QueryBuilder instances shared across requests.
+- Random seeds or locale/timezone mutations not reset.
 
 ## Per-request cleanup hooks
 
@@ -49,3 +59,38 @@ $kernel->afterRequest(function ($request, $response, $container) {
 
 For long-lived workers, call `Connection::reconnect()` if a connection becomes
 stale or times out.
+
+## Worker-safe patterns
+
+- Instantiate services once, but keep request data in method scope.
+- Prefer passing data into methods rather than storing it on the instance.
+- Use the `Conn` assigns for per-request values you need in views.
+- For SDK clients (cloud, AI, payment), reuse the client but **do not** cache per-request tokens on the service.
+
+## Services + workers (external APIs)
+
+When running RoadRunner/Swoole, services that call external APIs should be:
+
+- **Stateless:** no request-specific fields stored on the service.
+- **Client-reusable:** keep a shared SDK/HTTP client and pass per-request auth or payloads as arguments.
+- **Timeout-aware:** external calls can hang; configure timeouts on the HTTP client.
+- **Retry-safe:** if the SDK retries, make sure the operation is idempotent or guarded.
+
+Example pattern:
+
+```php
+final class CloudStorageService
+{
+    public function __construct(private readonly HttpClient $client) {}
+
+    public function upload(string $path, string $contents, string $token): void
+    {
+        $this->client->post('/upload', [
+            'headers' => ['Authorization' => "Bearer {$token}"],
+            'body' => $contents,
+        ]);
+    }
+}
+```
+
+This keeps the client reusable while all request-specific values are passed in.

pipeflow

@@ -13,6 +13,7 @@ use PipeFlow\Console\Commands\MakeChannelCommand;
 use PipeFlow\Console\Commands\MakeTestCommand;
 use PipeFlow\Console\Commands\MakeFactoryCommand;
 use PipeFlow\Console\Commands\MakeFixtureCommand;
+use PipeFlow\Console\Commands\MakeServiceCommand;
 use PipeFlow\Console\Commands\MigrateCommand;
 use PipeFlow\Console\Commands\MigrateRollbackCommand;
 use PipeFlow\Console\Commands\RouteListCommand;
@@ -30,6 +31,7 @@ $cli->register(new MakeChannelCommand());
 $cli->register(new MakeTestCommand());
 $cli->register(new MakeFactoryCommand());
 $cli->register(new MakeFixtureCommand());
+$cli->register(new MakeServiceCommand());
 $cli->register(new MigrateCommand());
 $cli->register(new MigrateRollbackCommand());
 $cli->register(new RouteListCommand());

src/Console/Commands/MakeServiceCommand.php

@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PipeFlow\Console\Commands;
+
+use PipeFlow\Console\CommandInterface;
+use PipeFlow\Foundation\Application;
+use PipeFlow\Scaffold\Generator;
+
+final class MakeServiceCommand implements CommandInterface
+{
+    public function name(): string { return 'make:service'; }
+    public function description(): string { return 'Generate a service class.'; }
+
+    public function handle(array $args, Application $app): int
+    {
+        $name = $args[0] ?? null;
+        if (!$name) {
+            fwrite(STDERR, "Usage: make:service <Name>\n");
+            return 2;
+        }
+
+        $gen = new Generator($app);
+        $class = preg_replace('/Service$/', '', $name) . 'Service';
+        $namespace = 'App\\Services';
+        $path = 'app/Services/' . $class . '.php';
+
+        $stub = $gen->stub('service.php.stub');
+        $contents = str_replace(
+            ['{{namespace}}', '{{class}}'],
+            [$namespace, $class],
+            $stub
+        );
+
+        $gen->write($path, $contents);
+        echo "Created: {$path}\n";
+        return 0;
+    }
+}

src/Console/ConsoleApplication.php

@@ -30,7 +30,7 @@ public function run(array $argv): int
         }
 
         if (!isset($this->commands[$name])) {
-            fwrite(STDERR, "Unknown command: {$name}\n\n");
+            fwrite(STDERR, $this->colorize("Unknown command: {$name}\n\n", 'red'));
             $this->printHelp();
             return 2;
         }
@@ -41,9 +41,9 @@ public function run(array $argv): int
 
     private function printHelp(): void
     {
-        echo "PipeFlow CLI\n";
-        echo "Usage: php pipeflow <command> [options]\n\n";
-        echo "Commands:\n";
+        echo $this->colorize("PipeFlow CLI\n", 'bold_cyan');
+        echo $this->colorize("Usage: php pipeflow <command> [options]\n\n", 'cyan');
+        echo $this->colorize("Commands:\n", 'bold');
 
         $max = 0;
         foreach ($this->commands as $c) {
@@ -52,9 +52,41 @@ private function printHelp(): void
 
         foreach ($this->commands as $c) {
             $pad = str_repeat(' ', $max - strlen($c->name()) + 2);
-            echo "  {$c->name()}{$pad}{$c->description()}\n";
+            $name = $this->colorize($c->name(), 'green');
+            echo "  {$name}{$pad}{$c->description()}\n";
         }
 
         echo "\n";
     }
+
+    private function colorize(string $text, string $style): string
+    {
+        if (!$this->supportsColor()) {
+            return $text;
+        }
+
+        $codes = [
+            'bold' => '1',
+            'red' => '31',
+            'green' => '32',
+            'cyan' => '36',
+            'bold_cyan' => '1;36',
+        ];
+
+        $code = $codes[$style] ?? null;
+        if ($code === null) {
+            return $text;
+        }
+
+        return "\033[{$code}m{$text}\033[0m";
+    }
+
+    private function supportsColor(): bool
+    {
+        if (!function_exists('posix_isatty')) {
+            return false;
+        }
+
+        return posix_isatty(STDOUT) || posix_isatty(STDERR);
+    }
 }

stubs/service.php.stub

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace {{namespace}};
+
+final class {{class}}
+{
+    public function __construct()
+    {
+    }
+}