@h1dr0n/skill-pool 0.1.0

package/skills/api/skills/api-patterns/scripts/api_validator.py

@@ -0,0 +1,211 @@
+#!/usr/bin/env python3
+"""
+API Validator - Checks API endpoints for best practices.
+Validates OpenAPI specs, response formats, and common issues.
+"""
+import sys
+import json
+import re
+from pathlib import Path
+
+# Fix Windows console encoding for Unicode output
+try:
+    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+    sys.stderr.reconfigure(encoding='utf-8', errors='replace')
+except AttributeError:
+    pass  # Python < 3.7
+
+def find_api_files(project_path: Path) -> list:
+    """Find API-related files."""
+    patterns = [
+        "**/*api*.ts", "**/*api*.js", "**/*api*.py",
+        "**/routes/*.ts", "**/routes/*.js", "**/routes/*.py",
+        "**/controllers/*.ts", "**/controllers/*.js",
+        "**/endpoints/*.ts", "**/endpoints/*.py",
+        "**/*.openapi.json", "**/*.openapi.yaml",
+        "**/swagger.json", "**/swagger.yaml",
+        "**/openapi.json", "**/openapi.yaml"
+    ]
+    
+    files = []
+    for pattern in patterns:
+        files.extend(project_path.glob(pattern))
+    
+    # Exclude node_modules, etc.
+    return [f for f in files if not any(x in str(f) for x in ['node_modules', '.git', 'dist', 'build', '__pycache__'])]
+
+def check_openapi_spec(file_path: Path) -> dict:
+    """Check OpenAPI/Swagger specification."""
+    issues = []
+    passed = []
+    
+    try:
+        content = file_path.read_text(encoding='utf-8')
+        
+        if file_path.suffix == '.json':
+            spec = json.loads(content)
+        else:
+            # Basic YAML check
+            if 'openapi:' in content or 'swagger:' in content:
+                passed.append("[OK] OpenAPI/Swagger version defined")
+            else:
+                issues.append("[X] No OpenAPI version found")
+            
+            if 'paths:' in content:
+                passed.append("[OK] Paths section exists")
+            else:
+                issues.append("[X] No paths defined")
+            
+            if 'components:' in content or 'definitions:' in content:
+                passed.append("[OK] Schema components defined")
+            
+            return {'file': str(file_path), 'passed': passed, 'issues': issues, 'type': 'openapi'}
+        
+        # JSON OpenAPI checks
+        if 'openapi' in spec or 'swagger' in spec:
+            passed.append("[OK] OpenAPI version defined")
+        
+        if 'info' in spec:
+            if 'title' in spec['info']:
+                passed.append("[OK] API title defined")
+            if 'version' in spec['info']:
+                passed.append("[OK] API version defined")
+            if 'description' not in spec['info']:
+                issues.append("[!] API description missing")
+        
+        if 'paths' in spec:
+            path_count = len(spec['paths'])
+            passed.append(f"[OK] {path_count} endpoints defined")
+            
+            # Check each path
+            for path, methods in spec['paths'].items():
+                for method, details in methods.items():
+                    if method in ['get', 'post', 'put', 'patch', 'delete']:
+                        if 'responses' not in details:
+                            issues.append(f"[X] {method.upper()} {path}: No responses defined")
+                        if 'summary' not in details and 'description' not in details:
+                            issues.append(f"[!] {method.upper()} {path}: No description")
+        
+    except Exception as e:
+        issues.append(f"[X] Parse error: {e}")
+    
+    return {'file': str(file_path), 'passed': passed, 'issues': issues, 'type': 'openapi'}
+
+def check_api_code(file_path: Path) -> dict:
+    """Check API code for common issues."""
+    issues = []
+    passed = []
+    
+    try:
+        content = file_path.read_text(encoding='utf-8')
+        
+        # Check for error handling
+        error_patterns = [
+            r'try\s*{', r'try:', r'\.catch\(',
+            r'except\s+', r'catch\s*\('
+        ]
+        has_error_handling = any(re.search(p, content) for p in error_patterns)
+        if has_error_handling:
+            passed.append("[OK] Error handling present")
+        else:
+            issues.append("[X] No error handling found")
+        
+        # Check for status codes
+        status_patterns = [
+            r'status\s*\(\s*\d{3}\s*\)', r'statusCode\s*[=:]\s*\d{3}',
+            r'HttpStatus\.', r'status_code\s*=\s*\d{3}',
+            r'\.status\(\d{3}\)', r'res\.status\('
+        ]
+        has_status = any(re.search(p, content) for p in status_patterns)
+        if has_status:
+            passed.append("[OK] HTTP status codes used")
+        else:
+            issues.append("[!] No explicit HTTP status codes")
+        
+        # Check for validation
+        validation_patterns = [
+            r'validate', r'schema', r'zod', r'joi', r'yup',
+            r'pydantic', r'@Body\(', r'@Query\('
+        ]
+        has_validation = any(re.search(p, content, re.I) for p in validation_patterns)
+        if has_validation:
+            passed.append("[OK] Input validation present")
+        else:
+            issues.append("[!] No input validation detected")
+        
+        # Check for auth middleware
+        auth_patterns = [
+            r'auth', r'jwt', r'bearer', r'token',
+            r'middleware', r'guard', r'@Authenticated'
+        ]
+        has_auth = any(re.search(p, content, re.I) for p in auth_patterns)
+        if has_auth:
+            passed.append("[OK] Authentication/authorization detected")
+        
+        # Check for rate limiting
+        rate_patterns = [r'rateLimit', r'throttle', r'rate.?limit']
+        has_rate = any(re.search(p, content, re.I) for p in rate_patterns)
+        if has_rate:
+            passed.append("[OK] Rate limiting present")
+        
+        # Check for logging
+        log_patterns = [r'console\.log', r'logger\.', r'logging\.', r'log\.']
+        has_logging = any(re.search(p, content) for p in log_patterns)
+        if has_logging:
+            passed.append("[OK] Logging present")
+        
+    except Exception as e:
+        issues.append(f"[X] Read error: {e}")
+    
+    return {'file': str(file_path), 'passed': passed, 'issues': issues, 'type': 'code'}
+
+def main():
+    target = sys.argv[1] if len(sys.argv) > 1 else "."
+    project_path = Path(target)
+    
+    print("\n" + "=" * 60)
+    print("  API VALIDATOR - Endpoint Best Practices Check")
+    print("=" * 60 + "\n")
+    
+    api_files = find_api_files(project_path)
+    
+    if not api_files:
+        print("[!] No API files found.")
+        print("   Looking for: routes/, controllers/, api/, openapi.json/yaml")
+        sys.exit(0)
+    
+    results = []
+    for file_path in api_files[:15]:  # Limit
+        if 'openapi' in file_path.name.lower() or 'swagger' in file_path.name.lower():
+            result = check_openapi_spec(file_path)
+        else:
+            result = check_api_code(file_path)
+        results.append(result)
+    
+    # Print results
+    total_issues = 0
+    total_passed = 0
+    
+    for result in results:
+        print(f"\n[FILE] {result['file']} [{result['type']}]")
+        for item in result['passed']:
+            print(f"   {item}")
+            total_passed += 1
+        for item in result['issues']:
+            print(f"   {item}")
+            if item.startswith("[X]"):
+                total_issues += 1
+    
+    print("\n" + "=" * 60)
+    print(f"[RESULTS] {total_passed} passed, {total_issues} critical issues")
+    print("=" * 60)
+    
+    if total_issues == 0:
+        print("[OK] API validation passed")
+        sys.exit(0)
+    else:
+        print("[X] Fix critical issues before deployment")
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

