thachvd-kit 1.0.28 → 1.0.30

package/skills/api-design/SKILL.md

@@ -1,156 +0,0 @@
----
-name: api-design
-description: REST API design patterns. Use when designing new API endpoints, reviewing API contracts, choosing pagination strategies, error response formats, versioning, or HTTP status codes.
-allowed-tools: Read, Edit, Write
----
-
-# API Design Patterns
-
-## URL Structure
-
-```
-# Resources: plural nouns, lowercase, kebab-case, no verbs
-GET    /api/v1/users
-POST   /api/v1/users
-GET    /api/v1/users/:id
-PUT    /api/v1/users/:id
-PATCH  /api/v1/users/:id
-DELETE /api/v1/users/:id
-
-# Sub-resources for relationships
-GET    /api/v1/users/:id/orders
-POST   /api/v1/users/:id/orders
-
-# Actions that don't map to CRUD
-POST   /api/v1/orders/:id/cancel
-POST   /api/v1/auth/refresh
-```
-
-**Naming rules:**
-```
-✅ /api/v1/team-members          kebab-case
-✅ /api/v1/orders?status=active  query params for filtering
-✅ /api/v1/users/123/orders      nested for ownership
-
-❌ /api/v1/getUsers              verb in URL
-❌ /api/v1/user                  singular
-❌ /api/v1/team_members          snake_case in URLs
-```
-
-## HTTP Methods and Status Codes
-
-| Method | Idempotent | Use For |
-|--------|-----------|---------|
-| GET | Yes | Retrieve |
-| POST | No | Create / trigger actions |
-| PUT | Yes | Full replacement |
-| PATCH | No | Partial update |
-| DELETE | Yes | Remove |
-
-```
-# Success
-200 OK                    GET, PUT, PATCH (with body)
-201 Created               POST (add Location header)
-204 No Content            DELETE, PUT (no body)
-
-# Client Errors
-400 Bad Request           Validation failure, malformed JSON
-401 Unauthorized          Missing or invalid auth
-403 Forbidden             Authenticated, not authorized
-404 Not Found             Resource doesn't exist
-409 Conflict              Duplicate entry, state conflict
-422 Unprocessable Entity  Valid JSON, semantically invalid
-429 Too Many Requests     Rate limit exceeded
-
-# Server Errors
-500 Internal Server Error Never expose internal details
-503 Service Unavailable   Include Retry-After header
-```
-
-## Response Format
-
-```json
-// Success
-{ "data": { "id": "abc-123", "email": "alice@example.com", "created_at": "2025-01-15T10:30:00Z" } }
-
-// Collection with pagination
-{
-  "data": [{ "id": "abc-123", "name": "Alice" }],
-  "meta": { "total": 142, "page": 1, "per_page": 20, "total_pages": 8 },
-  "links": { "next": "/api/v1/users?page=2&per_page=20" }
-}
-
-// Error
-{
-  "error": {
-    "code": "validation_error",
-    "message": "Request validation failed",
-    "details": [
-      { "field": "email", "message": "Must be a valid email", "code": "invalid_format" }
-    ]
-  }
-}
-```
-
-## Pagination
-
-| Use Case | Type |
-|----------|------|
-| Admin dashboards, small datasets (<10K) | Offset |
-| Infinite scroll, feeds, large datasets | **Cursor** |
-| Public APIs | Cursor (default) |
-| Search results | Offset (users expect page numbers) |
-
-```
-# Offset
-GET /api/v1/users?page=2&per_page=20
-
-# Cursor
-GET /api/v1/users?cursor=eyJpZCI6MTIzfQ&limit=20
-→ { "data": [...], "meta": { "has_next": true, "next_cursor": "eyJpZCI6MTQzfQ" } }
-```
-
-## Versioning
-
-```
-/api/v1/users     ← recommended
-/api/v2/users     ← when breaking changes needed
-```
-
-**Breaking changes** (require new version): removing fields, changing types, changing URL structure.
-**Non-breaking** (no new version): adding optional fields/params, adding endpoints.
-
-Deprecation: 6-month notice, add `Sunset` header, return `410 Gone` after.
-
-## Filtering, Sorting, Search
-
-```
-GET /api/v1/orders?status=active&created_after=2025-01-01
-GET /api/v1/users?sort=created_at&order=desc
-GET /api/v1/products?q=widget
-GET /api/v1/users?fields=id,email,name      # Sparse fieldsets
-```
-
-## Rate Limiting Headers
-
-```
-X-RateLimit-Limit: 100
-X-RateLimit-Remaining: 45
-X-RateLimit-Reset: 1640995200
-Retry-After: 30    # on 429
-```
-
-## API Design Checklist
-
-Before shipping a new endpoint:
-
-- [ ] URL: plural noun, kebab-case, no verbs
-- [ ] Correct HTTP method and status code
-- [ ] Input validated with schema (Zod, Pydantic, Go validator)
-- [ ] Error response follows standard format with field-level details
-- [ ] Pagination implemented for list endpoints
-- [ ] Authentication required (or explicitly marked public)
-- [ ] Authorization checked (user can only access their own resources)
-- [ ] Rate limiting configured
-- [ ] Response does not leak internal details (stack traces, SQL errors)
-- [ ] OpenAPI spec updated

