@sylphx/flow 0.2.1 → 0.2.3

package/dist/assets/knowledge/stacks/node-api.md

@@ -0,0 +1,220 @@
+---
+name: Node.js API
+description: Express/Fastify, REST/GraphQL, authentication, middleware, error handling
+---
+
+# Backend API Development
+
+## REST Structure
+
+```
+GET    /users              List
+POST   /users              Create
+GET    /users/:id          Get
+PATCH  /users/:id          Update
+DELETE /users/:id          Delete
+GET    /users/:id/posts    Nested
+```
+
+**Status**: 200 OK, 201 Created, 204 No Content, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 500 Internal Server Error
+
+**Response format (project standard):**
+```json
+{ "data": {...}, "meta": {...} }
+{ "items": [...], "total": 100, "page": 1, "limit": 20 }
+{ "error": { "code": "VALIDATION_ERROR", "message": "...", "field": "..." } }
+```
+
+## N+1 Problem
+
+```javascript
+// BAD - N+1 queries
+for (user of users) { user.posts = await getPosts(user.id) }
+
+// GOOD - Join
+await db.users.findMany({ include: { posts: true } })
+
+// GOOD - Batch fetch
+const userIds = users.map(u => u.id)
+const posts = await db.posts.findMany({ where: { userId: { in: userIds } } })
+
+// GraphQL: DataLoader
+const loader = new DataLoader(async (ids) => {
+  const items = await db.find({ where: { id: { in: ids } } })
+  return ids.map(id => items.filter(i => i.parentId === id))
+})
+```
+
+## Database
+
+**Connection pooling:**
+```javascript
+const pool = new Pool({ max: 20, idleTimeoutMillis: 30000 })
+```
+
+**Caching pattern:**
+```javascript
+async function getUser(id) {
+  const cached = await redis.get(`user:${id}`)
+  if (cached) return JSON.parse(cached)
+
+  const user = await db.users.findUnique({ where: { id } })
+  await redis.set(`user:${id}`, JSON.stringify(user), 'EX', 3600)
+  return user
+}
+
+// Invalidate on update
+async function updateUser(id, data) {
+  const user = await db.users.update({ where: { id }, data })
+  await redis.del(`user:${id}`)
+  return user
+}
+```
+
+## Authentication
+
+**Session vs Token:**
+- Session: Traditional web apps, need fine-grained control
+- Token (JWT): SPAs, mobile apps, microservices
+
+**JWT middleware (project standard):**
+```javascript
+function requireAuth(req, res, next) {
+  const token = req.headers.authorization?.split(' ')[1]
+  if (!token) return res.status(401).json({ error: { code: 'NO_TOKEN' } })
+
+  try {
+    req.userId = jwt.verify(token, process.env.JWT_SECRET).userId
+    next()
+  } catch {
+    res.status(401).json({ error: { code: 'INVALID_TOKEN' } })
+  }
+}
+```
+
+**Authorization patterns:**
+```javascript
+// Role check
+function requireRole(...roles) {
+  return async (req, res, next) => {
+    const user = await db.users.findUnique({ where: { id: req.userId } })
+    if (!roles.includes(user.role)) {
+      return res.status(403).json({ error: { code: 'FORBIDDEN' } })
+    }
+    next()
+  }
+}
+
+// Ownership check
+function requireOwnership(getter) {
+  return async (req, res, next) => {
+    const resource = await getter(req)
+    if (resource.userId !== req.userId) {
+      return res.status(403).json({ error: { code: 'NOT_OWNER' } })
+    }
+    next()
+  }
+}
+```
+
+## Error Handling
+
+**Project standard:**
+```javascript
+class ApiError extends Error {
+  constructor(statusCode, code, message) {
+    super(message)
+    this.statusCode = statusCode
+    this.code = code
+    this.isOperational = true
+  }
+}
+
+// Error middleware (last!)
+app.use((err, req, res, next) => {
+  if (err.isOperational) {
+    return res.status(err.statusCode).json({
+      error: { code: err.code, message: err.message }
+    })
+  }
+
+  console.error('PROGRAMMER ERROR:', err)
+  res.status(500).json({ error: { code: 'INTERNAL_ERROR' } })
+})
+
+// Usage
+if (!user) throw new ApiError(404, 'NOT_FOUND', 'User not found')
+```
+
+## Performance
+
+**Targets**: DB < 100ms, API < 200ms
+
+**Optimize:**
+- N+1 → Joins / DataLoader
+- Connection pooling
+- Redis caching
+- Job queues (background tasks)
+- Pagination (always LIMIT)
+
+## GraphQL Basics
+
+**When**: Complex relationships, flexible queries
+**vs REST**: Simple CRUD → REST
+
+**DataLoader (required for N+1):**
+```javascript
+const postLoader = new DataLoader(async (userIds) => {
+  const posts = await db.posts.findMany({ where: { userId: { in: userIds } } })
+  return userIds.map(id => posts.filter(p => p.userId === id))
+})
+
+// In resolver
+User: {
+  posts: (user) => postLoader.load(user.id)
+}
+```
+
+## Common Patterns
+
+**Repository:**
+```javascript
+class UserRepo {
+  findById(id) { return db.users.findUnique({ where: { id } }) }
+  save(data) { return db.users.create({ data }) }
+}
+```
+
+**Service:**
+```javascript
+class UserService {
+  async createUser(data) {
+    if (!data.email) throw new Error('Email required')
+    return await this.repo.save(data)
+  }
+}
+```
+
+**Middleware chain:**
+```javascript
+app.use(cors())
+app.use(express.json())
+app.use(rateLimit())
+app.use(auth())
+app.use(errorHandler()) // Last!
+```
+
+## Best Practices
+
+✅ Prepared statements (prevent injection)
+✅ Connection pooling
+✅ Index foreign keys
+✅ Rate limit auth endpoints
+✅ Hash passwords (bcrypt/argon2)
+✅ HTTPS only
+✅ Validate server-side
+
+❌ SQL injection (string concat)
+❌ Plain text passwords
+❌ N+1 queries
+❌ No error handling

