start-vibing-stacks 2.2.0 → 2.4.0

package/stacks/nodejs/skills/nextjs-app-router/SKILL.md

@@ -114,6 +114,104 @@ export async function generateMetadata({ params }: { params: { id: string } }) {
 }
 ```
 
+## Environment Variables & API Security (MANDATORY)
+
+> **NEXT_PUBLIC_ vars are embedded in the browser JS bundle.** Anyone can see them in DevTools.
+
+### Server vs Client Environment
+
+| Prefix | Accessible from | Safe for |
+|--------|----------------|----------|
+| No prefix | Server Components, Route Handlers, Server Actions | API keys, secrets, tokens, DB URLs |
+| `NEXT_PUBLIC_*` | Server + Browser (embedded in JS) | Public URLs, analytics IDs, publishable keys |
+
+### FORBIDDEN Environment Patterns
+
+```bash
+# NEVER DO THIS — secret exposed in browser bundle
+NEXT_PUBLIC_OPENAI_KEY=sk-abc123
+NEXT_PUBLIC_STRIPE_SECRET_KEY=sk_live_abc
+NEXT_PUBLIC_DATABASE_URL=postgresql://user:pass@host/db
+
+# CORRECT — server-only (no NEXT_PUBLIC_ prefix)
+OPENAI_KEY=sk-abc123
+STRIPE_SECRET_KEY=sk_live_abc
+DATABASE_URL=postgresql://user:pass@host/db
+
+# OK as NEXT_PUBLIC_ — no secret value
+NEXT_PUBLIC_APP_URL=https://myapp.com
+NEXT_PUBLIC_STRIPE_KEY=pk_live_abc
+NEXT_PUBLIC_GA_ID=G-XXXXX
+```
+
+### API Proxy Pattern (MANDATORY)
+
+External API calls with secrets MUST go through server-side Route Handlers:
+
+```tsx
+// app/api/ai/route.ts — Secret stays on server
+import { NextRequest, NextResponse } from 'next/server';
+
+export async function POST(req: NextRequest) {
+  const { prompt } = await req.json();
+
+  const response = await fetch('https://api.openai.com/v1/chat/completions', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${process.env['OPENAI_KEY']}`,
+    },
+    body: JSON.stringify({
+      model: 'gpt-4',
+      messages: [{ role: 'user', content: prompt }],
+    }),
+  });
+
+  if (!response.ok) {
+    return NextResponse.json({ error: 'AI request failed' }, { status: 502 });
+  }
+
+  return NextResponse.json(await response.json());
+}
+```
+
+```tsx
+// components/chat.tsx — Client calls YOUR route, not external API
+'use client';
+
+async function sendMessage(prompt: string) {
+  const res = await fetch('/api/ai', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ prompt }),
+  });
+  return res.json();
+}
+```
+
+### Server Actions for Mutations
+
+Server Actions also keep secrets server-side:
+
+```tsx
+// app/actions/payment.ts
+'use server';
+
+import Stripe from 'stripe';
+
+const stripe = new Stripe(process.env['STRIPE_SECRET_KEY']!);
+
+export async function createCheckout(priceId: string) {
+  const session = await stripe.checkout.sessions.create({
+    mode: 'payment',
+    line_items: [{ price: priceId, quantity: 1 }],
+    success_url: `${process.env['APP_URL']}/success`,
+    cancel_url: `${process.env['APP_URL']}/cancel`,
+  });
+  return { url: session.url };
+}
+```
+
 ## FORBIDDEN
 
 1. **`'use client'` on server-capable components** — default to server
@@ -121,3 +219,6 @@ export async function generateMetadata({ params }: { params: { id: string } }) {
 3. **`getServerSideProps` / `getStaticProps`** — App Router uses async components
 4. **API routes for server-only data** — use server components directly
 5. **Prop drilling through layouts** — use parallel routes or context
+6. **`NEXT_PUBLIC_` with API keys, secrets, or tokens** — secrets leak to browser bundle
+7. **Calling external APIs from client components** — use Route Handlers as proxy
+8. **`process.env['SECRET']` in `'use client'` files** — only `NEXT_PUBLIC_*` vars work client-side

package/stacks/nodejs/stack.json

@@ -1,29 +1,13 @@
 {
   "id": "nodejs",
   "name": "Node.js / TypeScript",
-  "icon": "\ud83d\udce6",
+  "icon": "📦",
   "runtime": "Bun / Node.js 20+",
   "minVersion": "20.0.0",
   "packageManager": "bun|npm|pnpm",
-  "extensions": [
-    ".ts",
-    ".tsx",
-    ".js",
-    ".jsx",
-    ".mjs",
-    ".cjs"
-  ],
-  "testExtensions": [
-    "*.test.ts",
-    "*.spec.ts",
-    "*.test.tsx"
-  ],
-  "detectFiles": [
-    "package.json",
-    "tsconfig.json",
-    "bun.lockb",
-    "next.config.js"
-  ],
+  "extensions": [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"],
+  "testExtensions": ["*.test.ts", "*.spec.ts", "*.test.tsx"],
+  "detectFiles": ["package.json", "tsconfig.json", "bun.lockb", "bun.lock", "next.config.js"],
   "commands": {
     "test": "bun run test",
     "lint": "bun run lint",
@@ -33,146 +17,95 @@
     "typecheck": "bun run typecheck"
   },
   "qualityGates": [
-    {
-      "name": "TypeCheck",
-      "command": "bun run typecheck",
-      "required": true,
-      "order": 1
-    },
-    {
-      "name": "Lint",
-      "command": "bun run lint",
-      "required": true,
-      "order": 2
-    },
-    {
-      "name": "Tests",
-      "command": "bun run test",
-      "required": true,
-      "order": 3
-    },
-    {
-      "name": "Build",
-      "command": "bun run build",
-      "required": true,
-      "order": 4
-    }
+    { "name": "TypeCheck", "command": "bun run typecheck", "required": true, "order": 1 },
+    { "name": "Lint", "command": "bun run lint", "required": true, "order": 2 },
+    { "name": "Tests", "command": "bun run test", "required": true, "order": 3 },
+    { "name": "Build", "command": "bun run build", "required": true, "order": 4 }
   ],
   "frameworks": [
     {
       "id": "nextjs",
       "name": "Next.js (App Router)",
-      "icon": "\u25b2",
-      "detectFiles": [
-        "next.config.js",
-        "next.config.ts",
-        "next.config.mjs"
-      ]
+      "icon": "▲",
+      "detectFiles": ["next.config.js", "next.config.ts", "next.config.mjs"],
+      "default": true,
+      "skills": ["nextjs-app-router"]
     },
     {
       "id": "nuxt",
       "name": "Nuxt",
-      "icon": "\ud83d\udc9a",
-      "detectFiles": [
-        "nuxt.config.ts"
-      ]
+      "icon": "💚",
+      "detectFiles": ["nuxt.config.ts"],
+      "skills": []
     },
     {
       "id": "astro",
       "name": "Astro",
-      "icon": "\ud83d\ude80",
-      "detectFiles": [
-        "astro.config.mjs"
-      ]
+      "icon": "🚀",
+      "detectFiles": ["astro.config.mjs"],
+      "skills": []
     },
     {
       "id": "express",
       "name": "Express",
-      "icon": "\u26a1"
+      "icon": "⚡",
+      "skills": ["trpc-api"]
     },
     {
       "id": "fastify",
       "name": "Fastify",
-      "icon": "\ud83c\udfce\ufe0f"
+      "icon": "🏎️",
+      "skills": ["trpc-api"]
     },
     {
       "id": "vanilla",
       "name": "Vanilla Node.js",
-      "icon": "\ud83d\udcc4"
+      "icon": "📄",
+      "skills": []
     }
   ],
   "databases": [
-    {
-      "id": "mongodb",
-      "name": "MongoDB",
-      "icon": "\ud83c\udf43"
-    },
-    {
-      "id": "postgresql",
-      "name": "PostgreSQL",
-      "icon": "\ud83d\udc18"
-    },
-    {
-      "id": "mysql",
-      "name": "MySQL / MariaDB",
-      "icon": "\ud83d\udc2c"
-    },
-    {
-      "id": "sqlite",
-      "name": "SQLite (Turso / libSQL)",
-      "icon": "\ud83d\udcc1"
-    },
-    {
-      "id": "redis",
-      "name": "Redis (Upstash)",
-      "icon": "\ud83d\udd34"
-    },
-    {
-      "id": "none",
-      "name": "None",
-      "icon": "\u274c"
-    }
+    { "id": "mongodb", "name": "MongoDB", "icon": "🍃" },
+    { "id": "postgresql", "name": "PostgreSQL", "icon": "🐘" },
+    { "id": "mysql", "name": "MySQL / MariaDB", "icon": "🐬" },
+    { "id": "sqlite", "name": "SQLite (Turso / libSQL)", "icon": "📁" },
+    { "id": "redis", "name": "Redis (Upstash)", "icon": "🔴" },
+    { "id": "none", "name": "None", "icon": "❌" }
   ],
   "frontendOptions": [
     {
       "id": "react-tailwind",
       "name": "React 19+ / TailwindCSS 4+",
-      "icon": "\u269b\ufe0f"
+      "icon": "⚛️",
+      "skillsDir": "react",
+      "default": true,
+      "frameworks": ["nextjs", "express", "fastify", "vanilla"]
     },
     {
       "id": "vue",
       "name": "Vue.js / Nuxt",
-      "icon": "\ud83d\udc9a"
+      "icon": "💚",
+      "frameworks": ["nuxt"]
     },
     {
       "id": "svelte",
       "name": "Svelte / SvelteKit",
-      "icon": "\ud83d\udd25"
-    },
-    {
-      "id": "shadcn",
-      "name": "shadcn/ui + Tailwind",
-      "icon": "\ud83c\udfa8"
+      "icon": "🔥",
+      "frameworks": ["astro", "vanilla"]
     },
     {
       "id": "none",
-      "name": "API only \u2014 no frontend",
-      "icon": "\u274c"
+      "name": "API only — no frontend",
+      "icon": "❌"
     }
   ],
   "deployTargets": [
-    {
-      "id": "github",
-      "name": "GitHub (git push)",
-      "icon": "\ud83d\udc19"
-    }
+    { "id": "github", "name": "GitHub (git push)", "icon": "🐙" }
   ],
   "skills": [
     "typescript-strict",
-    "react-patterns",
-    "nextjs-app-router",
-    "zod-validation",
-    "vitest-testing"
+    "bun-runtime",
+    "zod-validation"
   ],
   "requirements": [
     {
@@ -185,17 +118,6 @@
         "linux": "curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs"
       },
       "versionRegex": "v?(\\d+\\.\\d+\\.\\d+)"
-    },
-    {
-      "name": "Bun",
-      "command": "bun",
-      "versionFlag": "--version",
-      "minVersion": "1.0.0",
-      "installCommand": {
-        "macos": "brew install oven-sh/bun/bun",
-        "linux": "curl -fsSL https://bun.sh/install | bash"
-      },
-      "versionRegex": "(\\d+\\.\\d+\\.\\d+)"
     }
   ]
 }

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