start-vibing-stacks 2.2.0 → 2.4.0

package/stacks/php/skills/security-scan-php/SKILL.md

@@ -1,80 +1,198 @@
-# PHP Security Scan
+# Laravel Security Scan
 
-## OWASP Top 10 for PHP
+## OWASP Top 10 for Laravel
 
 ### A01 - Broken Access Control
 
 ```php
-// ❌ NEVER trust user input for authorization
-$userId = $_GET['user_id'];
+// WRONG: Trust user input for authorization
+$userId = $request->input('user_id');
 $user = User::find($userId);
 
-// ✅ Use authenticated session
-$user = Auth::user();
+// CORRECT: Use authenticated session
+$user = $request->user();
+
+// CORRECT: Scope queries by authenticated user
+$query = Resource::query();
+if (!$request->user()->isAdmin()) {
+    $query->where('user_id', $request->user()->id);
+}
 ```
 
+**Rules:**
+- NEVER return unscoped queries — always filter by authenticated user
+- Use Policies for authorization logic
+- Use Form Requests with `authorize()` method
+- Use Route Model Binding with scoping
+
 ### A02 - Cryptographic Failures
 
 ```php
-// ❌ NEVER
+// WRONG
 md5($password);
 sha1($password);
 
-// ✅ ALWAYS
-password_hash($password, PASSWORD_BCRYPT, ['cost' => 12]);
-password_verify($input, $hash);
+// CORRECT (Laravel handles this via Hash facade)
+Hash::make($password);
+Hash::check($input, $hashedPassword);
+
+// For API tokens: use Laravel Sanctum
+// Table: users_access_tokens (UUIDs + Soft Deletes)
+// All token actions logged via Loggable trait
 ```
 
 ### A03 - Injection
 
 ```php
-// ❌ SQL Injection
-$db->query("SELECT * FROM users WHERE id = {$_GET['id']}");
+// WRONG: SQL Injection via DB::raw
+$users = DB::select("SELECT * FROM users WHERE id = {$id}");
+DB::raw("WHERE name = '{$name}'");
 
-// ✅ Prepared statements (PDO)
-$stmt = $db->prepare("SELECT * FROM users WHERE id = :id");
-$stmt->execute([':id' => $id]);
+// CORRECT: Eloquent (preferred)
+$user = User::findOrFail($id);
 
-// ✅ Prepared statements (MySQLi)
-$stmt = $db->prepare("SELECT * FROM users WHERE id = ?");
-$stmt->bind_param('i', $id);
-$stmt->execute();
+// CORRECT: Query Builder with bindings
+$users = DB::table('users')->where('name', $name)->get();
+
+// CORRECT: Raw with parameter binding (last resort)
+$results = DB::select('SELECT * FROM users WHERE id = ?', [$id]);
 ```
 
 ### A07 - XSS Prevention
 
 ```php
-// ❌ Raw output
-echo $userInput;
+// WRONG: Unescaped output in Blade
+{!! $userInput !!}
 
-// ✅ Always escape
-echo htmlspecialchars($userInput, ENT_QUOTES, 'UTF-8');
+// CORRECT: Auto-escaped (Blade default)
+{{ $userInput }}
 
-// ✅ In templates (Blade)
-{{ $userInput }}  // Auto-escaped
-{!! $trustedHtml !!}  // Only for trusted content
+// Only use {!! !!} for TRUSTED, pre-sanitized HTML
+{!! $trustedHtmlFromCMS !!}
 ```
 