package/dist/assets/knowledge/stacks/react-app.md

@@ -0,0 +1,232 @@
+---
+name: React Application
+description: React patterns, hooks, state management, performance, common bugs and fixes
+---
+
+# React Development
+
+## State Management Decision Tree
+```
+Used by 3+ unrelated components?
+├─ NO → useState in common ancestor
+└─ YES → Server data?
+    ├─ YES → React Query/SWR (not state!)
+    └─ NO → Complex actions?
+        ├─ YES → useReducer / Zustand
+        └─ NO → Context API
+```
+
+## Common Bugs & Fixes
+
+### Infinite useEffect Loop
+
+**Object/array deps:**
+```javascript
+// BAD
+useEffect(() => { fetch(users) }, [users])
+
+// FIX
+useEffect(() => { fetch(users) }, [userIds.join(',')])  // Primitive
+```
+
+**Unconditional state update:**
+```javascript
+// BAD
+useEffect(() => { setCount(count + 1) }, [count])
+
+// FIX
+useEffect(() => {
+  if (condition && count < max) setCount(count + 1)
+}, [count, condition, max])
+```
+
+### Stale Closure
+
+```javascript
+// BAD - uses initial count
+const [count, setCount] = useState(0)
+useEffect(() => {
+  setInterval(() => setCount(count + 1), 1000)
+}, [])
+
+// FIX: Functional update
+setInterval(() => setCount(c => c + 1), 1000)
+
+// FIX: useRef (complex cases)
+const countRef = useRef(count)
+useEffect(() => { countRef.current = count })
+useEffect(() => {
+  setInterval(() => setCount(countRef.current + 1), 1000)
+}, [])
+```
+
+### Missing Cleanup
+
+```javascript
+// BAD
+useEffect(() => {
+  subscribeToData(setData)
+}, [])
+
+// GOOD
+useEffect(() => {
+  const unsubscribe = subscribeToData(setData)
+  return () => unsubscribe()
+}, [])
+```
+
+## Performance
+
+**Optimize when:**
+- Profiler shows slowness
+- User-visible lag
+- 100+ renders/second
+
+**Profile first, optimize second.**
+
+### Unnecessary Re-renders
+
+```javascript
+// BAD
+function Parent() {
+  const config = { theme: 'dark' }
+  return <Child config={config} />
+}
+
+// GOOD
+const config = useMemo(() => ({ theme: 'dark' }), [])
+```
+
+**Order:**
+1. Fix parent
+2. useMemo/useCallback
+3. Profile
+4. React.memo (last resort)
+
+### Virtualization
+
+**When**: 500+ items, laggy scroll
+
+```javascript
+import { FixedSizeList } from 'react-window'
+<FixedSizeList height={600} itemCount={items.length} itemSize={35}>
+  {({ index, style }) => <div style={style}>{items[index]}</div>}
+</FixedSizeList>
+```
+
+### Debounce Search
+
+```javascript
+const debouncedQuery = useDebounce(query, 300)
+useEffect(() => {
+  if (debouncedQuery) searchAPI(debouncedQuery)
+}, [debouncedQuery])
+```
+
+## Data Fetching
+
+**Never** useState for server data. You lose: caching, loading, errors, refetching, race conditions.
+
+**Use React Query:**
+```javascript
+const { data, isLoading, error } = useQuery({
+  queryKey: ['users'],
+  queryFn: () => fetch('/api/users').then(r => r.json())
+})
+
+const mutation = useMutation({
+  mutationFn: (user) => fetch('/api/users', { method: 'POST', body: JSON.stringify(user) }),
+  onSuccess: () => queryClient.invalidateQueries(['users'])
+})
+```
+
+## Forms
+
+**React Hook Form** (recommended):
+```javascript
+const { register, handleSubmit, formState: { errors } } = useForm()
+
+<form onSubmit={handleSubmit(onSubmit)}>
+  <input {...register('email', {
+    required: 'Required',
+    pattern: { value: /^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}$/i }
+  })} />
+  {errors.email && <span>{errors.email.message}</span>}
+</form>
+```
+
+**Controlled vs Uncontrolled:**
+- Controlled: Validation on change, dependent fields
+- Uncontrolled: Simple submit, file inputs
+
+## Accessibility
+
+**Critical:**
+1. Semantic HTML (`<button>` not `<div onClick>`)
+2. Alt text (meaningful or `alt=""`)
+3. Form labels (every input)
+4. Keyboard nav (Tab, Enter/Space)
+5. Focus visible
+
+**Test**: VoiceOver (Cmd+F5), Tab through app
+
+```javascript
+// BAD
+<div onClick={handleClick}>Click</div>
+
+// GOOD
+<button onClick={handleClick}>Click</button>
+```
+
+## Debug Workflow
+
+**Component not updating:**
+1. State changing? (console.log)
+2. setState called?
+3. Mutating state? (must create new)
+4. Memoized with stale props?
+
+**Performance:**
+1. Profile (React DevTools)
+2. Identify slow component
+3. Check: Unnecessary re-renders?
+4. Check: Expensive computation?
+5. Optimize bottleneck only
+
+## Production Patterns
+
+**Error Boundary:**
+```javascript
+class ErrorBoundary extends React.Component {
+  state = { hasError: false }
+  static getDerivedStateFromError() { return { hasError: true } }
+  componentDidCatch(error, info) { logError(error, info) }
+  render() {
+    return this.state.hasError ? <ErrorFallback /> : this.props.children
+  }
+}
+```
+
+**Code Splitting:**
+```javascript
+const Dashboard = lazy(() => import('./Dashboard'))
+<Suspense fallback={<Loading />}>
+  <Dashboard />
+</Suspense>
+```
+
+## Key Decisions
+
+**State unclear?** → useState, refactor later
+**Performance slow?** → Profile first
+**Form complex?** → React Hook Form
+**Data fetching?** → React Query
+**Not sure?** → Simpler option
+
+## Anti-Patterns
+
+❌ Server data in useState
+❌ Premature optimization
+❌ React.memo everywhere
+❌ Missing cleanup
+❌ Div as button

