@neyugn/agent-kits 0.1.0

package/kits/coder/skills/api-patterns/SKILL.md

@@ -0,0 +1,316 @@
+---
+name: api-patterns
+description: API design principles and decision-making. Use when designing APIs, choosing between REST/GraphQL/tRPC, or implementing versioning, pagination, error handling. Covers response formats, authentication patterns, and rate limiting.
+allowed-tools: Read, Write, Edit, Glob, Grep
+version: 2.0
+---
+
+# API Patterns - Design Principles & Decision Making
+
+> **Philosophy:** Choose the right API style for the context. Learn to THINK, not copy fixed patterns.
+
+---
+
+## API Style Decision Tree
+
+```
+What are your requirements?
+│
+├─ Public API + Multiple clients?
+│  └─ → REST (broad compatibility, caching)
+│
+├─ Complex UI + Variable data needs?
+│  └─ → GraphQL (client-driven queries)
+│
+├─ TypeScript monorepo + Internal API?
+│  └─ → tRPC (end-to-end type safety)
+│
+├─ Real-time updates needed?
+│  └─ → WebSocket + REST/GraphQL
+│
+└─ Simple CRUD + Standard patterns?
+   └─ → REST (simplest, well-understood)
+```
+
+---
+
+## REST Best Practices
+
+### Resource Naming
+
+| ✅ Do               | ❌ Don't           |
+| ------------------- | ------------------ |
+| `GET /users`        | `GET /getUsers`    |
+| `GET /users/:id`    | `GET /user?id=123` |
+| `POST /users`       | `POST /createUser` |
+| `DELETE /users/:id` | `POST /deleteUser` |
+| `/users/:id/orders` | `/getUserOrders`   |
+
+### HTTP Methods
+
+| Method   | Purpose          | Idempotent |
+| -------- | ---------------- | ---------- |
+| `GET`    | Read resource    | ✅ Yes     |
+| `POST`   | Create resource  | ❌ No      |
+| `PUT`    | Replace resource | ✅ Yes     |
+| `PATCH`  | Partial update   | ❌ No      |
+| `DELETE` | Remove resource  | ✅ Yes     |
+
+### HTTP Status Codes
+
+| Code  | Meaning           | Use Case                 |
+| ----- | ----------------- | ------------------------ |
+| `200` | OK                | Successful GET/PUT/PATCH |
+| `201` | Created           | Successful POST          |
+| `204` | No Content        | Successful DELETE        |
+| `400` | Bad Request       | Invalid input            |
+| `401` | Unauthorized      | Missing/invalid auth     |
+| `403` | Forbidden         | No permission            |
+| `404` | Not Found         | Resource doesn't exist   |
+| `409` | Conflict          | Duplicate/state conflict |
+| `422` | Unprocessable     | Validation failed        |
+| `429` | Too Many Requests | Rate limited             |
+| `500` | Server Error      | Internal error           |
+
+---
+
+## Response Format
+
+### Standard Success Response
+
+```json
+{
+  "data": {},
+  "meta": {
+    "requestId": "abc-123",
+    "timestamp": 1707100000
+  }
+}
+```
+
+### Standard Error Response
+
+```json
+{
+  "error": {
+    "code": "USER_NOT_FOUND",
+    "message": "User with ID 123 was not found",
+    "details": {
+      "userId": "123"
+    }
+  },
+  "meta": {
+    "requestId": "abc-123",
+    "timestamp": 1707100000
+  }
+}
+```
+
+### Error Code Naming
+
+| Pattern                   | Example                             |
+| ------------------------- | ----------------------------------- |
+| `RESOURCE_NOT_FOUND`      | `USER_NOT_FOUND`, `ORDER_NOT_FOUND` |
+| `RESOURCE_ALREADY_EXISTS` | `EMAIL_ALREADY_EXISTS`              |
+| `INVALID_FIELD`           | `INVALID_EMAIL`, `INVALID_PHONE`    |
+| `PERMISSION_DENIED`       | `PERMISSION_DENIED`                 |
+| `RATE_LIMITED`            | `RATE_LIMITED`                      |
+
+---
+
+## Pagination Patterns
+
+### Offset-Based (Simple)
+
+```
+GET /users?page=2&limit=20
+
+Response:
+{
+  "data": [...],
+  "pagination": {
+    "page": 2,
+    "limit": 20,
+    "total": 100,
+    "totalPages": 5
+  }
+}
+```
+
+**Pros:** Simple, supports random access
+**Cons:** Performance issues with large offsets, unstable with mutations
+
+### Cursor-Based (Recommended for Large Datasets)
+
+```
+GET /users?cursor=eyJpZCI6MTAwfQ&limit=20
+
+Response:
+{
+  "data": [...],
+  "pagination": {
+    "nextCursor": "eyJpZCI6MTIwfQ",
+    "prevCursor": "eyJpZCI6ODB9",
+    "hasMore": true
+  }
+}
+```
+
+**Pros:** Stable ordering, efficient for large datasets
+**Cons:** No random access, more complex
+
+### Decision Matrix
+
+| Use Case                  | Strategy |
+| ------------------------- | -------- |
+| Small dataset (<1000)     | Offset   |
+| Large dataset (>10000)    | Cursor   |
+| Frequently changing data  | Cursor   |
+| Random page access needed | Offset   |
+| Infinite scroll UI        | Cursor   |
+| Table with page numbers   | Offset   |
+
+---
+
+## API Versioning
+
+### Strategies
+
+| Strategy        | Example          | Pros             | Cons                |
+| --------------- | ---------------- | ---------------- | ------------------- |
+| **URI Path**    | `/v1/users`      | Clear, cacheable | URL pollution       |
+| **Header**      | `Api-Version: 1` | Clean URLs       | Hidden from clients |
+| **Query Param** | `?version=1`     | Easy to test     | Not RESTful         |
+
+**Recommendation:** Use URI path versioning for clarity.
+
+### Version Lifecycle
+
+```
+v1 (current)    → Active, fully supported
+v2 (beta)       → In development, may change
+v1 (deprecated) → Still works, sunset warning
+v1 (retired)    → Returns 410 Gone
+```
+
+---
+
+## Authentication Patterns
+
+| Pattern       | Use Case         | Notes                        |
+| ------------- | ---------------- | ---------------------------- |
+| **JWT**       | Stateless APIs   | Short expiry, refresh tokens |
+| **OAuth 2.0** | Third-party auth | Authorization Code flow      |
+| **API Key**   | Server-to-server | Rate limit per key           |
+| **Session**   | Traditional web  | Requires sticky sessions     |
+
+### JWT Best Practices
+
+- Access token: 15 min expiry
+- Refresh token: 7 days expiry
+- Store refresh token securely (httpOnly cookie)
+- Include minimal claims (user ID, roles)
+- Validate signature on every request
+
+---
+
+## Rate Limiting
+
+### Strategies
+
+| Strategy           | Description                           |
+| ------------------ | ------------------------------------- |
+| **Token Bucket**   | Allows bursts, refills over time      |
+| **Sliding Window** | Smooth rate control                   |
+| **Fixed Window**   | Simple but allows burst at boundaries |
+
+### Response Headers
+
+```
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 45
+X-RateLimit-Reset: 1707105600
+Retry-After: 60
+```
+
+### Handling 429
+
+```json
+{
+  "error": {
+    "code": "RATE_LIMITED",
+    "message": "Too many requests. Try again in 60 seconds.",
+    "retryAfter": 60
+  }
+}
+```
+
+---
+
+## GraphQL vs REST
+
+| Aspect             | REST                     | GraphQL                    |
+| ------------------ | ------------------------ | -------------------------- |
+| **Data fetching**  | Multiple endpoints       | Single endpoint            |
+| **Over-fetching**  | Common                   | Avoided                    |
+| **Under-fetching** | Multiple requests        | Single query               |
+| **Caching**        | HTTP caching             | Complex                    |
+| **Learning curve** | Low                      | Medium                     |
+| **Best for**       | Simple CRUD, public APIs | Complex UIs, variable data |
+
+---
+
+## tRPC Best Practices
+
+When using tRPC (TypeScript-first):
+
+1. **Monorepo structure** - Share types between client/server
+2. **Procedure organization** - Group by feature, not CRUD
+3. **Input validation** - Use Zod for runtime validation
+4. **Error handling** - Use TRPCError for typed errors
+5. **Context** - Inject auth/db/etc via context
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't                     | ✅ Do                         |
+| ---------------------------- | ----------------------------- |
+| Use verbs in REST endpoints  | Use nouns + HTTP methods      |
+| Return 200 for errors        | Use appropriate status codes  |
+| Expose stack traces          | Return structured error codes |
+| Skip rate limiting           | Implement from day 1          |
+| Inconsistent response format | Define envelope pattern       |
+| Version in request body      | Version in URL path           |
+| Return all fields always     | Support field selection       |
+
+---
+
+## API Design Checklist
+
+Before implementing:
+
+- [ ] Identified API consumers (web, mobile, third-party)?
+- [ ] Chosen API style (REST/GraphQL/tRPC)?
+- [ ] Defined consistent response format?
+- [ ] Planned versioning strategy?
+- [ ] Designed authentication approach?
+- [ ] Implemented rate limiting?
+- [ ] Created OpenAPI documentation?
+- [ ] Added proper error codes?
+- [ ] Implemented pagination for lists?
+
+---
+
+## Related Skills
+
+| Need                   | Skill                   |
+| ---------------------- | ----------------------- |
+| Backend implementation | `nodejs-best-practices` |
+| Database design        | `database-design`       |
+| Security hardening     | `security-fundamentals` |
+| Testing APIs           | `testing-patterns`      |
+
+---
+
+> **Remember:** The best API is one that's easy to use correctly and hard to use incorrectly. Prioritize developer experience.

