thachvd-kit 1.0.13 → 1.0.15

package/.agent/skills/laravel-security/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: laravel-security
+description: Laravel security best practices. Use when adding authentication or authorization, handling user input and file uploads, building new API endpoints, managing secrets, or hardening production deployments.
+allowed-tools: Read, Edit, Grep
+---
+
+# Laravel Security Best Practices
+
+## Core Security Settings
+
+- `APP_DEBUG=false` in production
+- `APP_KEY` must be set and rotated on compromise
+- `SESSION_SECURE_COOKIE=true` and `SESSION_SAME_SITE=lax` (or `strict` for sensitive apps)
+- Configure trusted proxies for correct HTTPS detection
+
+## Authentication and Tokens (Sanctum)
+
+```php
+Route::middleware('auth:sanctum')->get('/me', function (Request $request) {
+    return $request->user();
+});
+```
+
+- Use short-lived tokens with refresh flows for sensitive data
+- Revoke tokens on logout and compromised accounts
+
+## Password Security
+
+```php
+$validated = $request->validate([
+    'password' => ['required', 'string', Password::min(12)->letters()->mixedCase()->numbers()->symbols()],
+]);
+
+$user->update(['password' => Hash::make($validated['password'])]);
+```
+
+## Authorization: Policies and Gates
+
+```php
+// In controller
+$this->authorize('update', $project);
+
+// Route-level enforcement
+Route::put('/projects/{project}', [ProjectController::class, 'update'])
+    ->middleware(['auth:sanctum', 'can:update,project']);
+```
+
+## Rate Limiting
+
+```php
+RateLimiter::for('login', function (Request $request) {
+    return [
+        Limit::perMinute(5)->by($request->ip()),
+        Limit::perMinute(5)->by(strtolower((string) $request->input('email'))),
+    ];
+});
+```
+
+## File Upload Safety
+
+```php
+final class UploadInvoiceRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return (bool) $this->user()?->can('upload-invoice');
+    }
+
+    public function rules(): array
+    {
+        return [
+            'invoice' => ['required', 'file', 'mimes:pdf', 'max:5120'],
+        ];
+    }
+}
+
+// Store outside public path
+$path = $request->file('invoice')->store('invoices', 'local');
+```
+
+## Mass Assignment Protection
+
+- Use `$fillable` or `$guarded` — avoid `Model::unguard()`
+- Prefer DTOs or explicit attribute mapping
+
+## SQL Injection Prevention
+
+- Use Eloquent or query builder parameter binding
+- Avoid raw SQL unless strictly necessary
+
+```php
+DB::select('select * from users where email = ?', [$email]);
+```
+
+## XSS Prevention
+
+- Blade escapes output by default (`{{ }}`)
+- Use `{!! !!}` only for trusted, sanitized HTML
+
+## CSRF Protection
+
+- Keep `VerifyCsrfToken` middleware enabled
+- Include `@csrf` in forms
+- For SPA + Sanctum: configure stateful domains
+
+```php
+// config/sanctum.php
+'stateful' => explode(',', env('SANCTUM_STATEFUL_DOMAINS', 'localhost')),
+```
+
+## Encrypted Attributes
+
+```php
+protected $casts = [
+    'api_token' => 'encrypted',
+];
+```
+
+## Security Headers Middleware
+
+```php
+final class SecurityHeaders
+{
+    public function handle(Request $request, \Closure $next): Response
+    {
+        $response = $next($request);
+        $response->headers->add([
+            'Content-Security-Policy' => "default-src 'self'",
+            'Strict-Transport-Security' => 'max-age=31536000',
+            'X-Frame-Options' => 'DENY',
+            'X-Content-Type-Options' => 'nosniff',
+            'Referrer-Policy' => 'no-referrer',
+        ]);
+        return $response;
+    }
+}
+```
+
+## CORS Configuration
+
+```php
+// config/cors.php
+return [
+    'paths' => ['api/*', 'sanctum/csrf-cookie'],
+    'allowed_origins' => ['https://app.example.com'],  // Never wildcard for auth routes
+    'supports_credentials' => true,
+];
+```
+
+## Logging and PII
+
+```php
+// Never log passwords, tokens, card data
+Log::info('User updated profile', [
+    'user_id' => $user->id,
+    'email' => '[REDACTED]',
+]);
+```
+
+## Signed URLs
+
+```php
+$url = URL::temporarySignedRoute('downloads.invoice', now()->addMinutes(15), ['invoice' => $invoice->id]);
+```
+
+## Secrets Management
+
+- Never commit secrets to source control
+- Use environment variables and secret managers (AWS SSM, Vault)
+- Rotate keys after exposure and invalidate sessions
+- Run `composer audit` regularly for dependency vulnerabilities

