create-raffles-it 1.0.1

package/skills/api-patterns/response.md

@@ -0,0 +1,37 @@
+# Response Format Principles
+
+> Consistency is key - choose a format and stick to it.
+
+## Common Patterns
+
+```
+Choose one:
+├── Envelope pattern ({ success, data, error })
+├── Direct data (just return the resource)
+└── HAL/JSON:API (hypermedia)
+```
+
+## Error Response
+
+```
+Include:
+├── Error code (for programmatic handling)
+├── User message (for display)
+├── Details (for debugging, field-level errors)
+├── Request ID (for support)
+└── NOT internal details (security!)
+```
+
+## Pagination Types
+
+| Type | Best For | Trade-offs |
+|------|----------|------------|
+| **Offset** | Simple, jumpable | Performance on large datasets |
+| **Cursor** | Large datasets | Can't jump to page |
+| **Keyset** | Performance critical | Requires sortable key |
+
+### Selection Questions
+
+1. How large is the dataset?
+2. Do users need to jump to specific pages?
+3. Is data frequently changing?

package/skills/api-patterns/rest.md

@@ -0,0 +1,40 @@
+# REST Principles
+
+> Resource-based API design - nouns not verbs.
+
+## Resource Naming Rules
+
+```
+Principles:
+├── Use NOUNS, not verbs (resources, not actions)
+├── Use PLURAL forms (/users not /user)
+├── Use lowercase with hyphens (/user-profiles)
+├── Nest for relationships (/users/123/posts)
+└── Keep shallow (max 3 levels deep)
+```
+
+## HTTP Method Selection
+
+| Method | Purpose | Idempotent? | Body? |
+|--------|---------|-------------|-------|
+| **GET** | Read resource(s) | Yes | No |
+| **POST** | Create new resource | No | Yes |
+| **PUT** | Replace entire resource | Yes | Yes |
+| **PATCH** | Partial update | No | Yes |
+| **DELETE** | Remove resource | Yes | No |
+
+## Status Code Selection
+
+| Situation | Code | Why |
+|-----------|------|-----|
+| Success (read) | 200 | Standard success |
+| Created | 201 | New resource created |
+| No content | 204 | Success, nothing to return |
+| Bad request | 400 | Malformed request |
+| Unauthorized | 401 | Missing/invalid auth |
+| Forbidden | 403 | Valid auth, no permission |
+| Not found | 404 | Resource doesn't exist |
+| Conflict | 409 | State conflict (duplicate) |
+| Validation error | 422 | Valid syntax, invalid data |
+| Rate limited | 429 | Too many requests |
+| Server error | 500 | Our fault |

package/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-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-patterns/skill.yaml

@@ -0,0 +1,3 @@
+name: api-patterns
+description: API design principles and decision-making. REST vs GraphQL vs tRPC selection, response formats, versioning, pagination.
+version: "1.0"

package/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-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/architecture/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: architecture
+description: Architectural decision-making framework. Requirements analysis, trade-off evaluation, ADR documentation. Use when making architecture decisions or analyzing system design.
+allowed-tools: Read, Glob, Grep
+---
+
+# Architecture Decision Framework
+
+> "Requirements drive architecture. Trade-offs inform decisions. ADRs capture rationale."
+
+## 🎯 Selective Reading Rule
+
+**Read ONLY files relevant to the request!** Check the content map, find what you need.
+
+| File | Description | When to Read |
+|------|-------------|--------------|
+| `context-discovery.md` | Questions to ask, project classification | Starting architecture design |
+| `trade-off-analysis.md` | ADR templates, trade-off framework | Documenting decisions |
+| `pattern-selection.md` | Decision trees, anti-patterns | Choosing patterns |
+| `examples.md` | MVP, SaaS, Enterprise examples | Reference implementations |
+| `patterns-reference.md` | Quick lookup for patterns | Pattern comparison |
+
+---
+
+## 🔗 Related Skills
+
+| Skill | Use For |
+|-------|---------|
+| `@[skills/database-design]` | Database schema design |
+| `@[skills/api-patterns]` | API design patterns |
+| `@[skills/deployment-procedures]` | Deployment architecture |
+
+---
+
+## Core Principle
+
+**"Simplicity is the ultimate sophistication."**
+
+- Start simple
+- Add complexity ONLY when proven necessary
+- You can always add patterns later
+- Removing complexity is MUCH harder than adding it
+
+---
+
+## Validation Checklist
+
+Before finalizing architecture:
+
+- [ ] Requirements clearly understood
+- [ ] Constraints identified
+- [ ] Each decision has trade-off analysis
+- [ ] Simpler alternatives considered
+- [ ] ADRs written for significant decisions
+- [ ] Team expertise matches chosen patterns