package/skills/api/skills/api-patterns/security-testing.md

@@ -0,0 +1,122 @@
+# API Security Testing
+
+> Principles for testing API security. OWASP API Top 10, authentication, authorization testing.
+
+---
+
+## OWASP API Security Top 10
+
+| Vulnerability | Test Focus |
+|---------------|------------|
+| **API1: BOLA** | Access other users' resources |
+| **API2: Broken Auth** | JWT, session, credentials |
+| **API3: Property Auth** | Mass assignment, data exposure |
+| **API4: Resource Consumption** | Rate limiting, DoS |
+| **API5: Function Auth** | Admin endpoints, role bypass |
+| **API6: Business Flow** | Logic abuse, automation |
+| **API7: SSRF** | Internal network access |
+| **API8: Misconfiguration** | Debug endpoints, CORS |
+| **API9: Inventory** | Shadow APIs, old versions |
+| **API10: Unsafe Consumption** | Third-party API trust |
+
+---
+
+## Authentication Testing
+
+### JWT Testing
+
+| Check | What to Test |
+|-------|--------------|
+| Algorithm | None, algorithm confusion |
+| Secret | Weak secrets, brute force |
+| Claims | Expiration, issuer, audience |
+| Signature | Manipulation, key injection |
+
+### Session Testing
+
+| Check | What to Test |
+|-------|--------------|
+| Generation | Predictability |
+| Storage | Client-side security |
+| Expiration | Timeout enforcement |
+| Invalidation | Logout effectiveness |
+
+---
+
+## Authorization Testing
+
+| Test Type | Approach |
+|-----------|----------|
+| **Horizontal** | Access peer users' data |
+| **Vertical** | Access higher privilege functions |
+| **Context** | Access outside allowed scope |
+
+### BOLA/IDOR Testing
+
+1. Identify resource IDs in requests
+2. Capture request with user A's session
+3. Replay with user B's session
+4. Check for unauthorized access
+
+---
+
+## Input Validation Testing
+
+| Injection Type | Test Focus |
+|----------------|------------|
+| SQL | Query manipulation |
+| NoSQL | Document queries |
+| Command | System commands |
+| LDAP | Directory queries |
+
+**Approach:** Test all parameters, try type coercion, test boundaries, check error messages.
+
+---
+
+## Rate Limiting Testing
+
+| Aspect | Check |
+|--------|-------|
+| Existence | Is there any limit? |
+| Bypass | Headers, IP rotation |
+| Scope | Per-user, per-IP, global |
+
+**Bypass techniques:** X-Forwarded-For, different HTTP methods, case variations, API versioning.
+
+---
+
+## GraphQL Security
+
+| Test | Focus |
+|------|-------|
+| Introspection | Schema disclosure |
+| Batching | Query DoS |
+| Nesting | Depth-based DoS |
+| Authorization | Field-level access |
+
+---
+
+## Security Testing Checklist
+
+**Authentication:**
+- [ ] Test for bypass
+- [ ] Check credential strength
+- [ ] Verify token security
+
+**Authorization:**
+- [ ] Test BOLA/IDOR
+- [ ] Check privilege escalation
+- [ ] Verify function access
+
+**Input:**
+- [ ] Test all parameters
+- [ ] Check for injection
+
+**Config:**
+- [ ] Check CORS
+- [ ] Verify headers
+- [ ] Test error handling
+
+---
+
+> **Remember:** APIs are the backbone of modern apps. Test them like attackers will.