package/.agent/skills/laravel-tdd/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: laravel-tdd
+description: Laravel TDD workflow with PHPUnit and Pest. Use when writing tests for Laravel applications, implementing red-green-refactor cycle, testing HTTP endpoints, auth, queues, events, or setting up test configuration.
+allowed-tools: Bash, Read, Edit, Write
+---
+
+# Laravel TDD Workflow
+
+## Red-Green-Refactor Cycle
+
+1. Write a failing test (RED)
+2. Implement the minimal change to pass (GREEN)
+3. Refactor while keeping tests green (REFACTOR)
+
+## Test Layers
+
+| Layer | Use For |
+|-------|---------|
+| **Unit** | Pure PHP classes, value objects, services |
+| **Feature** | HTTP endpoints, auth, validation, policies |
+| **Integration** | DB + queue + external boundaries together |
+
+## Database Strategy
+
+- **`RefreshDatabase`** — Default for tests touching the DB. Runs migrations once per run, wraps each test in a transaction.
+- **`DatabaseTransactions`** — When schema is already migrated, only need per-test rollback.
+- **`DatabaseMigrations`** — When you need full migrate/fresh for every test.
+
+## Testing Framework
+
+- Default to **Pest** for new tests when available
+- Use **PHPUnit** if project has standardized on it
+
+## PHPUnit Example
+
+```php
+use App\Models\User;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Tests\TestCase;
+
+final class ProjectControllerTest extends TestCase
+{
+    use RefreshDatabase;
+
+    public function test_owner_can_create_project(): void
+    {
+        $user = User::factory()->create();
+
+        $response = $this->actingAs($user)->postJson('/api/projects', [
+            'name' => 'New Project',
+        ]);
+
+        $response->assertCreated();
+        $this->assertDatabaseHas('projects', ['name' => 'New Project']);
+    }
+}
+```
+
+## Pest Example
+
+```php
+use App\Models\User;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+
+uses(RefreshDatabase::class);
+
+test('owner can create project', function () {
+    $user = User::factory()->create();
+
+    $response = actingAs($user)->postJson('/api/projects', [
+        'name' => 'New Project',
+    ]);
+
+    $response->assertCreated();
+    assertDatabaseHas('projects', ['name' => 'New Project']);
+});
+```
+
+## Factories and States
+
+```php
+$user = User::factory()->state(['role' => 'admin'])->create();
+
+// Factory sequences
+User::factory()->count(3)->for($project)->create();
+```
+
+## Fakes for Side Effects
+
+```php
+Queue::fake();
+dispatch(new SendOrderConfirmation($order->id));
+Queue::assertPushed(SendOrderConfirmation::class);
+
+Mail::fake();
+Notification::fake();
+Event::fake();
+```
+
+## Auth Testing (Sanctum)
+
+```php
+use Laravel\Sanctum\Sanctum;
+
+Sanctum::actingAs($user);
+
+$response = $this->getJson('/api/projects');
+$response->assertOk();
+```
+
+## HTTP and External Services
+
+```php
+// Isolate external APIs
+Http::fake(['api.stripe.com/*' => Http::response(['id' => 'evt_123'], 200)]);
+Http::assertSent(fn ($request) => $request->url() === 'https://api.stripe.com/...');
+```
+
+## Authorization Tests
+
+```php
+$this->assertTrue(Gate::forUser($user)->allows('update', $project));
+$this->assertFalse(Gate::forUser($otherUser)->allows('update', $project));
+```
+
+## Coverage Targets
+
+- Enforce 80%+ coverage for unit + feature tests
+- Use `pcov` or `XDEBUG_MODE=coverage` in CI
+
+## Test Commands
+
+```bash
+php artisan test
+php artisan test --parallel        # Parallel execution
+vendor/bin/pest
+vendor/bin/phpunit
+```
+
+## Test Configuration (phpunit.xml)
+
+```xml
+<php>
+    <env name="DB_CONNECTION" value="sqlite"/>
+    <env name="DB_DATABASE" value=":memory:"/>
+    <env name="CACHE_DRIVER" value="array"/>
+    <env name="QUEUE_CONNECTION" value="sync"/>
+</php>
+```