package/dist/assets/knowledge/universal/deployment.md

@@ -0,0 +1,109 @@
+---
+name: Deployment & DevOps
+description: Docker, CI/CD, monitoring, scaling, infrastructure
+---
+
+# Deployment & DevOps
+
+## Deployment Strategies
+
+**Blue-Green**: Two environments (blue=current, green=new) → test → switch. Zero downtime, instant rollback, 2x cost.
+
+**Rolling**: Replace gradually (10% at a time). No extra infrastructure, lower risk, slower.
+
+**Canary**: Route small % to new version. Test in production, minimal risk, complex routing.
+
+**Feature Flags**: Deploy code disabled, enable via config. Decouple deploy from release, A/B testing, kill switches.
+
+## CI/CD Pipeline
+
+### Continuous Integration (On Every Commit)
+1. Run linter
+2. Run tests (unit, integration)
+3. Build application
+4. Security scanning
+5. Code quality checks
+
+**Best practices**: Fast feedback (< 10min), fail fast, keep builds green
+
+### Continuous Deployment
+**Stages**: CI passes → deploy staging → E2E tests → deploy production → health checks → rollback if failed
+
+**Tools**: GitHub Actions, GitLab CI, Jenkins, CircleCI
+
+## Containerization (Docker)
+
+### Best Practices
+- Multi-stage builds (build → slim runtime)
+- Slim/alpine images
+- Layer caching (deps before code)
+- .dockerignore
+- Don't run as root
+
+## Orchestration (Kubernetes)
+
+**Core**: Pod (containers), Deployment (replicas), Service (load balancer), Ingress (routing), ConfigMap (config), Secret (sensitive)
+
+**Scaling**:
+- Horizontal Pod Autoscaler: Scale based on CPU/memory, min/max replicas
+- Cluster Autoscaler: Add/remove nodes
+
+## Monitoring & Observability
+
+### Logs
+**Structured logging**: JSON format with level, timestamp, message, context (user_id, trace_id)
+
+**Centralized**: ELK, Datadog, CloudWatch
+**Best practices**: Log errors with context, trace IDs, don't log secrets, set retention
+
+### Metrics
+**Track**: Request rate, error rate, response time (latency), resource usage (CPU, memory, disk)
+**Tools**: Prometheus, Grafana, Datadog
+
+### Tracing
+**Distributed tracing**: Track requests across services, identify bottlenecks
+**Tools**: Jaeger, Zipkin, Datadog APM
+
+### Alerting
+**Alert on**: Error rate > threshold, response time > SLA, resource exhaustion, service down
+**Best practices**: Actionable only, include runbooks, escalation policies, on-call rotation
+
+## High Availability
+
+### Load Balancing
+**Algorithms**: Round robin (equal), least connections (least busy), IP hash (consistent)
+**Health checks**: HTTP (/_health), TCP, check every 10-30s, remove unhealthy
+
+### Database Replication
+**Primary-Replica**: Writes to primary, reads from replicas, async (eventual consistency)
+**Multi-Primary**: Write to any, conflict resolution needed, complex but highly available
+
+### Backup & Disaster Recovery
+**Backups**: Automated daily, retention (7 days, 4 weeks, 12 months), test restores, offsite/cross-region
+**RTO/RPO**: RTO (recovery time), RPO (data loss acceptable)
+
+## Security
+
+**Network**: Firewall (whitelist), private subnets for DBs, VPN for internal, DDoS protection
+**Secrets**: Never commit to git, use secret managers (AWS Secrets Manager, Vault), rotate regularly, least privilege
+**SSL/TLS**: HTTPS everywhere, auto-renewal (Let's Encrypt), strong ciphers, HSTS headers
+**Compliance**: Encryption at rest, encryption in transit, access logs, security audits
+
+## Cost Optimization
+
+**Right-sizing**: Monitor usage, scale down over-provisioned, spot/preemptible for non-critical
+**Auto-scaling**: Scale down off-peak, scale up peak
+**Reserved Instances**: 1-3 year commit for 30-70% discount (predictable workloads)
+**Storage**: Lifecycle policies (move old to cheaper), delete unused, compress backups
+
+## Common Patterns
+
+**Immutable Infrastructure**: Never modify servers, deploy new, terminate old
+**Infrastructure as Code**: Terraform, CloudFormation, Pulumi → version controlled, reproducible
+**GitOps**: Git as truth, auto-deploy on merge, drift detection (ArgoCD, Flux)
+
+## Best Practices
+
+**Documentation**: Runbooks, architecture diagrams, incident response, on-call guides
+**Change Management**: Review process, deployment windows, rollback procedures, communication
+**Incident Response**: Detect → Triage → Mitigate → Resolve → Post-mortem

package/dist/assets/knowledge/universal/performance.md

@@ -0,0 +1,121 @@
+---
+name: Performance Optimization
+description: Profiling, caching, optimization patterns across frontend and backend
+---
+
+# Performance Optimization
+
+## Measure First
+
+**Never optimize without measuring.**
+
+### Tools
+**Frontend**: Chrome DevTools, Lighthouse, React Profiler
+**Backend**: APM (New Relic, Datadog), query explain plans
+
+### Metrics
+**Frontend**: FCP < 1.8s, LCP < 2.5s, CLS < 0.1, FID < 100ms, TTI < 3.5s
+**Backend**: Response < 200ms (p95), error rate < 1%, DB query < 100ms
+
+## Frontend Optimization
+
+### Bundle Size
+**Analyze**: webpack-bundle-analyzer
+**Reduce**: Tree-shaking, code splitting, lighter alternatives, remove unused deps
+
+### Loading Strategy
+1. Inline critical CSS
+2. Defer non-critical CSS
+3. Async non-critical JS
+4. Lazy load below-fold images
+5. Code splitting: `lazy(() => import('./Heavy'))`
+
+### Images
+- WebP format (smaller, better quality)
+- Responsive (srcset)
+- Lazy loading (loading="lazy")
+- CDN delivery
+- Optimize: compress, resize, correct format
+
+### Caching
+**Browser**: Cache-Control headers, versioned assets (hash), service worker
+**CDN**: Static assets, edge caching, geographic distribution
+
+## React Performance
+
+### Avoid Re-renders
+**Identify**: React DevTools Profiler, "Why did you render" library
+
+**Fix**: React.memo (pure components), useMemo (expensive computations), useCallback (function props), move static data outside component
+
+### Virtualization
+**Problem**: 10,000+ items
+**Solution**: react-window / react-virtualized (render only visible)
+
+### Debounce/Throttle
+- **Debounce**: Wait for user to stop (search input)
+- **Throttle**: Limit frequency (scroll handler)
+
+## Backend Performance
+
+### Database Optimization
+
+**Indexes**: Index WHERE/JOIN/ORDER BY columns, composite for multi-column, don't over-index (slows writes)
+
+**Queries**: EXPLAIN to analyze, avoid SELECT *, LIMIT for pagination, connection pooling, batch operations
+
+**N+1 Problem**: See sql.md for patterns
+
+### Caching Strategy
+
+**What**: Query results, API responses, computed values, sessions
+**Invalidation**: Time-based (TTL), event-based (on update), hybrid
+**Layers**: App memory (fastest) → Redis → DB cache → CDN
+
+### Async Processing
+
+**Background**: Email, image processing, reports, aggregation
+**Tools**: Job queues (Bull, BullMQ), message queues (RabbitMQ, Kafka), serverless
+
+### Response Time
+- Gzip compression
+- HTTP/2 multiplexing
+- Keep-alive connections
+- Parallel requests
+
+## Database Performance
+
+### Connection Management
+- Connection pooling (reuse)
+- Configure pool size
+- Monitor usage
+- Close idle connections
+
+### Query Performance
+**Slow query log**: Identify > 100ms, add indexes, rewrite, consider denormalization
+
+**Pagination**: See sql.md for cursor-based vs offset patterns
+
+### Scaling
+**Vertical**: Bigger server (limited)
+**Horizontal**: Read replicas (scale reads), sharding (partition data), DB-per-service
+
+## Monitoring
+
+**Frontend**: RUM, synthetic monitoring, Core Web Vitals, error tracking (Sentry)
+**Backend**: APM, log aggregation (ELK, Datadog), alerting, distributed tracing
+
+**Continuous**:
+1. Set budgets
+2. Monitor metrics
+3. Alert on regression
+4. Profile bottlenecks
+5. Optimize
+6. Measure impact
+
+## Common Pitfalls
+
+❌ **Premature optimization**: Optimize AFTER measuring, focus on biggest bottlenecks, 80/20 rule
+❌ **Over-caching**: Invalidation is hard, stale data bugs, memory limits → Cache stable, expensive data only
+❌ **Ignoring network**: Minimize requests, reduce payload, use HTTP/2, consider latency
+❌ **Blocking operations**: Never block event loop (Node), use async for I/O, worker threads for CPU tasks