cp-toolkit 2.0.0

package/templates/skills/optional/nextjs-react-expert/scripts/react_performance_checker.py

@@ -0,0 +1,252 @@
+#!/usr/bin/env python3
+"""
+React Performance Checker
+Automated performance audit for React/Next.js projects
+Based on Vercel Engineering best practices
+"""
+
+import os
+import re
+import json
+from pathlib import Path
+from typing import List, Dict, Tuple
+
+class PerformanceChecker:
+    def __init__(self, project_path: str):
+        self.project_path = Path(project_path)
+        self.issues = []
+        self.warnings = []
+        self.passed = []
+
+    def check_waterfalls(self):
+        """Check for sequential await patterns (Section 1)"""
+        print("\n[*] Checking for waterfalls (sequential awaits)...")
+
+        for filepath in self.project_path.rglob('*.{ts,tsx,js,jsx}'):
+            if 'node_modules' in str(filepath):
+                continue
+
+            try:
+                content = filepath.read_text(encoding='utf-8')
+
+                # Pattern: multiple awaits in sequence without Promise.all
+                sequential_awaits = re.findall(r'await\s+\w+.*?\n\s*await\s+\w+', content)
+
+                if sequential_awaits:
+                    self.issues.append({
+                        'file': str(filepath.relative_to(self.project_path)),
+                        'type': 'CRITICAL',
+                        'issue': 'Sequential awaits detected (waterfall)',
+                        'fix': 'Use Promise.all() for parallel fetching',
+                        'section': '1-async-eliminating-waterfalls.md'
+                    })
+            except Exception as e:
+                continue
+
+    def check_barrel_imports(self):
+        """Check for barrel imports (Section 2)"""
+        print("[*] Checking for barrel imports...")
+
+        for filepath in self.project_path.rglob('*.{ts,tsx,js,jsx}'):
+            if 'node_modules' in str(filepath):
+                continue
+
+            try:
+                content = filepath.read_text(encoding='utf-8')
+
+                # Pattern: import from index files or barrel exports
+                barrel_imports = re.findall(r"import.*from\s+['\"](@/.*?)/index['\"]", content)
+                barrel_imports += re.findall(r"import.*from\s+['\"]\.\.?/.*?['\"](?!.*?\.tsx?)", content)
+
+                if barrel_imports:
+                    self.warnings.append({
+                        'file': str(filepath.relative_to(self.project_path)),
+                        'type': 'CRITICAL',
+                        'issue': 'Potential barrel imports detected',
+                        'fix': 'Import directly from specific files',
+                        'section': '2-bundle-bundle-size-optimization.md'
+                    })
+            except Exception as e:
+                continue
+
+    def check_dynamic_imports(self):
+        """Check if large components use dynamic imports (Section 2)"""
+        print("[*] Checking for missing dynamic imports...")
+
+        for filepath in self.project_path.rglob('*.{ts,tsx}'):
+            if 'node_modules' in str(filepath):
+                continue
+
+            try:
+                content = filepath.read_text(encoding='utf-8')
+
+                # Check file size - if > 10KB, should probably use dynamic import
+                if len(content) > 10000:
+                    # Check if it's imported statically somewhere
+                    filename = filepath.stem
+
+                    # Search for static imports of this component
+                    for check_file in self.project_path.rglob('*.{ts,tsx}'):
+                        if check_file == filepath or 'node_modules' in str(check_file):
+                            continue
+
+                        check_content = check_file.read_text(encoding='utf-8')
+                        if f"import {filename}" in check_content or f"import {{ {filename}" in check_content:
+                            if 'dynamic(' not in check_content:
+                                self.warnings.append({
+                                    'file': str(check_file.relative_to(self.project_path)),
+                                    'type': 'CRITICAL',
+                                    'issue': f'Large component {filename} imported statically',
+                                    'fix': 'Use dynamic() for code splitting',
+                                    'section': '2-bundle-bundle-size-optimization.md'
+                                })
+                                break
+            except Exception as e:
+                continue
+
+    def check_useEffect_fetching(self):
+        """Check for data fetching in useEffect (Section 4)"""
+        print("[*] Checking for useEffect data fetching...")
+
+        for filepath in self.project_path.rglob('*.{ts,tsx}'):
+            if 'node_modules' in str(filepath):
+                continue
+
+            try:
+                content = filepath.read_text(encoding='utf-8')
+
+                # Pattern: fetch or axios in useEffect
+                if 'useEffect' in content:
+                    if re.search(r'useEffect.*?fetch\(', content, re.DOTALL):
+                        self.warnings.append({
+                            'file': str(filepath.relative_to(self.project_path)),
+                            'type': 'MEDIUM-HIGH',
+                            'issue': 'Data fetching in useEffect',
+                            'fix': 'Consider using SWR or React Query for deduplication',
+                            'section': '4-client-client-side-data-fetching.md'
+                        })
+            except Exception as e:
+                continue
+
+    def check_missing_memoization(self):
+        """Check for missing React.memo, useMemo, useCallback (Section 5)"""
+        print("[*] Checking for missing memoization...")
+
+        for filepath in self.project_path.rglob('*.{tsx}'):
+            if 'node_modules' in str(filepath):
+                continue
+
+            try:
+                content = filepath.read_text(encoding='utf-8')
+
+                # Check for component definitions without memo
+                components = re.findall(r'(?:export\s+)?(?:const|function)\s+([A-Z]\w+)', content)
+
+                if components and 'React.memo' not in content and 'memo(' not in content:
+                    # Check if component receives props
+                    if 'props:' in content or 'Props>' in content:
+                        self.warnings.append({
+                            'file': str(filepath.relative_to(self.project_path)),
+                            'type': 'MEDIUM',
+                            'issue': 'Component with props not memoized',
+                            'fix': 'Consider using React.memo if props are stable',
+                            'section': '5-rerender-re-render-optimization.md'
+                        })
+            except Exception as e:
+                continue
+
+    def check_image_optimization(self):
+        """Check for unoptimized images (Section 6)"""
+        print("[*] Checking for image optimization...")
+
+        for filepath in self.project_path.rglob('*.{ts,tsx,js,jsx}'):
+            if 'node_modules' in str(filepath):
+                continue
+
+            try:
+                content = filepath.read_text(encoding='utf-8')
+
+                # Check for <img> tags instead of next/image
+                if '<img' in content and 'next/image' not in content:
+                    self.warnings.append({
+                        'file': str(filepath.relative_to(self.project_path)),
+                        'type': 'MEDIUM',
+                        'issue': 'Using <img> instead of next/image',
+                        'fix': 'Use next/image for automatic optimization',
+                        'section': '6-rendering-rendering-performance.md'
+                    })
+            except Exception as e:
+                continue
+
+    def generate_report(self):
+        """Generate final report"""
+        print("\n" + "="*60)
+        print("REACT PERFORMANCE AUDIT REPORT")
+        print("="*60)
+
+        print(f"\n[CRITICAL ISSUES] ({len([i for i in self.issues if i['type'] == 'CRITICAL'])})")
+        for issue in self.issues:
+            if issue['type'] == 'CRITICAL':
+                print(f"  - {issue['file']}")
+                print(f"    Issue: {issue['issue']}")
+                print(f"    Fix: {issue['fix']}")
+                print(f"    Reference: {issue['section']}\n")
+
+        print(f"\n[WARNINGS] ({len(self.warnings)})")
+        for warning in self.warnings[:10]:  # Show first 10
+            print(f"  - {warning['file']}")
+            print(f"    Issue: {warning['issue']}")
+            print(f"    Fix: {warning['fix']}")
+            print(f"    Reference: {warning['section']}\n")
+
+        if len(self.warnings) > 10:
+            print(f"  ... and {len(self.warnings) - 10} more warnings")
+
+        print("\n" + "="*60)
+        print(f"SUMMARY:")
+        print(f"  Critical Issues: {len([i for i in self.issues if i['type'] == 'CRITICAL'])}")
+        print(f"  Warnings: {len(self.warnings)}")
+        print("="*60)
+
+        if len(self.issues) == 0 and len(self.warnings) == 0:
+            print("\n[SUCCESS] No major performance issues detected!")
+        else:
+            print("\n[ACTION REQUIRED] Review and fix issues above")
+            print("Priority: CRITICAL > HIGH > MEDIUM > LOW")
+
+    def run(self):
+        """Run all checks"""
+        print("="*60)
+        print("React Performance Checker (Vercel Engineering)")
+        print("="*60)
+        print(f"Scanning: {self.project_path}")
+
+        self.check_waterfalls()
+        self.check_barrel_imports()
+        self.check_dynamic_imports()
+        self.check_useEffect_fetching()
+        self.check_missing_memoization()
+        self.check_image_optimization()
+
+        self.generate_report()
+
+
+def main():
+    import sys
+
+    if len(sys.argv) < 2:
+        print("Usage: python react_performance_checker.py <project_path>")
+        sys.exit(1)
+
+    project_path = sys.argv[1]
+
+    if not os.path.exists(project_path):
+        print(f"[ERROR] Path not found: {project_path}")
+        sys.exit(1)
+
+    checker = PerformanceChecker(project_path)
+    checker.run()
+
+
+if __name__ == '__main__':
+    main()