package/.agent/skills/lint-and-validate/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: lint-and-validate
+description: Automatic quality control, linting, and static analysis procedures. Use after every code modification to ensure syntax correctness and project standards. Triggers onKeywords: lint, format, check, validate, types, static analysis.
+allowed-tools: Read, Glob, Grep, Bash
+---
+
+# Lint and Validate Skill
+
+> **MANDATORY:** Run appropriate validation tools after EVERY code change. Do not finish a task until the code is error-free.
+
+### Procedures by Ecosystem
+
+#### Node.js / TypeScript
+1. **Lint/Fix:** `npm run lint` or `npx eslint "path" --fix`
+2. **Types:** `npx tsc --noEmit`
+3. **Security:** `npm audit --audit-level=high`
+
+#### Python
+1. **Linter (Ruff):** `ruff check "path" --fix` (Fast & Modern)
+2. **Security (Bandit):** `bandit -r "path" -ll`
+3. **Types (MyPy):** `mypy "path"`
+
+## The Quality Loop
+1. **Write/Edit Code**
+2. **Run Audit:** `npm run lint && npx tsc --noEmit`
+3. **Analyze Report:** Check the "FINAL AUDIT REPORT" section.
+4. **Fix & Repeat:** Submitting code with "FINAL AUDIT" failures is NOT allowed.
+
+## Error Handling
+- If `lint` fails: Fix the style or syntax issues immediately.
+- If `tsc` fails: Correct type mismatches before proceeding.
+- If no tool is configured: Check the project root for `.eslintrc`, `tsconfig.json`, `pyproject.toml` and suggest creating one.
+
+---
+**Strict Rule:** No code should be committed or reported as "done" without passing these checks.
+
+---
+
+## Scripts
+
+| Script | Purpose | Command |
+|--------|---------|---------|
+| `scripts/lint_runner.py` | Unified lint check | `python scripts/lint_runner.py <project_path>` |
+| `scripts/type_coverage.py` | Type coverage analysis | `python scripts/type_coverage.py <project_path>` |
+

package/.agent/skills/lint-and-validate/scripts/lint_runner.py