package/skills/api/skills/api-patterns/trpc.md

@@ -0,0 +1,41 @@
+# tRPC Principles
+
+> End-to-end type safety for TypeScript monorepos.
+
+## When to Use
+
+```
+✅ Perfect fit:
+├── TypeScript on both ends
+├── Monorepo structure
+├── Internal tools
+├── Rapid development
+└── Type safety critical
+
+❌ Poor fit:
+├── Non-TypeScript clients
+├── Public API
+├── Need REST conventions
+└── Multiple language backends
+```
+
+## Key Benefits
+
+```
+Why tRPC:
+├── Zero schema maintenance
+├── End-to-end type inference
+├── IDE autocomplete across stack
+├── Instant API changes reflected
+└── No code generation step
+```
+
+## Integration Patterns
+
+```
+Common setups:
+├── Next.js + tRPC (most common)
+├── Monorepo with shared types
+├── Remix + tRPC
+└── Any TS frontend + backend
+```

package/skills/api/skills/api-patterns/versioning.md

@@ -0,0 +1,22 @@
+# Versioning Strategies
+
+> Plan for API evolution from day one.
+
+## Decision Factors
+
+| Strategy | Implementation | Trade-offs |
+|----------|---------------|------------|
+| **URI** | /v1/users | Clear, easy caching |
+| **Header** | Accept-Version: 1 | Cleaner URLs, harder discovery |
+| **Query** | ?version=1 | Easy to add, messy |
+| **None** | Evolve carefully | Best for internal, risky for public |
+
+## Versioning Philosophy
+
+```
+Consider:
+├── Public API? → Version in URI
+├── Internal only? → May not need versioning
+├── GraphQL? → Typically no versions (evolve schema)
+├── tRPC? → Types enforce compatibility
+```