-## Security Checklist
+### A08 - Insecure Deserialization
+
+```php
+// WRONG: Unserialize user data
+$data = unserialize($request->input('data'));
+
+// CORRECT: Use JSON with Model casts
+protected $casts = [
+    'metadata' => 'array',
+    'settings' => 'array',
+];
+
+// CORRECT: Defensive JSON handling
+$data = is_string($model->data) 
+    ? json_decode($model->data, true) 
+    : $model->data;
+```
+
+## Laravel-Specific Security
+
+### Mass Assignment Protection
+
+```php
+// WRONG: No protection
+$user = User::create($request->all());
+
+// CORRECT: Define $fillable
+class User extends Model {
+    protected $fillable = ['name', 'email'];
+}
+
+// CORRECT: Use Form Request validated data
+$user = User::create($request->validated());
+```
+
+### Environment Variables
+
+```php
+// WRONG: env() outside config files (null when cached)
+$apiKey = env('API_KEY');
 
-- [ ] All SQL uses prepared statements
-- [ ] All output is escaped (htmlspecialchars)
-- [ ] CSRF tokens on all forms
-- [ ] Passwords use password_hash/verify
-- [ ] File uploads validated (type, size, extension)
-- [ ] Sessions use httpOnly + secure cookies
-- [ ] Input validated before processing
-- [ ] No `eval()`, `exec()` with user input
-- [ ] No `extract()` on user data
-- [ ] Headers: X-Content-Type-Options, X-Frame-Options, CSP
+// CORRECT: Use config files
+// config/services.php
+'stripe' => ['key' => env('STRIPE_KEY')],
+
+// In code:
+$apiKey = config('services.stripe.key');
+```
+
+### CSRF & Authentication
+
+```php
+// Blade forms — CSRF automatic
+<form method="POST">
+    @csrf
+    ...
+</form>
+
+// API routes — use Sanctum middleware
+Route::middleware('auth:sanctum')->group(function () {
+    Route::apiResource('users', UserController::class);
+});
+```
+
+### File Upload Validation
+
+```php
+public function rules(): array
+{
+    return [
+        'avatar' => [
+            'required',
+            'image',
+            'mimes:jpg,jpeg,png,webp',
+            'max:2048', // 2MB
+            'dimensions:max_width=2000,max_height=2000',
+        ],
+    ];
+}
+```
+
+## Octane Security Considerations
+
+```php
+// WRONG: Static state leaks user data between requests
+class AuthService {
+    private static ?User $currentUser = null; // LEAKS!
+}
+
+// WRONG: Superglobals are stale in Octane
+$token = $_SERVER['HTTP_AUTHORIZATION'];
+
+// CORRECT: Use Request object
+$token = $request->bearerToken();
+$user = $request->user();
+```
+
+## Security Checklist
 
-## Sensitive Data Patterns (FORBIDDEN)
+- [ ] All queries use Eloquent or Query Builder (no raw SQL with user input)
+- [ ] All Blade output uses `{{ }}` (auto-escaped)
+- [ ] CSRF protection on all forms (`@csrf`)
+- [ ] Passwords use `Hash::make()` / `Hash::check()`
+- [ ] File uploads validated (type, size, dimensions)
+- [ ] API routes protected with Sanctum middleware
+- [ ] Models define `$fillable` (no `$guarded = []`)
+- [ ] Queries scoped by authenticated user (unless admin)
+- [ ] No `env()` calls outside config files
+- [ ] No static state in services (Octane-safe)
+- [ ] No superglobals (`$_GET`, `$_POST`, `$_SESSION`)
+- [ ] Sensitive headers set (X-Content-Type-Options, X-Frame-Options, CSP)
+- [ ] Rate limiting on authentication endpoints
+
+## Sensitive Patterns (FORBIDDEN)
 
 | Pattern | Risk |
 |---------|------|
-| `$_GET` used directly in SQL | SQL Injection |
-| `echo $_POST[...]` | XSS |
+| `DB::raw()` with user input | SQL Injection |
+| `{!! $userInput !!}` | XSS |
 | `md5()` / `sha1()` for passwords | Weak hashing |
-| `eval($userInput)` | RCE |
-| `include $_GET['page']` | LFI/RFI |
-| `serialize()` user data | Object injection |
+| Dynamic code execution | RCE |
+| `unserialize()` on user data | Object injection |
+| `$request->all()` without `$fillable` | Mass assignment |
+| `env()` in runtime code | Null after config cache |
+| Static user state in services | Data leaks in Octane |

package/stacks/php/stack.json

@@ -27,13 +27,20 @@
       "name": "Laravel 12 + Octane (RoadRunner) + Inertia.js",
       "icon": "🚀",
       "detectFiles": ["artisan", "rr.yaml"],
