start-vibing-stacks 2.16.0 → 2.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-vibing-stacks",
-  "version": "2.16.0",
+  "version": "2.17.0",
   "description": "AI-powered multi-stack dev workflow for Claude Code. Supports PHP, Node.js, Python and more.",
   "type": "module",
   "bin": {

package/stacks/php/skills/composer-workflow/SKILL.md

@@ -1,65 +1,138 @@
 ---
 name: composer-workflow
-version: 1.0.0
+version: 2.0.0
+description: "Composer 2.8+ (Oct 2024) workflow for Laravel / PHP 8.3-8.5 projects. Covers composer.json structure, PSR-4 layout, scripts orchestration, audit command (--abandoned, --ignore-severity, exit codes 1=vulns/2=abandoned/3=both), --patch-only updates, --ignore-scripts for supply-chain hardening, allow-missing-requirements, lockfile hygiene, optimized autoloader for prod, sort-packages, plugin allowlist. Invoke when initializing a project, adding dependencies, debugging install/update conflicts, or wiring CI quality scripts."
 ---
 
-# Composer Workflow
+# Composer Workflow (2.8+)
+
+**Invoke when initializing a Composer project, adding deps, debugging install/update, or wiring CI scripts.**
 
 ## Requirements
 
-- **Composer >= 2.0**
-- **PHP >= 8.3**
+- **Composer ≥ 2.8** (released Oct 2, 2024) — earlier versions miss audit/security features below
+- **PHP ≥ 8.3** in `require` (8.4 recommended for new projects — see `php-patterns`)
+- **`composer.lock` MUST be committed** for both apps and libraries
 
 ## Essential Commands
 
 ```bash
-composer install              # Install from lock file (CI/deploy)
-composer update               # Update dependencies (dev only)
-composer require package/name # Add dependency
-composer require --dev pkg    # Add dev dependency
-composer dump-autoload -o     # Optimize autoloader (production)
+composer install                     # From lock — used in CI/deploy
+composer install --no-dev --optimize-autoloader --classmap-authoritative  # Production
+composer update                      # Refresh lock — dev only, never CI
+composer update --patch-only         # 2.8+: only patch versions (safe weekly)
+composer update vendor/pkg --with-all-dependencies   # Update one + its deps
+
+composer require vendor/pkg          # Add runtime
+composer require --dev vendor/pkg    # Add dev-time
+composer remove vendor/pkg
+
+composer audit                       # Security scan — MUST be in CI
+composer audit --abandoned=fail      # 2.8+: also fail on abandoned packages
+composer audit --ignore-severity=low # 2.8+: skip noisy lows in CI
+
+composer outdated                    # List packages with newer releases
+composer outdated --direct           # Only top-level deps
+composer outdated --major-only       # Only majors (planning sessions)
+
+composer dump-autoload --optimize    # Regenerate, optimized
+composer validate --strict           # composer.json sanity check
+composer why vendor/pkg              # Who pulled this in?
+composer why-not vendor/pkg "^2.0"   # Why can't I install this version?
 ```
 
-## composer.json Structure
+## composer.json — production-grade baseline
 
 ```json
 {
     "name": "vendor/project",
     "type": "project",
+    "license": "proprietary",
     "require": {
-        "php": ">=8.3"
+        "php": "^8.3",
+        "ext-mbstring": "*",
+        "ext-pdo": "*"
     },
     "require-dev": {
-        "phpunit/phpunit": "^11.0",
+        "phpunit/phpunit": "^12.0",
+        "pestphp/pest": "^4.0",
         "phpstan/phpstan": "^2.0",
-        "friendsofphp/php-cs-fixer": "^3.0"
+        "phpstan/phpstan-deprecation-rules": "^2.0",
+        "friendsofphp/php-cs-fixer": "^3.0",
+        "roave/security-advisories": "dev-latest"
     },
     "autoload": {
-        "psr-4": {
-            "App\\": "src/"
-        }
+        "psr-4": { "App\\": "src/" }
     },
     "autoload-dev": {
-        "psr-4": {
-            "Tests\\": "tests/"
-        }
+        "psr-4": { "Tests\\": "tests/" }
     },
     "scripts": {
-        "test": "phpunit",
-        "lint": "phpstan analyse --level=6",
-        "format": "php-cs-fixer fix",
-        "check": [
-            "@lint",
-            "@test"
-        ]
+        "test":    "phpunit",
+        "test:cov":"XDEBUG_MODE=coverage phpunit --coverage-text --coverage-clover=coverage.xml",
+        "lint":    "phpstan analyse --memory-limit=1G",
+        "fix":     "php-cs-fixer fix",
+        "fix:check":"php-cs-fixer fix --dry-run --diff",
+        "audit":   "composer audit --abandoned=fail",
+        "check":   ["@lint", "@fix:check", "@audit", "@test"]
+    },
+    "scripts-descriptions": {
+        "check": "Run full quality gate locally — mirrors CI"
     },
     "config": {
         "sort-packages": true,
-        "allow-plugins": {}
-    }
+        "optimize-autoloader": true,
+        "preferred-install": "dist",
+        "allow-plugins": {
+            "pestphp/pest-plugin": true
+        }
+    },
+    "minimum-stability": "stable",
+    "prefer-stable": true
 }
 ```
 
+## Audit — exit codes (2.8+, use in CI)
+
+| Exit | Meaning |
+|---|---|
+| `0` | Clean |
+| `1` | Vulnerabilities found |
+| `2` | Abandoned packages found (with `--abandoned=fail`) |
+| `3` | Both |
+
+```yaml
+# .github/workflows/ci.yml — fail PR on vulns OR abandoned packages
+- name: Composer audit
+  run: composer audit --abandoned=fail --ignore-severity=low
+```
+
+The `--ignore-severity` flag is critical for CI ergonomics — without it a single LOW advisory blocks every PR.
+
+## Supply-Chain Hardening (links to security-baseline 2025-A03)
+
+```bash
+# Production install — never run third-party scripts on the build server
+composer install --no-dev --no-scripts --optimize-autoloader --classmap-authoritative
+```
+
+`config.allow-plugins` is a strict allowlist as of 2.x — Composer prompts/refuses unknown plugins. Keep the list minimal:
+
+```json
+"config": {
+  "allow-plugins": {
+    "pestphp/pest-plugin": true,
+    "php-http/discovery": false
+  }
+}
+```
+
+Pin **Roave Security Advisories** as a `dev` dep — it makes Composer **refuse to install** any version with a known CVE:
+
+```bash
+composer require --dev roave/security-advisories:dev-latest
+```
+
 ## PSR-4 Autoloading
 
 ```
@@ -71,13 +144,24 @@ src/
 ├── Models/
 │   └── User.php              → App\Models\User
 └── Middleware/
-    └── AuthMiddleware.php     → App\Middleware\AuthMiddleware
+    └── AuthMiddleware.php    → App\Middleware\AuthMiddleware
 ```
 
+For Laravel projects use `App\\` → `app/` (Laravel default), not `src/`.
+
+## Lockfile Hygiene
+
+- **Always commit** `composer.lock`
+- After `composer require/remove/update`, run `composer validate --strict` and commit the lock with the same commit
+- CI uses `composer install` (deterministic) — never `composer update`
+- Dependabot/Renovate watches `composer.json`; configure auto-merge for `--patch-only` after CI green
+
 ## Rules
 
-1. **Always commit composer.lock**
-2. **Never edit vendor/**
-3. **Use `composer install` in CI/production** (not update)
-4. **PHP >= 8.3 in require** — enforce minimum version
-5. **PSR-4 autoloading** — no manual includes
+1. **`composer.lock` is mandatory in git** — apps and libraries
+2. **Production = `--no-dev --no-scripts --optimize-autoloader --classmap-authoritative`** (supply-chain + perf)
+3. **CI runs `composer audit --abandoned=fail`** — failing the build on vulns or abandons
+4. **Never edit `vendor/`** — patch via `cweagans/composer-patches` if absolutely required
+5. **Pin `php` constraint** to your runtime (`^8.3` or `^8.4`); upgrade deliberately
+6. **Roave Security Advisories** as a dev dep on every project
+7. **Allow-plugins allowlist** kept minimal and reviewed

package/stacks/php/skills/external-api-patterns/SKILL.md

@@ -1,23 +1,37 @@
 ---
 name: external-api-patterns
-version: 1.0.0
+version: 2.0.0
+description: "Laravel patterns for consuming external APIs / SDKs / webhooks (2026). Two recommended approaches: (1) Laravel HTTP Client (`Http::`) wrapped in a Service for one-off integrations; (2) Saloon v3 for SDK-style integrations with multiple endpoints (Connectors + Requests + Responses, retry/auth/middleware/pagination first-class, mock client for testing, Laravel plugin). Octane-safe (no static client state), typed DTOs, typed exceptions, structured logging, idempotent webhook reception with signature verification (2025-A10 fail-closed). Invoke when adding any third-party integration or webhook handler."
 ---
 
-# External API Patterns — HTTP Client for Laravel + Octane
+# External API Patterns — Laravel + Octane (2026)
 
 **ALWAYS invoke when consuming external APIs, webhooks, or third-party services.**
 
+## Choose your tool
+
+| Scenario | Tool |
+|---|---|
+| 1–3 endpoints from one vendor, simple req/res | Laravel `Http::` Client wrapped in a Service |
+| SDK-shaped integration: many endpoints, auth flows, pagination, custom responses | **Saloon v3** (Connectors + Requests + Responses) |
+| Vendor publishes its own SDK | Use the SDK; still wrap in a Service for testability |
+
+Either way: **never call `Http::` or a vendor SDK directly from a Controller**. Always go through an injected Service.
+
 ## Architecture
 
 ```
-Controller/Job
-  → ApiService (business logic)
-    → Http::withOptions() (Laravel HTTP Client)
-      → Response handling (DTO)
-        → Error handling (typed exceptions)
-          → Logging + monitoring
-
-NEVER call Http:: directly in controllers. Always through a Service.
+Controller / Job / Listener
+        ↓
+ApiService (business logic, transactions)
+        ↓
+HTTP transport
+  ├── Http::baseUrl(...) → response()->json()        (Laravel Client path)
+  └── new Connector → ->send(new Request())          (Saloon path)
+        ↓
+Typed DTO (readonly class)
+        ↓
+Typed exception on failure / log + return on success
 ```
 
 ## Service Pattern
@@ -308,100 +322,157 @@ class AiModelController extends Controller
 }
 ```
 
-## Frontend Consumption (React + Inertia)
+## Saloon v3 — SDK-style integrations *(2026 recommended)*
 
-```tsx
-// resources/js/services/api.ts
-import axios, { AxiosError } from 'axios';
+Use when the integration has **many endpoints, auth flows, pagination, or warrants its own folder**. Saloon turns "an API" into an OOP shape: a `Connector` (base URL + auth + middleware) plus one `Request` per endpoint plus optional custom `Response` classes.
 
-interface ApiResponse<T> {
-    success: boolean;
-    message: string;
-    data: T;
-    errors?: Record<string, string[]>;
-}
+### Install
 
-interface ApiErrorResponse {
-    success: false;
-    message: string;
-    errors?: Record<string, string[]>;
-    retry_after?: number;
-}
+```bash
+composer require saloonphp/saloon "^3.0"
+composer require saloonphp/laravel-plugin "^4.0"   # Laravel integration
+php artisan vendor:publish --tag=saloon-config
+```
 
-export async function apiCall<T>(
-    method: 'get' | 'post' | 'put' | 'delete',
-    url: string,
-    data?: unknown,
-): Promise<T> {
-    try {
-        const response = await axios({ method, url, data });
-        const body = response.data as ApiResponse<T>;
-        if (!body.success) throw new ApiError(body.message, response.status);
-        return body.data;
-    } catch (error) {
-        if (error instanceof AxiosError) {
-            const body = error.response?.data as ApiErrorResponse;
-            const status = error.response?.status ?? 500;
-
-            if (status === 429) {
-                throw new RateLimitError(body?.retry_after ?? 60);
-            }
-            if (status === 422 && body?.errors) {
-                throw new ValidationError(body.message, body.errors);
-            }
-            throw new ApiError(body?.message ?? 'Connection failed', status);
-        }
-        throw error;
+### Folder layout
+
+```
+app/Http/Integrations/
+└── OpenAi/
+    ├── OpenAiConnector.php
+    ├── Requests/
+    │   ├── ChatCompletion.php
+    │   └── Embeddings.php
+    └── Responses/
+        └── ChatCompletionResponse.php
+```
+
+### Connector
+
+```php
+// app/Http/Integrations/OpenAi/OpenAiConnector.php
+namespace App\Http\Integrations\OpenAi;
+
+use Saloon\Http\Connector;
+use Saloon\Http\Auth\TokenAuthenticator;
+use Saloon\Traits\Plugins\AcceptsJson;
+use Saloon\RateLimitPlugin\Traits\HasRateLimits;
+
+class OpenAiConnector extends Connector
+{
+    use AcceptsJson;
+    use HasRateLimits;
+
+    public function resolveBaseUrl(): string
+    {
+        return config('services.openai.base_url', 'https://api.openai.com/v1');
     }
-}
 
-// Typed errors
-export class ApiError extends Error {
-    constructor(message: string, public status: number) { super(message); }
-}
-export class ValidationError extends ApiError {
-    constructor(message: string, public errors: Record<string, string[]>) { super(message, 422); }
+    protected function defaultHeaders(): array
+    {
+        return ['User-Agent' => 'myapp/1.0'];
+    }
+
+    protected function defaultAuth(): TokenAuthenticator
+    {
+        return new TokenAuthenticator(config('services.openai.key'));
+    }
+
+    protected function defaultConfig(): array
+    {
+        return ['timeout' => 30, 'connect_timeout' => 5];
+    }
 }
-export class RateLimitError extends ApiError {
-    constructor(public retryAfter: number) { super('Too many requests', 429); }
+```
+
+### Request
+
+```php
+// app/Http/Integrations/OpenAi/Requests/ChatCompletion.php
+namespace App\Http\Integrations\OpenAi\Requests;
+
+use Saloon\Contracts\Body\HasBody;
+use Saloon\Enums\Method;
+use Saloon\Http\Request;
+use Saloon\Traits\Body\HasJsonBody;
+
+class ChatCompletion extends Request implements HasBody
+{
+    use HasJsonBody;
+
+    protected Method $method = Method::POST;
+
+    public function __construct(
+        protected readonly string $model,
+        protected readonly array  $messages,
+        protected readonly float  $temperature = 0.7,
+    ) {}
+
+    public function resolveEndpoint(): string { return '/chat/completions'; }
+
+    protected function defaultBody(): array
+    {
+        return [
+            'model'       => $this->model,
+            'messages'    => $this->messages,
+            'temperature' => $this->temperature,
+        ];
+    }
 }
 ```
 
-### React Component Usage
+### Calling from a Service
 
-```tsx
-const LABELS = {
-    generating: __('messages.ai.generating'),
-    error: __('messages.errors.error'),
-    rateLimited: __('messages.errors.rate_limited'),
-} as const;
+```php
+namespace App\Services\External;
 
-export default function AiChat() {
-    const [loading, setLoading] = useState(false);
+use App\Http\Integrations\OpenAi\OpenAiConnector;
+use App\Http\Integrations\OpenAi\Requests\ChatCompletion;
+use App\DTOs\Api\ChatCompletionResponse;
 
-    const generate = async () => {
-        setLoading(true);
-        try {
-            const result = await apiCall<{ content: string }>('post', route('api.v1.ai.generate'), {
-                model: 'gpt-4',
-                messages: [{ role: 'user', content: prompt }],
-            });
-            setResponse(result.content);
-        } catch (error) {
-            if (error instanceof RateLimitError) {
-                toast.error(`${LABELS.rateLimited} (${error.retryAfter}s)`);
-            } else if (error instanceof ValidationError) {
-                Object.values(error.errors).flat().forEach(msg => toast.error(msg));
-            } else {
-                toast.error(error instanceof ApiError ? error.message : LABELS.error);
-            }
-        } finally {
-            setLoading(false);
-        }
-    };
+class OpenAiService
+{
+    public function __construct(private readonly OpenAiConnector $api) {}
+
+    public function chat(string $model, array $messages): ChatCompletionResponse
+    {
+        $response = $this->api
+            ->send(new ChatCompletion($model, $messages))
+            ->throw();
+        return ChatCompletionResponse::fromArray($response->json());
+    }
 }
 ```
 
+### Test with Saloon's MockClient
+
+```php
+use Saloon\Http\Faking\MockClient;
+use Saloon\Http\Faking\MockResponse;
+use App\Http\Integrations\OpenAi\Requests\ChatCompletion;
+
+it('returns the assistant message', function () {
+    $mock = new MockClient([
+        ChatCompletion::class => MockResponse::make(['choices' => [['message' => ['content' => 'hi']]], 'usage' => ['prompt_tokens' => 1, 'completion_tokens' => 1]], 200),
+    ]);
+    app(OpenAiConnector::class)->withMockClient($mock);
+
+    $resp = app(OpenAiService::class)->chat('gpt-4', [['role' => 'user', 'content' => 'hi']]);
+    expect($resp->content)->toBe('hi');
+});
+```
+
+### When Saloon shines vs raw `Http::`
+
+- **Auth is non-trivial** (OAuth2 device flow, signed requests, paginated tokens)
+- **Pagination** (cursor / page / link-header) — Saloon ships first-class paginators
+- **Many endpoints** sharing the same base config — DRY via the Connector
+- **Test coverage matters** — `MockClient` captures request shape, not just HTTP verb
+- **Ratelimit awareness** — `HasRateLimits` plugin tracks per-connector budgets
+- **Want the API to feel like a vendor SDK** to your call sites
+
+For 1-2 throwaway endpoints, raw `Http::` is fine — don't over-engineer.
+
 ## Octane Safety
 
 ```php
@@ -513,6 +584,17 @@ Log::error('[ServiceName] API failed', [
 | `static $client` in Octane | Instance `$this->client` per request |
 | No timeout on HTTP calls | `->timeout(30)->connectTimeout(5)` |
 | No retry logic | `->retry(3, backoff, when)` |
-| Webhook without signature check | ALWAYS verify signatures |
+| Webhook without signature check | ALWAYS verify signatures (2025-A10 fail-closed) |
 | Webhook sync processing | Dispatch job for async |
 | `dd()` / `dump()` API responses | Structured `Log::info/error` |
+| Many endpoints inlined as `Http::` calls | Promote to Saloon Connector + Requests |
+| Mocking Saloon by stubbing `Http::` | Use `MockClient` (matches by Request class) |
+
+## See Also
+
+- `axios-laravel-api` (frontend) — the React side that consumes this Laravel API
+- `api-design` / `api-security` — request shape + Sanctum patterns
+- `_shared/skills/security-baseline` (2025-A03 + 2025-A10) — supply chain + fail-closed
+- `_shared/skills/observability` — structured logging + redaction
+- `mariadb-octane` — transaction safety when API call participates in a DB transaction
+- `phpunit-testing` — Pest 4 patterns for Saloon `MockClient` and `Http::fake()`

package/stacks/php/skills/laravel-octane/SKILL.md

@@ -1,9 +1,10 @@
 ---
 name: laravel-octane
-version: 1.0.0
+version: 2.0.0
+description: "Laravel Octane patterns for production 2026 — covers FrankenPHP (recommended for new projects: single binary, automatic HTTPS, HTTP/3, early hints, Brotli, ~5× FPM throughput), RoadRunner (mature, best raw RPS, gRPC/WebSocket), and Swoole (best for I/O-heavy workloads via coroutines). Long-lived worker rules: no static state, no globals, no superglobals, no config() mutations, no die/exit/dd, scoped bindings instead of singletons, persistent DB connections with Octane flush, instance-scoped memoization. Includes server selection matrix and per-server config. Invoke when adopting Octane, choosing a server, debugging worker leaks, or hardening for persistent processes."
 ---
 
-# Laravel Octane (RoadRunner) Patterns
+# Laravel Octane Patterns (FrankenPHP / RoadRunner / Swoole)
 
 ## How Octane Works
 
@@ -11,6 +12,16 @@ Octane runs your app in a **long-lived worker process**. The application boots O
 
 **Consequence:** Any state stored in static properties, globals, or singletons persists across requests and can leak between users.
 
+## Server Selection — 2026 matrix
+
+| Server | When to choose | Strengths | Trade-offs |
+|---|---|---|---|
+| **FrankenPHP** | New projects; teams that value simplicity | Single Go binary; automatic HTTPS via Caddy; **HTTP/3**, early hints, Brotli; 5× PHP-FPM in 2025 benchmarks | Smaller community; weaker under heavy I/O latency |
+| **RoadRunner** | Production at scale; need consistent top-tier RPS | Battle-tested; ~111% higher RPS than FPM; gRPC + WebSocket built-in; rich plugin ecosystem | Steeper DevOps curve; YAML config |
+| **Swoole** | Workloads dominated by 200–500 ms I/O waits (DB, upstream APIs) | Coroutine concurrency shines under high I/O latency | Lower RPS in light-I/O workloads; smaller adoption for new apps |
+
+Default recommendation for new Laravel 12 projects in 2026: **FrankenPHP** (developer experience + modern HTTP). Pick **RoadRunner** if you've already standardized on it or need its specific features.
+
 ## Critical Rules
 
 ### DO: Dependency Injection
@@ -165,6 +176,67 @@ app()->scoped('cart', fn () => new Cart());
 // Fresh instance per request, cleared between requests
 ```
 
+## FrankenPHP Configuration *(2026 default)*
+
+Single binary; Caddy-based HTTPS; no PHP extension required.
+
+```bash
+composer require laravel/octane
+php artisan octane:install --server=frankenphp
+php artisan octane:start --server=frankenphp --workers=4 --max-requests=500
+```
+
+`Caddyfile` (production-grade, with HTTP/3 + early hints):
+
+```caddyfile
+{
+    frankenphp
+    order php_server before file_server
+    servers {
+        protocols h1 h2 h2c h3
+    }
+}
+
+api.example.com {
+    encode br zstd gzip
+    root * public/
+    php_server {
+        worker /path/to/public/frankenphp-worker.php 4
+    }
+    header ?Permissions-Policy "interest-cohort=()"
+    header Early-Hints rel=preload
+}
+```
+
+`public/frankenphp-worker.php` (worker mode — what gives you the 5× speedup):
+
+```php
+<?php
+ignore_user_abort(true);
+require __DIR__.'/../vendor/autoload.php';
+$app = require __DIR__.'/../bootstrap/app.php';
+$kernel = $app->make(Illuminate\Contracts\Http\Kernel::class);
+
+$max = (int)($_SERVER['MAX_REQUESTS'] ?? 500);
+for ($i = 0; $i < $max; $i++) {
+    $keepRunning = \frankenphp_handle_request(function () use ($kernel) {
+        $request = Illuminate\Http\Request::capture();
+        $response = $kernel->handle($request);
+        $response->send();
+        $kernel->terminate($request, $response);
+    });
+    gc_collect_cycles();
+    if (!$keepRunning) break;
+}
+```
+
+| Setting | Where | Notes |
+|---|---|---|
+| `--workers` | CLI | Defaults to CPU cores; tune to CPU/IO ratio |
+| `--max-requests` | CLI | Restart worker after N requests (memory safety, like RoadRunner's `max_jobs`) |
+| `protocols h3` | Caddyfile | Enable HTTP/3 (QUIC) — single biggest mobile-network win |
+| `Early-Hints` header | Response | Browser preloads CSS/JS during PHP think-time |
+
 ## RoadRunner Configuration (rr.yaml)
 
 ```yaml