package/kits/coder/skills/api-patterns/assets/.gitkeep

@@ -0,0 +1 @@
+# Assets directory - add templates, images, etc.

package/kits/coder/skills/api-patterns/references/deep-dive.md

@@ -0,0 +1,21 @@
+# Reference Documentation for Api Patterns
+
+[TODO: Add detailed reference content here]
+
+## Overview
+
+[Detailed explanation of concepts]
+
+## Deep Dive Topics
+
+### Topic 1
+
+[Content]
+
+### Topic 2
+
+[Content]
+
+## Examples
+
+[Real-world examples]

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

@@ -0,0 +1,253 @@
+#!/usr/bin/env python3
+"""
+API Validator - API endpoint best practices check for AGT-Kit
+==============================================================
+
+Validates OpenAPI specs, API code patterns, and common issues.
+
+Usage:
+    python3 .agent/skills/api-patterns/scripts/api_validator.py <project_path>
+
+Checks:
+    - OpenAPI/Swagger specification completeness
+    - Error handling patterns
+    - Input validation (Zod, Joi, etc.)
+    - Authentication/authorization
+    - Rate limiting
+    - HTTP status codes
+"""
+
+import sys
+import json
+import re
+from pathlib import Path
+from datetime import datetime
+from typing import List, Dict, Any
+
+# Fix console encoding
+try:
+    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+except:
+    pass
+
+SKIP_DIRS = {'node_modules', '.git', 'dist', 'build', '__pycache__', '.next', 'venv'}
+
+
+def find_api_files(project_path: Path) -> List[tuple]:
+    """Find API-related files."""
+    files = []
+    
+    patterns = {
+        'openapi': ['**/openapi*.json', '**/openapi*.yaml', '**/swagger*.json', '**/swagger*.yaml'],
+        'routes': ['**/routes/**/*.ts', '**/routes/**/*.js', '**/api/**/*.ts', '**/api/**/*.py'],
+        'controllers': ['**/controllers/**/*.ts', '**/controllers/**/*.js'],
+    }
+    
+    for file_type, globs in patterns.items():
+        for pattern in globs:
+            for f in project_path.glob(pattern):
+                if not any(skip in f.parts for skip in SKIP_DIRS):
+                    files.append((file_type, f))
+    
+    return files[:20]  # Limit
+
+
+def check_openapi_spec(file_path: Path) -> Dict[str, Any]:
+    """Check OpenAPI/Swagger specification."""
+    issues = []
+    passed = []
+    
+    try:
+        content = file_path.read_text(encoding='utf-8')
+        
+        # JSON or YAML
+        is_json = file_path.suffix == '.json'
+        
+        if is_json:
+            try:
+                spec = json.loads(content)
+                
+                # Version check
+                if 'openapi' in spec or 'swagger' in spec:
+                    passed.append("OpenAPI version defined")
+                
+                # Info section
+                if 'info' in spec:
+                    if spec['info'].get('title'):
+                        passed.append("API title defined")
+                    if spec['info'].get('version'):
+                        passed.append("API version defined")
+                    if not spec['info'].get('description'):
+                        issues.append("API description missing")
+                
+                # Paths
+                if 'paths' in spec:
+                    path_count = len(spec['paths'])
+                    passed.append(f"{path_count} endpoints defined")
+                    
+                    # Check each endpoint
+                    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"{method.upper()} {path}: No responses")
+                                if not details.get('summary') and not details.get('description'):
+                                    issues.append(f"{method.upper()} {path}: No description")
+                else:
+                    issues.append("No paths defined")
+                    
+            except json.JSONDecodeError as e:
+                issues.append(f"Invalid JSON: {str(e)[:30]}")
+        else:
+            # Basic YAML check
+            if 'openapi:' in content or 'swagger:' in content:
+                passed.append("OpenAPI version defined")
+            if 'paths:' in content:
+                passed.append("Paths section exists")
+            if 'components:' in content:
+                passed.append("Components defined")
+                
+    except Exception as e:
+        issues.append(f"Read error: {str(e)[:30]}")
+    
+    return {"passed": passed, "issues": issues, "type": "openapi"}
+
+
+def check_api_code(file_path: Path) -> Dict[str, Any]:
+    """Check API code for best practices."""
+    issues = []
+    passed = []
+    
+    try:
+        content = file_path.read_text(encoding='utf-8')
+        
+        # Error handling
+        error_patterns = [r'try\s*{', r'try:', r'\.catch\(', r'except\s+', r'catch\s*\(']
+        if any(re.search(p, content) for p in error_patterns):
+            passed.append("Error handling present")
+        else:
+            issues.append("No error handling found")
+        
+        # HTTP status codes
+        status_patterns = [
+            r'\.status\(\d{3}\)', r'status\s*=\s*\d{3}', r'statusCode.*\d{3}',
+            r'HttpStatus\.', r'res\.status\('
+        ]
+        if any(re.search(p, content) for p in status_patterns):
+            passed.append("HTTP status codes used")
+        else:
+            issues.append("No explicit status codes")
+        
+        # Input validation
+        validation_patterns = [r'validate', r'schema', r'zod', r'joi', r'yup', r'pydantic', r'@Body\(']
+        if any(re.search(p, content, re.I) for p in validation_patterns):
+            passed.append("Input validation present")
+        else:
+            issues.append("No input validation detected")
+        
+        # Authentication
+        auth_patterns = [r'auth', r'jwt', r'bearer', r'token', r'middleware', r'guard']
+        if any(re.search(p, content, re.I) for p in auth_patterns):
+            passed.append("Authentication detected")
+        
+        # Rate limiting
+        rate_patterns = [r'rateLimit', r'throttle', r'rate.?limit']
+        if any(re.search(p, content, re.I) for p in rate_patterns):
+            passed.append("Rate limiting present")
+        
+        # Logging
+        log_patterns = [r'console\.(log|error|warn)', r'logger\.', r'logging\.\w+']
+        if any(re.search(p, content) for p in log_patterns):
+            passed.append("Logging present")
+        
+        # CORS
+        if 'cors' in content.lower():
+            passed.append("CORS configuration")
+        
+    except Exception as e:
+        issues.append(f"Read error: {str(e)[:30]}")
+    
+    return {"passed": passed, "issues": issues, "type": "code"}
+
+
+def main():
+    project_path = Path(sys.argv[1] if len(sys.argv) > 1 else ".").resolve()
+    
+    print(f"\n{'='*60}")
+    print(f"[AGT-KIT API VALIDATOR] API Best Practices Check")
+    print(f"{'='*60}")
+    print(f"Project: {project_path}")
+    print(f"Time: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+    print("-"*60)
+    
+    api_files = find_api_files(project_path)
+    
+    if not api_files:
+        print("No API files found.")
+        print("Looking for: openapi.json, swagger.yaml, routes/, api/, controllers/")
+        output = {
+            "script": "api_validator",
+            "skill": "api-patterns",
+            "project": str(project_path),
+            "files_checked": 0,
+            "passed": True,
+            "message": "No API files found"
+        }
+        print(json.dumps(output, indent=2))
+        sys.exit(0)
+    
+    print(f"Found {len(api_files)} API files\n")
+    
+    all_results = []
+    total_passed = 0
+    total_issues = 0
+    
+    for file_type, file_path in api_files:
+        print(f"📄 {file_path.name} [{file_type}]")
+        
+        if file_type == 'openapi':
+            result = check_openapi_spec(file_path)
+        else:
+            result = check_api_code(file_path)
+        
+        for item in result["passed"]:
+            print(f"  ✅ {item}")
+            total_passed += 1
+        for item in result["issues"][:3]:
+            print(f"  ⚠️  {item}")
+            total_issues += 1
+        
+        all_results.append({
+            "file": str(file_path.name),
+            **result
+        })
+        print()
+    
+    # Summary
+    print("="*60)
+    print(f"SUMMARY: {total_passed} passed, {total_issues} issues")
+    print("="*60)
+    
+    passed = total_issues < 5
+    
+    if passed:
+        print("✅ API validation passed")
+    else:
+        print("⚠️  API needs improvement")
+    
+    output = {
+        "script": "api_validator",
+        "skill": "api-patterns",
+        "project": str(project_path),
+        "files_checked": len(api_files),
+        "total_passed": total_passed,
+        "total_issues": total_issues,
+        "passed": passed
+    }
+    
+    print("\n" + json.dumps(output, indent=2))
+    sys.exit(0 if passed else 1)
+
+
+if __name__ == "__main__":
+    main()

package/kits/coder/skills/api-patterns/scripts/validate.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+"""
+Example validator for api-patterns
+
+Usage:
+    python validate.py <project_path>
+"""
+
+import sys
+from pathlib import Path
+
+
+def validate(project_path: str) -> dict:
+    """Main validation logic"""
+    results = {
+        'errors': [],
+        'warnings': [],
+        'passed': []
+    }
+    
+    # TODO: Add validation logic
+    results['passed'].append('Placeholder validation passed')
+    
+    return results
+
+
+def print_results(results: dict):
+    """Pretty print results"""
+    print("\n🔍 Validation Results\n")
+    
+    if results['errors']:
+        print(f"❌ Errors ({len(results['errors'])})")
+        for error in results['errors']:
+            print(f"  - {error}")
+    
+    if results['warnings']:
+        print(f"\n⚠️  Warnings ({len(results['warnings'])})")
+        for warning in results['warnings']:
+            print(f"  - {warning}")
+    
+    if results['passed']:
+        print(f"\n✅ Passed ({len(results['passed'])})")
+        for passed in results['passed']:
+            print(f"  - {passed}")
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print("Usage: python validate.py <project_path>")
+        sys.exit(1)
+    
+    project_path = sys.argv[1]
+    results = validate(project_path)
+    print_results(results)
+    
+    sys.exit(1 if results['errors'] else 0)