-      "default": true
+      "default": true,
+      "skills": [
+        "laravel-patterns",
+        "laravel-octane"
+      ]
     },
     {
       "id": "laravel",
       "name": "Laravel 12 (standard)",
       "icon": "🏗️",
-      "detectFiles": ["artisan", "bootstrap/app.php"]
+      "detectFiles": ["artisan", "bootstrap/app.php"],
+      "skills": [
+        "laravel-patterns"
+      ]
     }
   ],
   "databases": [
@@ -46,12 +53,20 @@
       "id": "react-inertia",
       "name": "ReactJS 19 + Inertia.js + TailwindCSS 4",
       "icon": "⚛️",
-      "default": true
+      "default": true,
+      "frameworks": ["laravel", "laravel-octane"]
     },
     {
       "id": "blade",
       "name": "Blade + TailwindCSS 4",
-      "icon": "🖼️"
+      "icon": "🖼️",
+      "frameworks": ["laravel", "laravel-octane"]
+    },
+    {
+      "id": "livewire",
+      "name": "Livewire + Alpine.js",
+      "icon": "⚡",
+      "frameworks": ["laravel", "laravel-octane"]
     },
     {
       "id": "none",
@@ -68,8 +83,6 @@
     "phpstan-analysis",
     "composer-workflow",
     "security-scan-php",
-    "laravel-patterns",
-    "laravel-octane",
     "api-design"
   ],
   "requirements": [

package/templates/CLAUDE-nodejs.md

@@ -0,0 +1,323 @@
+# {{PROJECT_NAME}}
+
+> **CHARACTER LIMIT**: Max 40,000 chars. Validate with `wc -m CLAUDE.md` before commit.
+
+## Last Change
+
+**Branch:** main
+**Date:** {{DATE}}
+**Summary:** Initial project setup with start-vibing-stacks (Node.js)
+
+## 30 Seconds Overview
+
+{{PROJECT_NAME}} is a TypeScript project using {{FRAMEWORK}}.
+
+## Stack
+
+| Component | Technology |
+|-----------|------------|
+| Runtime | Bun / Node.js 20+ |
+| Language | TypeScript **strict mode** |
+| Framework | {{FRAMEWORK}} |
+| Database | {{DATABASE}} |
+| Validation | Zod |
+| Testing | Vitest + Playwright |
+| UI | React + Tailwind + shadcn |
+| Data | TanStack Query + Sonner |
+| Forms | react-hook-form + Zod |
+
+## Architecture
+
+```
+project/
+├── CLAUDE.md               # This file (40k char max)
+├── .claude/
+│   ├── agents/             # 6 active subagents
+│   ├── skills/             # Skill systems (auto-injected)
+│   ├── hooks/              # Validation hooks
+│   ├── config/             # Project configuration
+│   └── commands/           # Slash commands (/feature, /fix, /research, /validate)
+├── src/
+│   ├── app/                # Next.js App Router pages
+│   │   ├── (marketing)/    # Route group — public pages
+│   │   ├── (app)/          # Route group — authenticated
+│   │   │   └── dashboard/
+│   │   │       ├── page.tsx
+│   │   │       └── _components/  # Page-specific components
+│   │   ├── api/            # Route handlers (API endpoints)
+│   │   ├── layout.tsx      # Root layout with providers
+│   │   └── loading.tsx     # Global loading skeleton
+│   ├── components/
+│   │   ├── ui/             # shadcn primitives (Button, Input)
+│   │   ├── layout/         # Header, Sidebar, Footer
+│   │   ├── shared/         # Cross-feature components
+│   │   └── providers.tsx   # Context providers (client)
+│   ├── lib/
+│   │   ├── utils.ts        # cn utility (clsx + tailwind-merge)
+│   │   ├── api/            # API client instances
+│   │   └── validations/    # Zod schemas
+│   ├── hooks/              # Custom React hooks
+│   └── styles/             # Global styles, theme tokens
+├── types/                  # ALL TypeScript interfaces (MANDATORY)
+├── tests/
+│   ├── unit/               # Vitest unit tests
+│   └── e2e/                # Playwright E2E tests
+├── public/                 # Static assets
+├── tsconfig.json           # TypeScript config (strict: true)
+├── next.config.ts          # Framework config
+├── tailwind.config.ts      # TailwindCSS config
+├── vitest.config.ts        # Test config
+└── package.json            # Dependencies
+```
+
+## Workflow
+
+```
+0. TODO LIST      → Create detailed todo list from prompt
+1. BRANCH         → Create feature/ | fix/ | refactor/ | test/
+2. RESEARCH       → Run research-web agent for NEW features
+3. IMPLEMENT      → Follow project rules + strict types
+4. TEST           → Run tester agent (Vitest / Playwright)
+5. DOCUMENT       → Run documenter agent for modified files
+6. UPDATE         → Update THIS FILE (CLAUDE.md) with changes
+7. QUALITY        → bun run typecheck && lint && test
+8. COMMIT         → Conventional commits, merge to main
+```
+
+## CLAUDE.md Update Rules
+
+> After ANY implementation, update this file to reflect the current state.
+
+| Change Type | Sections to Update |
+|-------------|-------------------|
+| Any file change | Last Change (branch, date, summary) |
+| API/routes | Critical Rules, Architecture |
+| UI components | Architecture, Component Organization |
+| New feature | 30s Overview, Architecture |
+| New gotcha | FORBIDDEN or NRY |
+| New dependency | Stack |
+| Workflow change | Workflow section |
+
+1. **Last Change** documents WHAT was done
+2. **Other sections** document HOW things work NOW
+3. **Both must be current** — updating only Last Change is insufficient
+4. Keep only the LATEST Last Change entry (no stacking)
+
+## Agent System
+
+### Subagents (6)
+
+| Agent | Purpose |
+|-------|---------|
+| **research-web** | Researches best practices before new features |
+| **documenter** | Maps files to domains, creates/updates domain docs |
+| **domain-updater** | Records problems, solutions, learnings |
+| **commit-manager** | Manages git commits, conventional format |
+| **claude-md-compactor** | Compacts CLAUDE.md when > 40k chars |
+| **tester** | Creates tests with Vitest/Playwright |
+
+### Skills
+
+| Category | Skills |
+|----------|--------|
+| **Development** | typescript-strict, react-patterns, nextjs-app-router, zod-validation, shadcn-ui, tailwind-patterns |
+| **Quality** | quality-gate, security-scan, test-coverage, final-check |
+| **Infrastructure** | docker-patterns, git-workflow, performance-patterns, debugging-patterns |
+| **Documentation** | codebase-knowledge, docs-tracker, research-cache, ui-ux-audit |
+
+## Critical Rules
+
+- **TypeScript strict mode** — `strict: true` in tsconfig.json
+- **Bracket notation** for env vars: `process.env['VARIABLE']`
+- **Zod validation** for ALL external input (forms, API, env)
+- **Server Components by default** — push `'use client'` to leaf components
+- **Parallel data fetching** — `Promise.all()` over waterfall
+- **Type everything** — no `any`, use `unknown` for truly unknown data
+- **Loading states** — every data page must have `loading.tsx`
+- **Error boundaries** — every route should handle errors gracefully
+- **Conventional commits** — `feat:`, `fix:`, `refactor:`, `docs:`, `chore:`
+
+### Environment Variables Security (MANDATORY)
+
+> **NEVER expose secrets to the browser.** `NEXT_PUBLIC_*` vars are embedded in the JS bundle and visible to anyone.
+
+| Prefix | Where it runs | Safe for |
+|--------|--------------|----------|
+| `NEXT_PUBLIC_*` | Browser + Server | Public URLs, analytics IDs, Stripe **publishable** key (`pk_`) |
+| No prefix | Server ONLY | API keys, secrets, tokens, database URLs, private keys |
+
+```typescript
+// .env.local
+OPENAI_KEY=sk-abc123                    // Server only — SAFE
+STRIPE_SECRET_KEY=sk_live_abc           // Server only — SAFE
+NEXT_PUBLIC_APP_URL=https://myapp.com   // Public — OK (no secret)
+NEXT_PUBLIC_STRIPE_KEY=pk_live_abc      // Public — OK (publishable key)
+
+// NEXT_PUBLIC_OPENAI_KEY=sk-abc123     // FORBIDDEN — exposed in browser bundle!
+```
+
+### API Proxy Pattern (MANDATORY for external APIs)
+
+> **ALL calls to external APIs with secrets MUST go through server-side Route Handlers or Server Actions. NEVER call external APIs directly from client components.**
+
+```typescript
+// app/api/chat/route.ts — Server-side proxy (token NEVER leaves server)
+import { NextRequest, NextResponse } from 'next/server';
+
+export async function POST(req: NextRequest) {
+  const { message } = await req.json();
+  const response = await fetch('https://api.openai.com/v1/chat/completions', {
+    headers: { Authorization: `Bearer ${process.env['OPENAI_KEY']}` },
+    method: 'POST',
+    body: JSON.stringify({ model: 'gpt-4', messages: [{ role: 'user', content: message }] }),
+  });
+  return NextResponse.json(await response.json());
+}
+
+// components/chat.tsx — Client calls YOUR API, not the external one
+'use client';
+const response = await fetch('/api/chat', {
+  method: 'POST',
+  body: JSON.stringify({ message }),
+});
+```
+
+### Types Location
+
+- **ALL** interfaces/types MUST be in `types/` folder
+- **NEVER** define types in `src/` files
+- **EXCEPTION:** Zod inferred types (`z.infer<typeof Schema>`)
+
+### TypeScript Strict
+
+```typescript
+process.env['VARIABLE'];    // CORRECT (bracket notation)
+source: 'listed' as const;  // CORRECT (literal type)
+```
+
+### Component Organization
+
+| Question | Location |
+|----------|----------|
+| Used in ONE page only? | `app/[page]/_components/` |
+| Used across 2+ features? | `components/shared/` |
+| UI primitive (Button, Input)? | `components/ui/` |
+| Layout element (Header)? | `components/layout/` |
+
+| Lines | Action |
+|-------|--------|
+| < 200 | Keep in single file |
+| 200-400 | Consider splitting |
+| > 400 | **MUST split** into smaller components |
+
+## FORBIDDEN
+
+### Security (CRITICAL)
+
+| Action | Reason |
+|--------|--------|
+| `NEXT_PUBLIC_` with API keys/secrets/tokens | Exposes credentials in browser JS bundle — use server-side proxy |
+| Call external APIs from client components | Leaks tokens — route through `app/api/` Route Handlers |
+| `process.env['SECRET']` in `'use client'` files | Only `NEXT_PUBLIC_*` vars reach the browser — use Server Actions |
+| Hardcode API keys in source code | Use `.env.local` + server-side access only |
+| Commit `.env.local` / `.env` to git | Add to `.gitignore` — use `.env.example` with empty values |
+
+### Code Quality
+
+| Action | Reason |
+|--------|--------|
+| `any` type | Defeats strict mode — use `unknown` |
+| Skip typecheck | TypeScript errors become runtime bugs |
+| Relative imports (shared) | Breaks when files move — use `@/` alias |
+| Define types in `src/` | Must be in `types/` folder |
+| `'use client'` at top-level layouts | Breaks server rendering, push to leaves |
+| Waterfall data fetching | Use `Promise.all()` for parallel |
+| Skip `loading.tsx` on data pages | Flash of empty content |
+| Files > 400 lines | MUST split into smaller components |
+| Wildcard icon imports | Use named: `import { X } from 'lucide-react'` |
+| `var` keyword | Use `const` or `let` |
+| Raw `console.log` in production | Use structured logging |
+
+### Workflow
+
+| Action | Reason |
+|--------|--------|
+| Commit directly to main | Create feature/fix branches |
+| Skip research for new features | Leads to outdated patterns |
+| Skip todo list creation | Loses track of tasks |
+| Skip documenter agent | Documentation is mandatory |
+| Skip domain documentation | MUST update domains/*.md |
+| Stack Last Change entries | Keep only the LATEST |
+| Use MUI/Chakra | Use shadcn/ui + Radix |
+| Skip CLAUDE.md update | MUST update after implementations |
+
+## UI Architecture
+
+> Web apps MUST have **separate UIs** for each platform, NOT just "responsive design".
+
+| Platform | Layout |
+|----------|--------|
+| Mobile (375px) | Full-screen modals, bottom nav, touch-first |
+| Tablet (768px) | Condensed dropdowns, hybrid nav |
+| Desktop (1280px+) | Sidebar left, top navbar with search |
+
+## Quality Gates
+
+```bash
+bun run typecheck   # MUST pass
+bun run lint        # MUST pass
+bun run test        # MUST pass
+bun run build       # MUST pass
+```
+
+## Domain Documentation
+
+> Domain docs prevent Claude from re-exploring the codebase every session.
+
+```
+.claude/skills/codebase-knowledge/domains/
+├── authentication.md
+├── api.md
+├── database.md
+├── ui-components.md
+└── [domain-name].md
+```
+
+Each domain file tracks: Files, Connections, Recent Commits, Attention Points, Problems & Solutions.
+
+## Commit Format
+
+```
+[type]: [description]
+
+- Detail 1
+- Detail 2
+
+Generated with Claude Code
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+Types: `feat`, `fix`, `refactor`, `docs`, `chore`
+
+## NRY (Never Repeat Yourself)
+
+- Multi-line bash with `\` continuations (breaks permissions)
+- Relative paths in permission patterns
+- Using bash for file operations (use Read/Write/Edit tools)
+- Ignoring context size (use `/compact`)
+
+## Configuration
+
+Project settings in `.claude/config/`:
+
+- `active-project.json` — Stack, framework, database, skills
+- `domain-mapping.json` — File-to-domain mapping
+- `quality-gates.json` — Quality check commands
+- `testing-config.json` — Test framework config
+- `security-rules.json` — Security audit rules
+- `standards-review.json` — Imported project standards
+
+## Setup by start-vibing-stacks
+
+This project was set up with `npx start-vibing-stacks`.
+For updates: `npx start-vibing-stacks --force`