@@ -0,0 +1,184 @@
+#!/usr/bin/env python3
+"""
+Lint Runner - Unified linting and type checking
+Runs appropriate linters based on project type.
+
+Usage:
+    python lint_runner.py <project_path>
+
+Supports:
+    - Node.js: npm run lint, npx tsc --noEmit
+    - Python: ruff check, mypy
+"""
+
+import subprocess
+import sys
+import json
+import platform
+import shutil
+from pathlib import Path
+from datetime import datetime
+
+# Fix Windows console encoding
+try:
+    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+except:
+    pass
+
+
+def detect_project_type(project_path: Path) -> dict:
+    """Detect project type and available linters."""
+    result = {
+        "type": "unknown",
+        "linters": []
+    }
+    
+    # Node.js project
+    package_json = project_path / "package.json"
+    if package_json.exists():
+        result["type"] = "node"
+        try:
+            pkg = json.loads(package_json.read_text(encoding='utf-8'))
+            scripts = pkg.get("scripts", {})
+            deps = {**pkg.get("dependencies", {}), **pkg.get("devDependencies", {})}
+            
+            # Check for lint script
+            if "lint" in scripts:
+                result["linters"].append({"name": "npm lint", "cmd": ["npm", "run", "lint"]})
+            elif "eslint" in deps:
+                result["linters"].append({"name": "eslint", "cmd": ["npx", "eslint", "."]})
+            
+            # Check for TypeScript
+            if "typescript" in deps or (project_path / "tsconfig.json").exists():
+                result["linters"].append({"name": "tsc", "cmd": ["npx", "tsc", "--noEmit"]})
+                
+        except:
+            pass
+    
+    # Python project
+    if (project_path / "pyproject.toml").exists() or (project_path / "requirements.txt").exists():
+        result["type"] = "python"
+        
+        # Check for ruff
+        result["linters"].append({"name": "ruff", "cmd": ["ruff", "check", "."]})
+        
+        # Check for mypy
+        if (project_path / "mypy.ini").exists() or (project_path / "pyproject.toml").exists():
+            result["linters"].append({"name": "mypy", "cmd": ["mypy", "."]})
+    
+    return result
+
+
+def run_linter(linter: dict, cwd: Path) -> dict:
+    """Run a single linter and return results."""
+    result = {
+        "name": linter["name"],
+        "passed": False,
+        "output": "",
+        "error": ""
+    }
+    
+    try:
+        cmd = linter["cmd"]
+        
+        # Windows compatibility for npm/npx
+        if platform.system() == "Windows":
+            if cmd[0] in ["npm", "npx"]:
+                # Force .cmd extension on Windows
+                if not cmd[0].lower().endswith(".cmd"):
+                    cmd[0] = f"{cmd[0]}.cmd"
+        
+        proc = subprocess.run(
+            cmd,
+            cwd=str(cwd),
+            capture_output=True,
+            text=True,
+            encoding='utf-8',
+            errors='replace',
+            timeout=120,
+            shell=platform.system() == "Windows" # Shell=True often helps with path resolution on Windows
+        )
+        
+        result["output"] = proc.stdout[:2000] if proc.stdout else ""
+        result["error"] = proc.stderr[:500] if proc.stderr else ""
+        result["passed"] = proc.returncode == 0
+        
+    except FileNotFoundError:
+        result["error"] = f"Command not found: {linter['cmd'][0]}"
+    except subprocess.TimeoutExpired:
+        result["error"] = "Timeout after 120s"
+    except Exception as e:
+        result["error"] = str(e)
+    
+    return result
+
+
+def main():
+    project_path = Path(sys.argv[1] if len(sys.argv) > 1 else ".").resolve()
+    
+    print(f"\n{'='*60}")
+    print(f"[LINT RUNNER] Unified Linting")
+    print(f"{'='*60}")
+    print(f"Project: {project_path}")
+    print(f"Time: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+    
+    # Detect project type
+    project_info = detect_project_type(project_path)
+    print(f"Type: {project_info['type']}")
+    print(f"Linters: {len(project_info['linters'])}")
+    print("-"*60)
+    
+    if not project_info["linters"]:
+        print("No linters found for this project type.")
+        output = {
+            "script": "lint_runner",
+            "project": str(project_path),
+            "type": project_info["type"],
+            "checks": [],
+            "passed": True,
+            "message": "No linters configured"
+        }
+        print(json.dumps(output, indent=2))
+        sys.exit(0)
+    
+    # Run each linter
+    results = []
+    all_passed = True
+    
+    for linter in project_info["linters"]:
+        print(f"\nRunning: {linter['name']}...")
+        result = run_linter(linter, project_path)
+        results.append(result)
+        
+        if result["passed"]:
+            print(f"  [PASS] {linter['name']}")
+        else:
+            print(f"  [FAIL] {linter['name']}")
+            if result["error"]:
+                print(f"  Error: {result['error'][:200]}")
+            all_passed = False
+    
+    # Summary
+    print("\n" + "="*60)
+    print("SUMMARY")
+    print("="*60)
+    
+    for r in results:
+        icon = "[PASS]" if r["passed"] else "[FAIL]"
+        print(f"{icon} {r['name']}")
+    
+    output = {
+        "script": "lint_runner",
+        "project": str(project_path),
+        "type": project_info["type"],
+        "checks": results,
+        "passed": all_passed
+    }
+    
+    print("\n" + json.dumps(output, indent=2))
+    
+    sys.exit(0 if all_passed else 1)
+
+
+if __name__ == "__main__":
+    main()