start-vibing-stacks 2.2.0 → 2.3.0

package/stacks/frontend/react-inertia/skills/react-standards/SKILL.md

@@ -0,0 +1,267 @@
+# React 19+ Standards (with Inertia.js)
+
+## Version Requirements
+
+- **ReactJS >= 19** — MANDATORY
+- **TailwindCSS >= 4** — MANDATORY
+- **Inertia.js >= 2** — MANDATORY
+
+## Translation Pattern (via Inertia shared props)
+
+```tsx
+import __ from '@/Utils/translate';
+
+// CORRECT: Translations as CONST at the top, BEFORE hooks
+const LABELS = {
+    title: __('dashboard.title'),
+    save: __('common.save'),
+    cancel: __('common.cancel'),
+    errorRequired: __('errors.field_required'),
+    welcome: __('dashboard.welcome', { name: 'User' }),
+};
+
+export default function Dashboard() {
+    const [data, setData] = useState(null);
+
+    return <h1>{LABELS.title}</h1>;
+}
+
+// WRONG: __() inside JSX (Hook violation — usePage() is called internally)
+return <h1>{__('dashboard.title')}</h1>; // NEVER
+```
+
+**Rules:**
+- Translations in `CONST` variables before state hooks
+- New strings must be added to `lang/en/*.php` AND `lang/pt/*.php`
+- Error strings centralized in `lang/*/errors.php`
+- Use replacements for dynamic values: `__('key', { name: value })`
+
+## Debug Logging
+
+```tsx
+const ENABLE_DASHBOARD_DEBUG = false;
+
+const debugLog = (...args: unknown[]) => {
+    if (ENABLE_DASHBOARD_DEBUG) console.log('[Dashboard]', ...args);
+};
+
+export default function Dashboard() {
+    debugLog('Rendering with data:', data);
+}
+```
+
+**Rule:** Never leave raw `console.log`. Always use controlled debug pattern.
+
+## TailwindCSS Class Organization
+
+```tsx
+// CORRECT: Classes as CONST — clean JSX
+const STYLES = {
+    container: 'flex flex-col gap-4 p-6 bg-white rounded-lg shadow-sm',
+    title: 'text-2xl font-bold text-gray-900',
+    button: 'px-4 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700 transition',
+    grid: 'grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6',
+};
+
+export default function Dashboard() {
+    return (
+        <div className={STYLES.container}>
+            <h1 className={STYLES.title}>{LABELS.title}</h1>
+        </div>
+    );
+}
+
+// WRONG: Inline class soup
+<div className="flex flex-col gap-4 p-6 bg-white rounded-lg shadow-sm"> // NEVER
+```
+
+## SVG Icons
+
+```tsx
+// CORRECT: Separate files, import with ?react
+import CheckIcon from '@/Icons/CheckIcon.svg?react';
+import { CheckIcon, AlertIcon } from '@/Icons';
+
+// WRONG: Inline SVG (bloats JSX)
+<svg viewBox="0 0 24 24">...</svg> // NEVER
+```
+
+**Structure:**
+```
+resources/js/Icons/
+├── index.js           # Barrel export
+├── CheckIcon.svg
+├── AlertIcon.svg
+└── SpinnerIcon.svg
+```
+
+## Inertia.js Hooks & Navigation
+
+### Accessing Shared Props
+
+```tsx
+import { usePage } from '@inertiajs/react';
+
+export default function Header() {
+    const { auth, locale, flash } = usePage().props;
+
+    return (
+        <nav>
+            <span>{auth.user?.name}</span>
+            {flash.success && <Alert>{flash.success}</Alert>}
+        </nav>
+    );
+}
+```
+
+### Forms with useForm
+
+```tsx
+import { useForm } from '@inertiajs/react';
+
+export default function CreateOrder() {
+    const { data, setData, post, processing, errors } = useForm({
+        product_id: '',
+        quantity: 1,
+        notes: '',
+    });
+
+    const handleSubmit = (e) => {
+        e.preventDefault();
+        post(route('orders.store'));
+    };
+
+    return (
+        <form onSubmit={handleSubmit}>
+            <Input
+                value={data.product_id}
+                onChange={(e) => setData('product_id', e.target.value)}
+                error={errors.product_id}
+            />
+            <Button type="submit" loading={processing}>
+                {processing ? <LoadingSpinner /> : LABELS.save}
+            </Button>
+        </form>
+    );
+}
+```
+
+**Rules:**
+- Use `useForm` for ALL form submissions (handles CSRF, errors, loading)
+- `processing` boolean for button loading states
+- `errors` object maps to Form Request validation errors
+- Never use `fetch()` or `axios` for form submissions
+
+### Navigation
+
+```tsx
+import { Link, router } from '@inertiajs/react';
+
+// SPA links (no full page reload)
+<Link href={route('orders.index')}>Orders</Link>
+
+// Programmatic navigation
+router.visit(route('dashboard'));
+
+// Partial reload (only refresh specific props)
+router.reload({ only: ['stats', 'recentOrders'] });
+```
+
+## Loading States
+
+```tsx
+// CORRECT: Always show loading feedback
+export default function DataTable() {
+    const [loading, setLoading] = useState(true);
+
+    if (loading) {
+        return <SectionLoader />;
+    }
+
+    return <Table data={data} />;
+}
+
+// Button loading (from useForm)
+<Button onClick={handleSave} disabled={processing}>
+    {processing ? <LoadingSpinner /> : LABELS.save}
+</Button>
+```
+
+**Rule:** Every data-heavy section needs a loading state.
+
+## Modal Data Flow
+
+```tsx
+interface EditModalProps {
+    item: Item;
+    isOpen: boolean;
+    onClose: () => void;
+    onUpdated: () => void;
+}
+
+function EditModal({ item, isOpen, onClose, onUpdated }: EditModalProps) {
+    const { data, setData, put, processing } = useForm({
+        name: item.name,
+    });
+
+    const handleSave = (e) => {
+        e.preventDefault();
+        put(route('items.update', item.id), {
+            onSuccess: () => {
+                onUpdated();
+                onClose();
+            },
+        });
+    };
+}
+
+// Parent: use router.reload for refresh after modal mutation
+<EditModal
+    item={selectedItem}
+    isOpen={showModal}
+    onClose={() => setShowModal(false)}
+    onUpdated={() => router.reload({ only: ['items'] })}
+/>
+```
+
+## Third-Party Libraries (Charts)
+
+```tsx
+// CORRECT: Let React handle re-rendering
+{chartData && (
+    <ApexChart
+        key={JSON.stringify(chartData)}
+        options={chartOptions}
+        series={chartData}
+        type="area"
+    />
+)}
+
+// WRONG: Manual DOM manipulation
+const chartRef = useRef(null);
+chartRef.current.updateSeries(newData); // NEVER
+
+// Memoize expensive computations
+const processedData = useMemo(() => {
+    return heavyTransform(rawData);
+}, [rawData]);
+```
+
+**Rules:**
+- No `useRef` for updating third-party components
+- Conditional rendering: `data && <Component />`
+- `useMemo` for expensive computations
+- Loading states before rendering charts
+
+## Forbidden Patterns
+
+| Pattern | Reason | Use Instead |
+|---------|--------|-------------|
+| `fetch()` / `axios` for pages | Bypasses Inertia | `Inertia::render()` props |
+| `__()` inside JSX | Hook violation | CONST at top |
+| Inline SVGs | Bloats components | SVG files + `?react` |
+| `<a href>` for internal links | Full reload | `<Link href>` |
+| `window.location` | Full reload | `router.visit()` |
+| Raw `console.log` | Uncontrolled | Debug constant pattern |
+| Inline Tailwind soup | Unreadable | STYLES const object |
+| `axios.post()` for forms | No CSRF/errors | `useForm().post()` |

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