package/skills/api-patterns/SKILL.md

@@ -1,81 +0,0 @@
----
-name: api-patterns
-description: API design principles and decision-making. REST vs GraphQL vs tRPC selection, response formats, versioning, pagination.
-allowed-tools: Read, Write, Edit, Glob, Grep
----
-
-# API Patterns
-
-> API design principles and decision-making for 2025.
-> **Learn to THINK, not copy fixed patterns.**
-
-## 🎯 Selective Reading Rule
-
-**Read ONLY files relevant to the request!** Check the content map, find what you need.
-
----
-
-## 📑 Content Map
-
-| File | Description | When to Read |
-|------|-------------|--------------|
-| `api-style.md` | REST vs GraphQL vs tRPC decision tree | Choosing API type |
-| `rest.md` | Resource naming, HTTP methods, status codes | Designing REST API |
-| `response.md` | Envelope pattern, error format, pagination | Response structure |
-| `graphql.md` | Schema design, when to use, security | Considering GraphQL |
-| `trpc.md` | TypeScript monorepo, type safety | TS fullstack projects |
-| `versioning.md` | URI/Header/Query versioning | API evolution planning |
-| `auth.md` | JWT, OAuth, Passkey, API Keys | Auth pattern selection |
-| `rate-limiting.md` | Token bucket, sliding window | API protection |
-| `documentation.md` | OpenAPI/Swagger best practices | Documentation |
-| `security-testing.md` | OWASP API Top 10, auth/authz testing | Security audits |
-
----
-
-## 🔗 Related Skills
-
-| Need | Skill |
-|------|-------|
-| API implementation | `@[skills/backend-development]` |
-| Data structure | `@[skills/database-design]` |
-| Security details | `@[skills/security-hardening]` |
-
----
-
-## ✅ Decision Checklist
-
-Before designing an API:
-
-- [ ] **Asked user about API consumers?**
-- [ ] **Chosen API style for THIS context?** (REST/GraphQL/tRPC)
-- [ ] **Defined consistent response format?**
-- [ ] **Planned versioning strategy?**
-- [ ] **Considered authentication needs?**
-- [ ] **Planned rate limiting?**
-- [ ] **Documentation approach defined?**
-
----
-
-## ❌ Anti-Patterns
-
-**DON'T:**
-- Default to REST for everything
-- Use verbs in REST endpoints (/getUsers)
-- Return inconsistent response formats
-- Expose internal errors to clients
-- Skip rate limiting
-
-**DO:**
-- Choose API style based on context
-- Ask about client requirements
-- Document thoroughly
-- Use appropriate status codes
-
----
-
-## Script
-
-| Script | Purpose | Command |
-|--------|---------|---------|
-| `scripts/api_validator.py` | API endpoint validation | `python scripts/api_validator.py <project_path>` |
-

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