package/templates/skills/optional/nodejs-best-practices/SKILL.md

@@ -0,0 +1,333 @@
+---
+name: nodejs-best-practices
+description: Node.js development principles and decision-making. Framework selection, async patterns, security, and architecture. Teaches thinking, not copying.
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# Node.js Best Practices
+
+> Principles and decision-making for Node.js development in 2025.
+> **Learn to THINK, not memorize code patterns.**
+
+---
+
+## ⚠️ How to Use This Skill
+
+This skill teaches **decision-making principles**, not fixed code to copy.
+
+- ASK user for preferences when unclear
+- Choose framework/pattern based on CONTEXT
+- Don't default to same solution every time
+
+---
+
+## 1. Framework Selection (2025)
+
+### Decision Tree
+
+```
+What are you building?
+│
+├── Edge/Serverless (Cloudflare, Vercel)
+│   └── Hono (zero-dependency, ultra-fast cold starts)
+│
+├── High Performance API
+│   └── Fastify (2-3x faster than Express)
+│
+├── Enterprise/Team familiarity
+│   └── NestJS (structured, DI, decorators)
+│
+├── Legacy/Stable/Maximum ecosystem
+│   └── Express (mature, most middleware)
+│
+└── Full-stack with frontend
+    └── Next.js API Routes or tRPC
+```
+
+### Comparison Principles
+
+| Factor | Hono | Fastify | Express |
+|--------|------|---------|---------|
+| **Best for** | Edge, serverless | Performance | Legacy, learning |
+| **Cold start** | Fastest | Fast | Moderate |
+| **Ecosystem** | Growing | Good | Largest |
+| **TypeScript** | Native | Excellent | Good |
+| **Learning curve** | Low | Medium | Low |
+
+### Selection Questions to Ask:
+1. What's the deployment target?
+2. Is cold start time critical?
+3. Does team have existing experience?
+4. Is there legacy code to maintain?
+
+---
+
+## 2. Runtime Considerations (2025)
+
+### Native TypeScript
+
+```
+Node.js 22+: --experimental-strip-types
+├── Run .ts files directly
+├── No build step needed for simple projects
+└── Consider for: scripts, simple APIs
+```
+
+### Module System Decision
+
+```
+ESM (import/export)
+├── Modern standard
+├── Better tree-shaking
+├── Async module loading
+└── Use for: new projects
+
+CommonJS (require)
+├── Legacy compatibility
+├── More npm packages support
+└── Use for: existing codebases, some edge cases
+```
+
+### Runtime Selection
+
+| Runtime | Best For |
+|---------|----------|
+| **Node.js** | General purpose, largest ecosystem |
+| **Bun** | Performance, built-in bundler |
+| **Deno** | Security-first, built-in TypeScript |
+
+---
+
+## 3. Architecture Principles
+
+### Layered Structure Concept
+
+```
+Request Flow:
+│
+├── Controller/Route Layer
+│   ├── Handles HTTP specifics
+│   ├── Input validation at boundary
+│   └── Calls service layer
+│
+├── Service Layer
+│   ├── Business logic
+│   ├── Framework-agnostic
+│   └── Calls repository layer
+│
+└── Repository Layer
+    ├── Data access only
+    ├── Database queries
+    └── ORM interactions
+```
+
+### Why This Matters:
+- **Testability**: Mock layers independently
+- **Flexibility**: Swap database without touching business logic
+- **Clarity**: Each layer has single responsibility
+
+### When to Simplify:
+- Small scripts → Single file OK
+- Prototypes → Less structure acceptable
+- Always ask: "Will this grow?"
+
+---
+
+## 4. Error Handling Principles
+
+### Centralized Error Handling
+
+```
+Pattern:
+├── Create custom error classes
+├── Throw from any layer
+├── Catch at top level (middleware)
+└── Format consistent response
+```
+
+### Error Response Philosophy
+
+```
+Client gets:
+├── Appropriate HTTP status
+├── Error code for programmatic handling
+├── User-friendly message
+└── NO internal details (security!)
+
+Logs get:
+├── Full stack trace
+├── Request context
+├── User ID (if applicable)
+└── Timestamp
+```
+
+### Status Code Selection
+
+| Situation | Status | When |
+|-----------|--------|------|
+| Bad input | 400 | Client sent invalid data |
+| No auth | 401 | Missing or invalid credentials |
+| No permission | 403 | Valid auth, but not allowed |
+| Not found | 404 | Resource doesn't exist |
+| Conflict | 409 | Duplicate or state conflict |
+| Validation | 422 | Schema valid but business rules fail |
+| Server error | 500 | Our fault, log everything |
+
+---
+
+## 5. Async Patterns Principles
+
+### When to Use Each
+
+| Pattern | Use When |
+|---------|----------|
+| `async/await` | Sequential async operations |
+| `Promise.all` | Parallel independent operations |
+| `Promise.allSettled` | Parallel where some can fail |
+| `Promise.race` | Timeout or first response wins |
+
+### Event Loop Awareness
+
+```
+I/O-bound (async helps):
+├── Database queries
+├── HTTP requests
+├── File system
+└── Network operations
+
+CPU-bound (async doesn't help):
+├── Crypto operations
+├── Image processing
+├── Complex calculations
+└── → Use worker threads or offload
+```
+
+### Avoiding Event Loop Blocking
+
+- Never use sync methods in production (fs.readFileSync, etc.)
+- Offload CPU-intensive work
+- Use streaming for large data
+
+---
+
+## 6. Validation Principles
+
+### Validate at Boundaries
+
+```
+Where to validate:
+├── API entry point (request body/params)
+├── Before database operations
+├── External data (API responses, file uploads)
+└── Environment variables (startup)
+```
+
+### Validation Library Selection
+
+| Library | Best For |
+|---------|----------|
+| **Zod** | TypeScript first, inference |
+| **Valibot** | Smaller bundle (tree-shakeable) |
+| **ArkType** | Performance critical |
+| **Yup** | Existing React Form usage |
+
+### Validation Philosophy
+
+- Fail fast: Validate early
+- Be specific: Clear error messages
+- Don't trust: Even "internal" data
+
+---
+
+## 7. Security Principles
+
+### Security Checklist (Not Code)
+
+- [ ] **Input validation**: All inputs validated
+- [ ] **Parameterized queries**: No string concatenation for SQL
+- [ ] **Password hashing**: bcrypt or argon2
+- [ ] **JWT verification**: Always verify signature and expiry
+- [ ] **Rate limiting**: Protect from abuse
+- [ ] **Security headers**: Helmet.js or equivalent
+- [ ] **HTTPS**: Everywhere in production
+- [ ] **CORS**: Properly configured
+- [ ] **Secrets**: Environment variables only
+- [ ] **Dependencies**: Regularly audited
+
+### Security Mindset
+
+```
+Trust nothing:
+├── Query params → validate
+├── Request body → validate
+├── Headers → verify
+├── Cookies → validate
+├── File uploads → scan
+└── External APIs → validate response
+```
+
+---
+
+## 8. Testing Principles
+
+### Test Strategy Selection
+
+| Type | Purpose | Tools |
+|------|---------|-------|
+| **Unit** | Business logic | node:test, Vitest |
+| **Integration** | API endpoints | Supertest |
+| **E2E** | Full flows | Playwright |
+
+### What to Test (Priorities)
+
+1. **Critical paths**: Auth, payments, core business
+2. **Edge cases**: Empty inputs, boundaries
+3. **Error handling**: What happens when things fail?
+4. **Not worth testing**: Framework code, trivial getters
+
+### Built-in Test Runner (Node.js 22+)
+
+```
+node --test src/**/*.test.ts
+├── No external dependency
+├── Good coverage reporting
+└── Watch mode available
+```
+
+---
+
+## 10. Anti-Patterns to Avoid
+
+### ❌ DON'T:
+- Use Express for new edge projects (use Hono)
+- Use sync methods in production code
+- Put business logic in controllers
+- Skip input validation
+- Hardcode secrets
+- Trust external data without validation
+- Block event loop with CPU work
+
+### ✅ DO:
+- Choose framework based on context
+- Ask user for preferences when unclear
+- Use layered architecture for growing projects
+- Validate all inputs
+- Use environment variables for secrets
+- Profile before optimizing
+
+---
+
+## 11. Decision Checklist
+
+Before implementing:
+
+- [ ] **Asked user about stack preference?**
+- [ ] **Chosen framework for THIS context?** (not just default)
+- [ ] **Considered deployment target?**
+- [ ] **Planned error handling strategy?**
+- [ ] **Identified validation points?**
+- [ ] **Considered security requirements?**
+
+---
+
+> **Remember**: Node.js best practices are about decision-making, not memorizing patterns. Every project deserves fresh consideration based on its requirements.