@@ -1,92 +1,170 @@
 # Laravel Octane (RoadRunner) Patterns
 
-## Critical Rules
+## How Octane Works
 
-Octane runs your app in a **long-lived process** — different from traditional PHP.
+Octane runs your app in a **long-lived worker process**. The application boots ONCE and handles many requests without restarting. This is fundamentally different from traditional PHP where each request boots a fresh process.
 
-### ✅ DO
+**Consequence:** Any state stored in static properties, globals, or singletons persists across requests and can leak between users.
 
-```php
-// Dependency Injection over resolve()
-public function __construct(
-    private readonly UserService $userService,
-) {}
+## Critical Rules
 
-// Use Request object
-public function store(Request $request): JsonResponse
+### DO: Dependency Injection
+
+```php
+// CORRECT: Constructor injection (resolved fresh per request scope)
+class OrderController extends Controller
 {
-    $name = $request->input('name');
+    public function __construct(
+        private readonly OrderService $orderService,
+        private readonly CacheManager $cache,
+    ) {}
 }
 
-// Persistent DB connections with flush
-// config/database.php
-'options' => [PDO::ATTR_PERSISTENT => true]
-// Octane::prepare to flush connections between requests
+// CORRECT: Method injection in controller actions
+public function store(StoreOrderRequest $request, PaymentGateway $gateway): JsonResponse
+{
+    $result = $gateway->charge($request->validated());
+    return response()->json($result, 201);
+}
 ```
 
-### ❌ NEVER
+### DO: Use the Request Object
 
 ```php