package/skills/api/skills/database-patterns.md

@@ -0,0 +1,126 @@
+---
+name: database-patterns
+description: Database design and optimization - schema design, query optimization, N+1 prevention, migrations, connection pooling. Use when working with databases.
+---
+
+# Database Patterns
+
+## When to Activate
+- Designing database schema
+- Optimizing slow queries
+- Writing migrations
+- Debugging N+1 queries
+- Setting up connection pooling
+
+## Schema Design
+
+### Primary Keys
+| Option | When | Example |
+|--------|------|---------|
+| UUID v4 | Distributed systems | No coordination needed |
+| ULID | Sorted + distributed | Time-sortable UUID |
+| Auto-increment | Simple apps | Single database |
+
+### Standard Columns
+Every table should have:
+```sql
+id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
+updated_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
+deleted_at  TIMESTAMPTZ  -- soft delete (nullable)
+```
+
+### Normalization vs Denormalization
+- Normalize to 3NF by default
+- Denormalize intentionally for read-heavy access patterns
+- Document every denormalization with the reason
+
+## Query Optimization
+
+### Index Strategy
+- Add indexes for WHERE, JOIN, ORDER BY columns
+- Composite indexes: column order matters (most selective first)
+- Partial indexes for filtered queries
+- Always verify with `EXPLAIN ANALYZE`
+
+### N+1 Prevention
+
+```sql
+-- BAD: N+1 (one query per user for orders)
+SELECT * FROM users;
+-- then for EACH user:
+SELECT * FROM orders WHERE user_id = ?;
+
+-- GOOD: JOIN
+SELECT u.*, o.id as order_id, o.total
+FROM users u
+LEFT JOIN orders o ON o.user_id = u.id;
+
+-- GOOD: Batch
+SELECT * FROM orders WHERE user_id IN (?, ?, ?, ...);
+```
+
+### ORM Equivalents
+```
+# Django: select_related (JOIN) / prefetch_related (batch)
+User.objects.select_related('profile').prefetch_related('orders')
+
+# Prisma: include
+prisma.user.findMany({ include: { orders: true } })
+
+# TypeORM: relations
+userRepo.find({ relations: ['orders'] })
+```
+
+## Migrations
+
+### Rules
+1. One migration per schema change
+2. Always include rollback (down migration)
+3. Never modify deployed migrations
+4. Test on production-size data before deploying
+5. Separate data migrations from schema migrations
+
+### Safe Migration Patterns
+
+| Operation | Safe Approach |
+|-----------|--------------|
+| Add column | Add nullable, backfill, then add NOT NULL |
+| Remove column | Stop reading first, then drop in next deploy |
+| Rename column | Add new, copy data, update code, drop old |
+| Add index | `CREATE INDEX CONCURRENTLY` (Postgres) |
+
+## Connection Pooling
+
+### Pool Size Formula
+```
+connections = (CPU cores * 2) + disk_spindles
+```
+
+### Configuration
+| Setting | Recommended |
+|---------|------------|
+| Min connections | 2-5 |
+| Max connections | 20-50 |
+| Idle timeout | 10-30 seconds |
+| Max lifetime | 30 minutes |
+| Connection timeout | 5 seconds |
+
+## Security
+
+- Parameterized queries ONLY (never string interpolation)
+- Least-privilege database users per service
+- Encrypt sensitive columns at rest
+- Audit trail for sensitive data access
+- Regular backup testing (restore drills)
+
+## Anti-Patterns
+
+| Don't | Do Instead |
+|-------|-----------|
+| `SELECT *` | Specify needed columns |
+| String concatenation in SQL | Parameterized queries |
+| No indexes on foreign keys | Index all FK columns |
+| Modify deployed migrations | Create new migration |
+| Store files in DB | Store in object storage, reference by URL |
+| Unbounded queries | Always add LIMIT |