package/skills/architecture/context-discovery.md

@@ -0,0 +1,43 @@
+# Context Discovery
+
+> Before suggesting any architecture, gather context.
+
+## Question Hierarchy (Ask User FIRST)
+
+1. **Scale**
+   - How many users? (10, 1K, 100K, 1M+)
+   - Data volume? (MB, GB, TB)
+   - Transaction rate? (per second/minute)
+
+2. **Team**
+   - Solo developer or team?
+   - Team size and expertise?
+   - Distributed or co-located?
+
+3. **Timeline**
+   - MVP/Prototype or long-term product?
+   - Time to market pressure?
+
+4. **Domain**
+   - CRUD-heavy or business logic complex?
+   - Real-time requirements?
+   - Compliance/regulations?
+
+5. **Constraints**
+   - Budget limitations?
+   - Legacy systems to integrate?
+   - Technology stack preferences?
+
+## Project Classification Matrix
+
+```
+                    MVP              SaaS           Enterprise
+┌─────────────────────────────────────────────────────────────┐
+│ Scale        │ <1K           │ 1K-100K      │ 100K+        │
+│ Team         │ Solo          │ 2-10         │ 10+          │
+│ Timeline     │ Fast (weeks)  │ Medium (months)│ Long (years)│
+│ Architecture │ Simple        │ Modular      │ Distributed  │
+│ Patterns     │ Minimal       │ Selective    │ Comprehensive│
+│ Example      │ Next.js API   │ NestJS       │ Microservices│
+└─────────────────────────────────────────────────────────────┘
+```

package/skills/architecture/examples.md

@@ -0,0 +1,94 @@
+# Architecture Examples
+
+> Real-world architecture decisions by project type.
+
+---
+
+## Example 1: MVP E-commerce (Solo Developer)
+
+```yaml
+Requirements:
+  - <1000 users initially
+  - Solo developer
+  - Fast to market (8 weeks)
+  - Budget-conscious
+
+Architecture Decisions:
+  App Structure: Monolith (simpler for solo)
+  Framework: Next.js (full-stack, fast)
+  Data Layer: Prisma direct (no over-abstraction)
+  Authentication: JWT (simpler than OAuth)
+  Payment: Stripe (hosted solution)
+  Database: PostgreSQL (ACID for orders)
+
+Trade-offs Accepted:
+  - Monolith → Can't scale independently (team doesn't justify it)
+  - No Repository → Less testable (simple CRUD doesn't need it)
+  - JWT → No social login initially (can add later)
+
+Future Migration Path:
+  - Users > 10K → Extract payment service
+  - Team > 3 → Add Repository pattern
+  - Social login requested → Add OAuth
+```
+
+---
+
+## Example 2: SaaS Product (5-10 Developers)
+
+```yaml
+Requirements:
+  - 1K-100K users
+  - 5-10 developers
+  - Long-term (12+ months)
+  - Multiple domains (billing, users, core)
+
+Architecture Decisions:
+  App Structure: Modular Monolith (team size optimal)
+  Framework: NestJS (modular by design)
+  Data Layer: Repository pattern (testing, flexibility)
+  Domain Model: Partial DDD (rich entities)
+  Authentication: OAuth + JWT
+  Caching: Redis
+  Database: PostgreSQL
+
+Trade-offs Accepted:
+  - Modular Monolith → Some module coupling (microservices not justified)
+  - Partial DDD → No full aggregates (no domain experts)
+  - RabbitMQ later → Initial synchronous (add when proven needed)
+
+Migration Path:
+  - Team > 10 → Consider microservices
+  - Domains conflict → Extract bounded contexts
+  - Read performance issues → Add CQRS
+```
+
+---
+
+## Example 3: Enterprise (100K+ Users)
+
+```yaml
+Requirements:
+  - 100K+ users
+  - 10+ developers
+  - Multiple business domains
+  - Different scaling needs
+  - 24/7 availability
+
+Architecture Decisions:
+  App Structure: Microservices (independent scale)
+  API Gateway: Kong/AWS API GW
+  Domain Model: Full DDD
+  Consistency: Event-driven (eventual OK)
+  Message Bus: Kafka
+  Authentication: OAuth + SAML (enterprise SSO)
+  Database: Polyglot (right tool per job)
+  CQRS: Selected services
+
+Operational Requirements:
+  - Service mesh (Istio/Linkerd)
+  - Distributed tracing (Jaeger/Tempo)
+  - Centralized logging (ELK/Loki)
+  - Circuit breakers (Resilience4j)
+  - Kubernetes/Helm
+```