-// Static state (leaks between requests!)
-class Service {
-    private static array $cache = []; // ❌ LEAKS
+public function store(Request $request): JsonResponse
+{
+    $name = $request->input('name');
+    $token = $request->bearerToken();
+    $ip = $request->ip();
+    $user = $request->user();
 }
-
-// Global variables
-global $user; // ❌
-
-// Modifying config at runtime
-config(['app.name' => 'New']); // ❌ Affects ALL requests
-
-// die() or exit()
-die('error'); // ❌ Kills the worker
-
-// Superglobals
-$_GET['id']; // ❌ Stale between requests
-$_POST['name']; // ❌
-$_SESSION['user']; // ❌
 ```
 
-### AppServiceProvider — Connection Flush
+### DO: Persistent DB Connections with Flush
 
 ```php
-// app/Providers/AppServiceProvider.php
-use Laravel\Octane\Facades\Octane;
-
-public function boot(): void
-{
-    // MANDATORY: flush DB connections between requests
-    Octane::prepare(fn ($sandbox) => $sandbox->flushDatabaseConnections());
-}
+// config/database.php
+'mysql' => [
+    'options' => [
+        PDO::ATTR_PERSISTENT => true,
+    ],
+],
+
+// Octane automatically flushes connections between requests
+// via Octane::prepare() — no manual work needed
 ```
 
-**Rule:** ALWAYS pair persistent connections with `Octane::prepare` flush in AppServiceProvider.
-
-### Memoization in Workers
+### DO: Instance-scoped Memoization
 
 ```php
 // ✅ Scoped to instance, cleared per request
 class ProcessLeadsJob implements ShouldQueue
 {
     private array $lookupCache = [];
-    
+
     public function handle(): void
     {
         foreach ($this->leads as $lead) {
-            $result = $this->lookupCache[$lead->key] 
+            $result = $this->lookupCache[$lead->key]
                 ??= $this->expensiveLookup($lead->key);
         }
-        // Cache is GC'd when job instance is destroyed
+        // Cache is garbage collected when job instance is destroyed
     }
 }
+```
+
+## NEVER Do These in Octane
+
+### No Static State
+
+```php
+// WRONG: Static properties persist across ALL requests
+class AuthService {
+    private static ?User $currentUser = null; // LEAKS between users!
+    private static array $cache = [];          // Grows forever!
+}
 
-// ❌ Static cache (persists across jobs in Octane!)
-private static array $cache = [];
+// CORRECT: Instance properties (scoped to request)
+class AuthService {
+    private ?User $currentUser = null;
+    private array $cache = [];
+}
+```
+
+### No Global Variables
+
+```php
+// WRONG
+global $config;
+$GLOBALS['user'] = $user;
+
+// CORRECT: Use DI or config()
+$value = config('app.name');
+```
+
+### No Runtime Config Mutation
+
+```php
+// WRONG: Affects ALL concurrent requests in the worker
+config(['app.timezone' => 'America/Sao_Paulo']);
+config(['services.stripe.key' => $newKey]);
+
+// CORRECT: Pass values explicitly
+$this->service->processWithTimezone('America/Sao_Paulo');
+```
+
+### No Process Termination
+
+```php
+// WRONG: Kills the entire worker process
+die('Something went wrong');
+exit(1);
+dd($variable);
+
+// CORRECT: Throw exceptions (handled by Laravel)
+throw new RuntimeException('Something went wrong');
+abort(500, 'Internal error');
+
+// For debugging: use dump() without die
+dump($variable); // Outputs without killing worker
+Log::debug('Debug info', ['var' => $variable]);
+```
+
+### No Superglobals
+
+```php
+// WRONG: Stale data from previous requests
+$_GET['id'];
+$_POST['name'];
+$_SESSION['user'];
+$_SERVER['HTTP_AUTHORIZATION'];
+$_COOKIE['token'];
+
+// CORRECT: Use Request object
+$request->input('id');
+$request->post('name');
+$request->session()->get('user');
+$request->header('Authorization');
+$request->cookie('token');
+```
+
+### No Singleton Abuse
+
+```php
+// WRONG: Singleton state leaks
+app()->singleton('cart', fn () => new Cart());
+// The same Cart instance serves ALL users!
+
+// CORRECT: Use scoped bindings
+app()->scoped('cart', fn () => new Cart());
+// Fresh instance per request, cleared between requests
 ```
 
 ## RoadRunner Configuration (rr.yaml)
 
 ```yaml
+version: '3'
+
 server:
   command: "php artisan octane:start --server=roadrunner --host=0.0.0.0 --port=8000"
 
@@ -94,17 +172,41 @@ http:
   address: 0.0.0.0:8000
   pool:
     num_workers: 4
-    max_jobs: 500        # Restart worker after 500 requests (memory safety)
+    max_jobs: 500
     supervisor:
-      max_worker_memory: 128  # MB
+      max_worker_memory: 128
 
 logs:
   level: info
+  encoding: json
 ```
 
+### Worker Tuning
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `num_workers` | CPU cores | Number of worker processes |
+| `max_jobs` | 500 | Restart worker after N requests (memory safety) |
+| `max_worker_memory` | 128 MB | Kill worker if exceeds memory |
+
+**Rule:** Always set `max_jobs` to prevent memory leaks from accumulating.
+
 ## Database Safety
 
 - **NEVER** execute `db:wipe`, `migrate:fresh`, `migrate:refresh`, `db:reset`
 - **ALWAYS** use incremental migrations (`make:migration`)
-- If migration fails → fix the file or create a new one
+- If migration fails, fix the file or create a new one
 - Assume **all environments contain critical data**
+
+## Octane Checklist
+
+- [ ] No `static` properties on service classes
+- [ ] No global variables or `$GLOBALS`
+- [ ] No `config()` mutations at runtime
+- [ ] No `die()`, `exit()`, or `dd()` in production code
+- [ ] No superglobals (`$_GET`, `$_POST`, `$_SESSION`, `$_SERVER`)
+- [ ] No `app()->singleton()` for request-scoped data (use `scoped`)
+- [ ] All services use constructor DI (not `app()` or `resolve()`)
+- [ ] Memoization scoped to instance, not static
+- [ ] `max_jobs` configured in `rr.yaml` for memory safety
+- [ ] Persistent DB connections enabled with Octane flush