package/skills/api/skills/deployment-patterns.md

@@ -0,0 +1,105 @@
+---
+name: deployment-patterns
+description: Production deployment workflows - platform selection, pre-deploy checks, rollback strategies, zero-downtime patterns. Use when deploying or planning deployment.
+---
+
+# Deployment Patterns
+
+## When to Activate
+- Deploying to production
+- Setting up CI/CD pipelines
+- Planning deployment strategy
+- Handling deployment failures
+
+## Platform Decision Tree
+
+| App Type | Recommended | Alternative |
+|----------|------------|-------------|
+| Static site | Vercel, Cloudflare Pages | Netlify, S3+CloudFront |
+| Web app (SSR) | Vercel, Railway | Fly.io, Render |
+| API service | Railway, Fly.io | AWS ECS, GCP Cloud Run |
+| Microservices | Kubernetes | Docker Swarm, Nomad |
+| Serverless | AWS Lambda, Cloudflare Workers | Vercel Functions |
+
+## Pre-Deployment Checklist
+
+### Code Quality
+- [ ] All tests passing
+- [ ] Build succeeds locally
+- [ ] No linting errors
+- [ ] Code reviewed and approved
+
+### Environment
+- [ ] Environment variables configured
+- [ ] Secrets rotated if needed
+- [ ] Database migrations ready
+- [ ] Feature flags set correctly
+
+### Safety
+- [ ] Rollback plan documented
+- [ ] Database backup taken
+- [ ] Monitoring alerts configured
+- [ ] On-call team notified
+
+## Deployment Workflow
+
+### Phase 1: Prepare
+- Run full test suite
+- Build production artifacts
+- Verify environment config
+
+### Phase 2: Backup
+- Database snapshot
+- Note current deployed version (git SHA)
+- Export current config
+
+### Phase 3: Deploy
+- Run database migrations
+- Deploy application
+- Verify health checks pass
+
+### Phase 4: Verify
+- [ ] Health endpoint responding
+- [ ] Key user flows working
+- [ ] No error rate spike
+- [ ] Performance metrics normal
+- [ ] Logs show expected behavior
+
+### Phase 5: Confirm or Rollback
+- If all checks pass: mark deployment complete
+- If issues found: execute rollback plan
+
+## Zero-Downtime Strategies
+
+| Strategy | How It Works | Best For |
+|----------|-------------|----------|
+| **Rolling** | Replace instances one at a time | Standard deployments |
+| **Blue-Green** | Switch traffic between two environments | Critical services |
+| **Canary** | Route small % of traffic to new version | High-risk changes |
+
+## Rollback Plan
+
+```bash
+# Quick rollback
+git revert HEAD
+git push origin main
+
+# Database rollback
+npm run migrate:rollback
+# OR: flyway undo / alembic downgrade
+
+# Container rollback
+docker pull app:previous-version
+docker-compose up -d
+```
+
+## Anti-Patterns
+
+| Don't | Do Instead |
+|-------|-----------|
+| Deploy on Friday afternoon | Deploy early in the week |
+| Skip staging | Always test in staging first |
+| Deploy without monitoring | Set up alerts before deploy |
+| Big bang releases | Small, incremental deployments |
+| Manual deployments | Automate with CI/CD |
+| Skip database backups | Always backup before migrations |