@@ -1,42 +0,0 @@
-# API Style Selection (2025)
-
-> REST vs GraphQL vs tRPC - Hangi durumda hangisi?
-
-## Decision Tree
-
-```
-Who are the API consumers?
-│
-├── Public API / Multiple platforms
-│   └── REST + OpenAPI (widest compatibility)
-│
-├── Complex data needs / Multiple frontends
-│   └── GraphQL (flexible queries)
-│
-├── TypeScript frontend + backend (monorepo)
-│   └── tRPC (end-to-end type safety)
-│
-├── Real-time / Event-driven
-│   └── WebSocket + AsyncAPI
-│
-└── Internal microservices
-    └── gRPC (performance) or REST (simplicity)
-```
-
-## Comparison
-
-| Factor | REST | GraphQL | tRPC |
-|--------|------|---------|------|
-| **Best for** | Public APIs | Complex apps | TS monorepos |
-| **Learning curve** | Low | Medium | Low (if TS) |
-| **Over/under fetching** | Common | Solved | Solved |
-| **Type safety** | Manual (OpenAPI) | Schema-based | Automatic |
-| **Caching** | HTTP native | Complex | Client-based |
-
-## Selection Questions
-
-1. Who are the API consumers?
-2. Is the frontend TypeScript?
-3. How complex are the data relationships?
-4. Is caching critical?
-5. Public or internal API?

package/skills/api-patterns/auth.md

@@ -1,24 +0,0 @@
-# Authentication Patterns
-
-> Choose auth pattern based on use case.
-
-## Selection Guide
-
-| Pattern | Best For |
-|---------|----------|
-| **JWT** | Stateless, microservices |
-| **Session** | Traditional web, simple |
-| **OAuth 2.0** | Third-party integration |
-| **API Keys** | Server-to-server, public APIs |
-| **Passkey** | Modern passwordless (2025+) |
-
-## JWT Principles
-
-```
-Important:
-├── Always verify signature
-├── Check expiration
-├── Include minimal claims
-├── Use short expiry + refresh tokens
-└── Never store sensitive data in JWT
-```

package/skills/api-patterns/documentation.md

@@ -1,26 +0,0 @@
-# API Documentation Principles
-
-> Good docs = happy developers = API adoption.
-
-## OpenAPI/Swagger Essentials
-
-```
-Include:
-├── All endpoints with examples
-├── Request/response schemas
-├── Authentication requirements
-├── Error response formats
-└── Rate limiting info
-```
-
-## Good Documentation Has
-
-```
-Essentials:
-├── Quick start / Getting started
-├── Authentication guide
-├── Complete API reference
-├── Error handling guide
-├── Code examples (multiple languages)
-└── Changelog
-```

package/skills/api-patterns/graphql.md

@@ -1,41 +0,0 @@
-# GraphQL Principles
-
-> Flexible queries for complex, interconnected data.
-
-## When to Use
-
-```
-✅ Good fit:
-├── Complex, interconnected data
-├── Multiple frontend platforms
-├── Clients need flexible queries
-├── Evolving data requirements
-└── Reducing over-fetching matters
-
-❌ Poor fit:
-├── Simple CRUD operations
-├── File upload heavy
-├── HTTP caching important
-└── Team unfamiliar with GraphQL
-```
-
-## Schema Design Principles
-
-```
-Principles:
-├── Think in graphs, not endpoints
-├── Design for evolvability (no versions)
-├── Use connections for pagination
-├── Be specific with types (not generic "data")
-└── Handle nullability thoughtfully
-```
-
-## Security Considerations
-
-```
-Protect against:
-├── Query depth attacks → Set max depth
-├── Query complexity → Calculate cost
-├── Batching abuse → Limit batch size
-├── Introspection → Disable in production
-```

package/skills/api-patterns/rate-limiting.md

@@ -1,31 +0,0 @@
-# Rate Limiting Principles
-
-> Protect your API from abuse and overload.
-
-## Why Rate Limit
-
-```
-Protect against:
-├── Brute force attacks
-├── Resource exhaustion
-├── Cost overruns (if pay-per-use)
-└── Unfair usage
-```
-
-## Strategy Selection
-
-| Type | How | When |
-|------|-----|------|
-| **Token bucket** | Burst allowed, refills over time | Most APIs |
-| **Sliding window** | Smooth distribution | Strict limits |
-| **Fixed window** | Simple counters per window | Basic needs |
-
-## Response Headers
-
-```
-Include in headers:
-├── X-RateLimit-Limit (max requests)
-├── X-RateLimit-Remaining (requests left)
-├── X-RateLimit-Reset (when limit resets)
-└── Return 429 when exceeded
-```

package/skills/api-patterns/response.md

@@ -1,37 +0,0 @@
-# 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

@@ -1,40 +0,0 @@
-# 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

@@ -1,211 +0,0 @@
-#!/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()