@cubis/foundry 0.3.64 → 0.3.65

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/nextjs-react-expert/docs/8-advanced-advanced-patterns.md

@@ -0,0 +1,150 @@
+# 8. Advanced Patterns
+
+> **Impact:** VARIABLE
+> **Focus:** Advanced patterns for specific cases that require careful implementation.
+
+---
+
+## Overview
+
+This section contains **3 rules** focused on advanced patterns.
+
+---
+
+## Rule 8.1: Initialize App Once, Not Per Mount
+
+**Impact:** LOW-MEDIUM  
+**Tags:** initialization, useEffect, app-startup, side-effects  
+
+## Initialize App Once, Not Per Mount
+
+Do not put app-wide initialization that must run once per app load inside `useEffect([])` of a component. Components can remount and effects will re-run. Use a module-level guard or top-level init in the entry module instead.
+
+**Incorrect (runs twice in dev, re-runs on remount):**
+
+```tsx
+function Comp() {
+  useEffect(() => {
+    loadFromStorage()
+    checkAuthToken()
+  }, [])
+
+  // ...
+}
+```
+
+**Correct (once per app load):**
+
+```tsx
+let didInit = false
+
+function Comp() {
+  useEffect(() => {
+    if (didInit) return
+    didInit = true
+    loadFromStorage()
+    checkAuthToken()
+  }, [])
+
+  // ...
+}
+```
+
+Reference: [Initializing the application](https://react.dev/learn/you-might-not-need-an-effect#initializing-the-application)
+
+---
+
+## Rule 8.2: Store Event Handlers in Refs
+
+**Impact:** LOW  
+**Tags:** advanced, hooks, refs, event-handlers, optimization  
+
+## Store Event Handlers in Refs
+
+Store callbacks in refs when used in effects that shouldn't re-subscribe on callback changes.
+
+**Incorrect (re-subscribes on every render):**
+
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+  useEffect(() => {
+    window.addEventListener(event, handler)
+    return () => window.removeEventListener(event, handler)
+  }, [event, handler])
+}
+```
+
+**Correct (stable subscription):**
+
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+  const handlerRef = useRef(handler)
+  useEffect(() => {
+    handlerRef.current = handler
+  }, [handler])
+
+  useEffect(() => {
+    const listener = (e) => handlerRef.current(e)
+    window.addEventListener(event, listener)
+    return () => window.removeEventListener(event, listener)
+  }, [event])
+}
+```
+
+**Alternative: use `useEffectEvent` if you're on latest React:**
+
+```tsx
+import { useEffectEvent } from 'react'
+
+function useWindowEvent(event: string, handler: (e) => void) {
+  const onEvent = useEffectEvent(handler)
+
+  useEffect(() => {
+    window.addEventListener(event, onEvent)
+    return () => window.removeEventListener(event, onEvent)
+  }, [event])
+}
+```
+
+`useEffectEvent` provides a cleaner API for the same pattern: it creates a stable function reference that always calls the latest version of the handler.
+
+---
+
+## Rule 8.3: useEffectEvent for Stable Callback Refs
+
+**Impact:** LOW  
+**Tags:** advanced, hooks, useEffectEvent, refs, optimization  
+
+## useEffectEvent for Stable Callback Refs
+
+Access latest values in callbacks without adding them to dependency arrays. Prevents effect re-runs while avoiding stale closures.
+
+**Incorrect (effect re-runs on every callback change):**
+
+```tsx
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState('')
+
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearch(query), 300)
+    return () => clearTimeout(timeout)
+  }, [query, onSearch])
+}
+```
+
+**Correct (using React's useEffectEvent):**
+
+```tsx
+import { useEffectEvent } from 'react';
+
+function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
+  const [query, setQuery] = useState('')
+  const onSearchEvent = useEffectEvent(onSearch)
+
+  useEffect(() => {
+    const timeout = setTimeout(() => onSearchEvent(query), 300)
+    return () => clearTimeout(timeout)
+  }, [query])
+}
+```
+

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/nextjs-react-expert/scripts/convert_rules.py

@@ -0,0 +1,222 @@
+#!/usr/bin/env python3
+"""
+Conversion Script: React Best Practices → .agent Format
+Merges 59 individual rules into 8 grouped section files
+"""
+
+import os
+import re
+from pathlib import Path
+from typing import Dict, List, Tuple
+
+# Section metadata from _sections.md
+SECTIONS = {
+    'async': {
+        'number': 1,
+        'title': 'Eliminating Waterfalls',
+        'impact': 'CRITICAL',
+        'description': 'Waterfalls are the #1 performance killer. Each sequential await adds full network latency. Eliminating them yields the largest gains.'
+    },
+    'bundle': {
+        'number': 2,
+        'title': 'Bundle Size Optimization',
+        'impact': 'CRITICAL',
+        'description': 'Reducing initial bundle size improves Time to Interactive and Largest Contentful Paint.'
+    },
+    'server': {
+        'number': 3,
+        'title': 'Server-Side Performance',
+        'impact': 'HIGH',
+        'description': 'Optimizing server-side rendering and data fetching eliminates server-side waterfalls and reduces response times.'
+    },
+    'client': {
+        'number': 4,
+        'title': 'Client-Side Data Fetching',
+        'impact': 'MEDIUM-HIGH',
+        'description': 'Automatic deduplication and efficient data fetching patterns reduce redundant network requests.'
+    },
+    'rerender': {
+        'number': 5,
+        'title': 'Re-render Optimization',
+        'impact': 'MEDIUM',
+        'description': 'Reducing unnecessary re-renders minimizes wasted computation and improves UI responsiveness.'
+    },
+    'rendering': {
+        'number': 6,
+        'title': 'Rendering Performance',
+        'impact': 'MEDIUM',
+        'description': 'Optimizing the rendering process reduces the work the browser needs to do.'
+    },
+    'js': {
+        'number': 7,
+        'title': 'JavaScript Performance',
+        'impact': 'LOW-MEDIUM',
+        'description': 'Micro-optimizations for hot paths can add up to meaningful improvements.'
+    },
+    'advanced': {
+        'number': 8,
+        'title': 'Advanced Patterns',
+        'impact': 'VARIABLE',
+        'description': 'Advanced patterns for specific cases that require careful implementation.'
+    }
+}
+
+
+def parse_frontmatter(content: str) -> Tuple[Dict, str]:
+    """Parse markdown frontmatter and body"""
+    if not content.startswith('---'):
+        return {}, content
+
+    parts = content.split('---', 2)
+    if len(parts) < 3:
+        return {}, content
+
+    # Parse YAML frontmatter manually (simple key: value)
+    frontmatter = {}
+    for line in parts[1].strip().split('\n'):
+        if ':' in line:
+            key, value = line.split(':', 1)
+            frontmatter[key.strip()] = value.strip()
+
+    body = parts[2].strip()
+    return frontmatter, body
+
+
+def parse_rule_file(filepath: Path) -> Dict:
+    """Parse a single rule file"""
+    with open(filepath, 'r', encoding='utf-8') as f:
+        content = f.read()
+
+    frontmatter, body = parse_frontmatter(content)
+
+    # Extract prefix from filename
+    filename = filepath.stem
+    prefix = filename.split('-')[0]
+
+    return {
+        'filename': filepath.name,
+        'prefix': prefix,
+        'title': frontmatter.get('title', filename),
+        'impact': frontmatter.get('impact', ''),
+        'impactDescription': frontmatter.get('impactDescription', ''),
+        'tags': frontmatter.get('tags', ''),
+        'body': body,
+        'frontmatter': frontmatter
+    }
+
+
+def group_rules_by_section(rules_dir: Path) -> Dict[str, List[Dict]]:
+    """Group all rules by their section prefix"""
+    grouped = {prefix: [] for prefix in SECTIONS.keys()}
+
+    for rule_file in sorted(rules_dir.glob('*.md')):
+        # Skip special files
+        if rule_file.name.startswith('_'):
+            continue
+
+        rule = parse_rule_file(rule_file)
+        prefix = rule['prefix']
+
+        if prefix in grouped:
+            grouped[prefix].append(rule)
+        else:
+            print(f"[WARNING] Unknown prefix '{prefix}' in file: {rule_file.name}")
+
+    return grouped
+
+
+def generate_section_file(section_prefix: str, rules: List[Dict], output_dir: Path):
+    """Generate a merged section file"""
+    if not rules:
+        print(f"[WARNING] No rules found for section: {section_prefix}")
+        return
+
+    section_meta = SECTIONS[section_prefix]
+    section_num = section_meta['number']
+    section_title = section_meta['title']
+    impact = section_meta['impact']
+    description = section_meta['description']
+
+    # Sort rules by title
+    rules.sort(key=lambda r: r['title'])
+
+    # Build content
+    content = f"""# {section_num}. {section_title}
+
+> **Impact:** {impact}
+> **Focus:** {description}
+
+---
+
+## Overview
+
+This section contains **{len(rules)} rules** focused on {section_title.lower()}.
+
+"""
+
+    # Add each rule
+    for i, rule in enumerate(rules, 1):
+        rule_id = f"{section_num}.{i}"
+        title = rule['title']
+        rule_impact = rule['impact']
+        tags = rule['tags']
+        body = rule['body']
+
+        content += f"""---
+
+## Rule {rule_id}: {title}
+
+"""
+
+        if rule_impact:
+            content += f"**Impact:** {rule_impact}  \n"
+
+        if tags:
+            content += f"**Tags:** {tags}  \n"
+
+        content += f"\n{body}\n\n"
+
+    # Write file
+    output_file = output_dir / f"{section_num}-{section_prefix}-{section_title.lower().replace(' ', '-')}.md"
+    output_file.write_text(content, encoding='utf-8')
+    print(f"[OK] Generated: {output_file.name} ({len(rules)} rules)")
+
+
+def main():
+    """Main conversion function"""
+    # Paths
+    base_dir = Path(__file__).parent.parent.parent.parent.parent
+    rules_dir = base_dir / "others/agent-skills/skills/react-best-practices/rules"
+    output_dir = base_dir / ".agent/skills/react-best-practices"
+
+    print(f"[*] Reading rules from: {rules_dir}")
+    print(f"[*] Output to: {output_dir}")
+    print()
+
+    # Check if rules directory exists
+    if not rules_dir.exists():
+        print(f"[ERROR] Rules directory not found: {rules_dir}")
+        return
+
+    # Group rules
+    print("[*] Grouping rules by section...")
+    grouped_rules = group_rules_by_section(rules_dir)
+
+    # Stats
+    total_rules = sum(len(rules) for rules in grouped_rules.values())
+    print(f"[*] Found {total_rules} total rules")
+    print()
+
+    # Generate section files
+    print("[*] Generating section files...")
+    for section_prefix in SECTIONS.keys():
+        rules = grouped_rules[section_prefix]
+        generate_section_file(section_prefix, rules, output_dir)
+
+    print()
+    print("[SUCCESS] Conversion complete!")
+    print(f"[*] Generated 8 section files from {total_rules} rules")
+
+
+if __name__ == '__main__':
+    main()

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/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/workflows/workflows/agent-environment-setup/platforms/claude/skills/nodejs-best-practices/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: "nodejs-best-practices"
+description: "Decision framework for modern Node.js backend architecture, operations, and security using current LTS-era practices."
+license: MIT
+metadata:
+  version: "2.0.0"
+  domain: "backend"
+  role: "decision-guide"
+  stack: "nodejs"
+  baseline: "Node 22/24 LTS era"
+---
+
+# Node.js Best Practices
+
+## Purpose
+
+Use this skill to choose the right Node backend patterns for the actual constraints of the task, not by habit.
+
+## Decision flow
+
+1. Clarify deployment target (container, serverless, edge).
+2. Select framework/runtime shape based on latency and team constraints.
+3. Define API, validation, auth, and observability boundaries.
+4. Implement smallest safe slice, then harden.
+
+## Core guidance
+
+- Prefer typed boundaries (TypeScript + schema validation).
+- Keep transport concerns out of business logic.
+- Standardize error envelopes and correlation IDs.
+- Enforce timeout, retry, and circuit-breaker strategy for downstream calls.
+- Use graceful shutdown and health/readiness probes.
+
+## Security and reliability
+
+- Validate all request input before business logic.
+- Use least-privilege credentials and secret rotation.
+- Avoid blocking the event loop in request paths.
+- Add rate limits and abuse controls on external endpoints.
+
+## Performance
+
+- Measure before optimizing.
+- Profile CPU and heap in realistic workloads.
+- Use streaming/backpressure for large I/O paths.
+
+## Output expectation
+
+Return concrete architecture choices with tradeoffs, then implementation steps and verification criteria.