@girardmedia/bootspring 3.3.2 → 3.4.0

package/assets/skills/rag-patterns.md

@@ -0,0 +1,159 @@
+---
+name: rag-patterns
+description: Build retrieval-augmented generation systems with chunking, embeddings, vector stores, hybrid search, and evaluation.
+---
+
+# RAG Patterns
+
+## When to Use
+
+Apply when your LLM needs access to private data, documents, or knowledge that
+isn't in its training set. RAG is the right choice when fine-tuning is too
+expensive or when the source data changes frequently.
+
+## How It Works
+
+### 1. Chunking Strategies
+
+Split documents into chunks that preserve semantic meaning. Chunk size directly
+impacts retrieval quality.
+
+```typescript
+// Fixed-size with overlap — simple baseline
+function chunkFixed(text: string, size = 512, overlap = 64): string[] {
+  const chunks: string[] = [];
+  for (let i = 0; i < text.length; i += size - overlap) {
+    chunks.push(text.slice(i, i + size));
+  }
+  return chunks;
+}
+
+// Recursive character splitting — respects document structure
+// Split on paragraphs first, then sentences, then words
+const separators = ['\n\n', '\n', '. ', ' '];
+
+// Semantic chunking — group sentences by embedding similarity
+// 1. Embed each sentence
+// 2. Compute cosine similarity between adjacent sentences
+// 3. Split where similarity drops below threshold (e.g., 0.75)
+```
+
+Rules of thumb: 256-512 tokens for precise retrieval, 1024+ for broader context.
+Always include overlap (10-20%) to avoid splitting mid-concept.
+
+### 2. Embedding Models
+
+| Model | Dimensions | Speed | Quality | Cost |
+|-------|-----------|-------|---------|------|
+| `text-embedding-3-small` | 1536 | Fast | Good | $0.02/1M tokens |
+| `text-embedding-3-large` | 3072 | Medium | Best | $0.13/1M tokens |
+| `voyage-3` | 1024 | Fast | Excellent | $0.06/1M tokens |
+| `nomic-embed-text` (local) | 768 | Varies | Good | Free |
+
+Normalize embeddings before storing. Use Matryoshka dimensions (OpenAI) to
+reduce storage — 256d retains ~95% quality of full 1536d.
+
+### 3. Vector Store Selection
+
+```typescript
+// Pinecone — managed, scales to billions
+import { Pinecone } from '@pinecone-database/pinecone';
+const index = pc.index('docs').namespace('v2');
+await index.upsert([{ id: 'chunk-1', values: embedding, metadata: { source } }]);
+
+// pgvector — runs in your existing Postgres
+// CREATE EXTENSION vector;
+// CREATE TABLE chunks (id serial, embedding vector(1536), content text);
+// CREATE INDEX ON chunks USING ivfflat (embedding vector_cosine_ops);
+
+// Chroma — local dev, easy to start
+import { ChromaClient } from 'chromadb';
+const collection = await client.getOrCreateCollection({ name: 'docs' });
+```
+
+Choose pgvector when you already run Postgres and have < 10M vectors. Use
+Pinecone/Qdrant for billion-scale or when you need managed infrastructure.
+
+### 4. Hybrid Search (Vector + Keyword)
+
+Pure vector search misses exact matches. Combine with BM25 for best results.
+
+```typescript
+async function hybridSearch(query: string, topK = 10) {
+  const [vectorResults, keywordResults] = await Promise.all([
+    vectorStore.similaritySearch(query, topK),
+    fullTextSearch(query, topK), // BM25 via Postgres ts_vector or Elasticsearch
+  ]);
+
+  // Reciprocal Rank Fusion — merges two ranked lists
+  const scores = new Map<string, number>();
+  const k = 60; // RRF constant
+  for (const [rank, doc] of vectorResults.entries()) {
+    scores.set(doc.id, (scores.get(doc.id) ?? 0) + 1 / (k + rank + 1));
+  }
+  for (const [rank, doc] of keywordResults.entries()) {
+    scores.set(doc.id, (scores.get(doc.id) ?? 0) + 1 / (k + rank + 1));
+  }
+
+  return [...scores.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, topK);
+}
+```
+
+### 5. Reranking
+
+Retrieve broadly (top 20-50), then rerank with a cross-encoder for precision.
+
+```typescript
+// Cohere reranker — best quality/cost trade-off
+const reranked = await cohere.rerank({
+  model: 'rerank-english-v3.0',
+  query,
+  documents: candidates.map(c => c.content),
+  topN: 5,
+});
+
+// Filter by relevance score threshold
+const relevant = reranked.results.filter(r => r.relevanceScore > 0.3);
+```
+
+### 6. Evaluation
+
+Measure retrieval quality before tuning generation.
+
+```typescript
+// Hit rate — does the correct chunk appear in top-K?
+// MRR (Mean Reciprocal Rank) — how high does it rank?
+// Faithfulness — does the LLM answer actually use the retrieved context?
+// Answer relevance — does the answer address the question?
+
+// RAGAS framework for automated evaluation
+// 1. Build a test set: 50-100 question/answer/context triples
+// 2. Run retrieval, measure hit@5 and MRR
+// 3. Run generation, score faithfulness and relevance with LLM-as-judge
+// 4. Track metrics per chunk strategy and model combination
+```
+
+## Examples
+
+| Problem | Pattern | Result |
+|---------|---------|--------|
+| Legal docs need exact clause matching | Hybrid search (BM25 + vector) | Catches both semantic and keyword matches |
+| Code documentation with mixed languages | Recursive chunking on markdown headers | Preserves code blocks intact |
+| Customer support over 100K articles | Retrieve 50, rerank to 5 | 3x precision vs. vector-only |
+| Answers hallucinate despite good retrieval | Add source citations in system prompt | User can verify, trust increases |
+| Embedding costs growing fast | Matryoshka 256d + cache embeddings | 6x storage reduction, minimal quality loss |
+
+## Checklist
+
+- [ ] Chunk size is tuned for your content type (not just default 512)
+- [ ] Chunks include metadata (source URL, section title, timestamp)
+- [ ] Overlap between chunks prevents mid-sentence splits
+- [ ] Hybrid search combines vector similarity with keyword matching
+- [ ] Reranker filters retrieval results before sending to LLM
+- [ ] System prompt instructs the model to cite sources and say "I don't know"
+- [ ] Evaluation set of 50+ question/context/answer triples exists
+- [ ] Hit rate and MRR are measured and tracked across changes
+- [ ] Embedding model choice is benchmarked, not assumed
+- [ ] Vector index uses appropriate type (IVFFlat for < 1M, HNSW for quality)

package/assets/skills/rate-limiting.md

@@ -0,0 +1,319 @@
+---
+name: rate-limiting
+description: Rate limiting patterns for token bucket, sliding window, Redis-backed distributed limits, per-user quotas, and response headers.
+---
+
+# Rate Limiting Patterns
+
+## When to Use
+Implement rate limiting to protect APIs from abuse, enforce usage quotas, ensure fair resource allocation, and prevent cascading failures. Apply rate limiting at the gateway level for global protection and at the route level for sensitive endpoints (login, payment, search). Choose the algorithm based on your needs: fixed window for simplicity, sliding window for accuracy, or token bucket for burst tolerance.
+
+## How It Works
+
+### Fixed Window Rate Limiter
+
+```typescript
+// src/rate-limiters/fixed-window.ts
+export class FixedWindowLimiter {
+  private windows = new Map<string, { count: number; resetAt: number }>();
+
+  constructor(
+    private readonly maxRequests: number,
+    private readonly windowMs: number,
+  ) {}
+
+  check(key: string): { allowed: boolean; remaining: number; resetAt: number } {
+    const now = Date.now();
+    const window = this.windows.get(key);
+
+    if (!window || now >= window.resetAt) {
+      const resetAt = now + this.windowMs;
+      this.windows.set(key, { count: 1, resetAt });
+      return { allowed: true, remaining: this.maxRequests - 1, resetAt };
+    }
+
+    if (window.count >= this.maxRequests) {
+      return { allowed: false, remaining: 0, resetAt: window.resetAt };
+    }
+
+    window.count++;
+    return { allowed: true, remaining: this.maxRequests - window.count, resetAt: window.resetAt };
+  }
+}
+```
+
+### Sliding Window Rate Limiter
+
+```typescript
+// src/rate-limiters/sliding-window.ts
+export class SlidingWindowLimiter {
+  private requests = new Map<string, number[]>();
+
+  constructor(
+    private readonly maxRequests: number,
+    private readonly windowMs: number,
+  ) {}
+
+  check(key: string): { allowed: boolean; remaining: number; retryAfterMs: number } {
+    const now = Date.now();
+    const windowStart = now - this.windowMs;
+
+    // Get or initialize timestamps
+    let timestamps = this.requests.get(key) ?? [];
+
+    // Remove expired timestamps
+    timestamps = timestamps.filter((t) => t > windowStart);
+
+    if (timestamps.length >= this.maxRequests) {
+      const oldestInWindow = timestamps[0];
+      const retryAfterMs = oldestInWindow + this.windowMs - now;
+      this.requests.set(key, timestamps);
+      return { allowed: false, remaining: 0, retryAfterMs };
+    }
+
+    timestamps.push(now);
+    this.requests.set(key, timestamps);
+
+    return {
+      allowed: true,
+      remaining: this.maxRequests - timestamps.length,
+      retryAfterMs: 0,
+    };
+  }
+}
+```
+
+### Token Bucket (Burst-Tolerant)
+
+```typescript
+// src/rate-limiters/token-bucket.ts
+export class TokenBucketLimiter {
+  private buckets = new Map<string, { tokens: number; lastRefill: number }>();
+
+  constructor(
+    private readonly capacity: number,
+    private readonly refillRate: number,  // tokens per second
+  ) {}
+
+  check(key: string, cost: number = 1): { allowed: boolean; remaining: number } {
+    const now = Date.now();
+    let bucket = this.buckets.get(key);
+
+    if (!bucket) {
+      bucket = { tokens: this.capacity, lastRefill: now };
+      this.buckets.set(key, bucket);
+    }
+
+    // Refill tokens based on elapsed time
+    const elapsed = (now - bucket.lastRefill) / 1000;
+    bucket.tokens = Math.min(this.capacity, bucket.tokens + elapsed * this.refillRate);
+    bucket.lastRefill = now;
+
+    if (bucket.tokens < cost) {
+      return { allowed: false, remaining: Math.floor(bucket.tokens) };
+    }
+
+    bucket.tokens -= cost;
+    return { allowed: true, remaining: Math.floor(bucket.tokens) };
+  }
+}
+
+// Usage: 100 tokens capacity, refill 10/sec, allows bursts up to 100
+const limiter = new TokenBucketLimiter(100, 10);
+```
+
+### Redis-Backed Distributed Rate Limiter
+
+```typescript
+// src/rate-limiters/redis-sliding-window.ts
+import { Redis } from 'ioredis';
+
+export class RedisRateLimiter {
+  constructor(
+    private readonly redis: Redis,
+    private readonly maxRequests: number,
+    private readonly windowMs: number,
+    private readonly prefix: string = 'rl',
+  ) {}
+
+  async check(key: string): Promise<{
+    allowed: boolean;
+    remaining: number;
+    resetAt: number;
+    retryAfterMs: number;
+  }> {
+    const now = Date.now();
+    const windowStart = now - this.windowMs;
+    const redisKey = `${this.prefix}:${key}`;
+
+    // Atomic Lua script: remove expired, count, add if under limit
+    const result = await this.redis.eval(
+      `
+      local key = KEYS[1]
+      local now = tonumber(ARGV[1])
+      local window_start = tonumber(ARGV[2])
+      local max_requests = tonumber(ARGV[3])
+      local window_ms = tonumber(ARGV[4])
+
+      -- Remove expired entries
+      redis.call('ZREMRANGEBYSCORE', key, 0, window_start)
+
+      -- Count current entries
+      local count = redis.call('ZCARD', key)
+
+      if count < max_requests then
+        -- Add new entry
+        redis.call('ZADD', key, now, now .. ':' .. math.random(1000000))
+        redis.call('PEXPIRE', key, window_ms)
+        return {1, max_requests - count - 1, 0}
+      else
+        -- Get oldest entry to calculate retry-after
+        local oldest = redis.call('ZRANGE', key, 0, 0, 'WITHSCORES')
+        local retry_after = oldest[2] and (tonumber(oldest[2]) + window_ms - now) or window_ms
+        return {0, 0, retry_after}
+      end
+      `,
+      1, redisKey, now, windowStart, this.maxRequests, this.windowMs
+    ) as [number, number, number];
+
+    return {
+      allowed: result[0] === 1,
+      remaining: result[1],
+      resetAt: now + this.windowMs,
+      retryAfterMs: result[2],
+    };
+  }
+}
+```
+
+### Express Middleware Integration
+
+```typescript
+// src/middleware/rate-limit.ts
+import type { Request, Response, NextFunction } from 'express';
+import { RedisRateLimiter } from '../rate-limiters/redis-sliding-window';
+
+interface RateLimitConfig {
+  maxRequests: number;
+  windowMs: number;
+  keyGenerator?: (req: Request) => string;
+  skipFailedRequests?: boolean;
+  message?: string;
+}
+
+export function rateLimit(limiter: RedisRateLimiter, config: RateLimitConfig) {
+  const getKey = config.keyGenerator ?? ((req: Request) => {
+    const userId = (req as any).userId;
+    return userId ? `user:${userId}` : `ip:${req.ip}`;
+  });
+
+  return async (req: Request, res: Response, next: NextFunction) => {
+    const key = getKey(req);
+    const result = await limiter.check(key);
+
+    // Always set rate limit headers
+    res.set({
+      'X-RateLimit-Limit': String(config.maxRequests),
+      'X-RateLimit-Remaining': String(result.remaining),
+      'X-RateLimit-Reset': String(Math.ceil(result.resetAt / 1000)),
+    });
+
+    if (!result.allowed) {
+      res.set('Retry-After', String(Math.ceil(result.retryAfterMs / 1000)));
+      return res.status(429).json({
+        error: config.message ?? 'Too many requests',
+        retryAfterMs: result.retryAfterMs,
+      });
+    }
+
+    next();
+  };
+}
+
+// Usage with different limits per endpoint
+const redis = new Redis(process.env.REDIS_URL!);
+
+app.use('/api/auth/login',
+  rateLimit(new RedisRateLimiter(redis, 5, 900_000, 'rl:login'), {
+    maxRequests: 5,
+    windowMs: 900_000, // 5 per 15 minutes
+    keyGenerator: (req) => `login:${req.ip}`,
+    message: 'Too many login attempts. Try again in 15 minutes.',
+  })
+);
+
+app.use('/api/',
+  rateLimit(new RedisRateLimiter(redis, 100, 60_000, 'rl:api'), {
+    maxRequests: 100,
+    windowMs: 60_000, // 100 per minute
+  })
+);
+```
+
+### Tiered Rate Limiting
+
+```typescript
+// src/rate-limiters/tiered.ts
+interface RateTier {
+  name: string;
+  maxRequests: number;
+  windowMs: number;
+}
+
+const tiers: Record<string, RateTier> = {
+  free:       { name: 'free', maxRequests: 60, windowMs: 60_000 },
+  pro:        { name: 'pro', maxRequests: 600, windowMs: 60_000 },
+  enterprise: { name: 'enterprise', maxRequests: 6000, windowMs: 60_000 },
+};
+
+function getTierForUser(userId: string): RateTier {
+  const subscription = getUserSubscription(userId);
+  return tiers[subscription.plan] ?? tiers.free;
+}
+
+app.use('/api/', async (req: Request, res: Response, next: NextFunction) => {
+  const userId = (req as any).userId;
+  const tier = getTierForUser(userId);
+  const limiter = new RedisRateLimiter(redis, tier.maxRequests, tier.windowMs, `rl:${tier.name}`);
+
+  const result = await limiter.check(userId);
+
+  res.set({
+    'X-RateLimit-Limit': String(tier.maxRequests),
+    'X-RateLimit-Remaining': String(result.remaining),
+    'X-RateLimit-Reset': String(Math.ceil(result.resetAt / 1000)),
+    'X-RateLimit-Tier': tier.name,
+  });
+
+  if (!result.allowed) {
+    res.set('Retry-After', String(Math.ceil(result.retryAfterMs / 1000)));
+    return res.status(429).json({
+      error: 'Rate limit exceeded',
+      tier: tier.name,
+      limit: tier.maxRequests,
+      upgradeUrl: '/pricing',
+    });
+  }
+
+  next();
+});
+```
+
+## Examples
+
+| Algorithm | Burst Behavior | Complexity | Best For |
+|-----------|---------------|------------|----------|
+| Fixed window | Full burst at boundary | O(1) | Simple APIs, low traffic |
+| Sliding window | Even distribution | O(n) | Accurate per-second limits |
+| Token bucket | Allows controlled bursts | O(1) | APIs with bursty traffic |
+| Leaky bucket | Smooths to constant rate | O(1) | Downstream protection |
+
+## Checklist
+- [ ] Rate limit headers (`X-RateLimit-*`, `Retry-After`) included in all responses
+- [ ] `429` responses include retry-after time and human-readable message
+- [ ] Redis-backed limiter used for multi-instance deployments
+- [ ] Key generation uses user ID for authenticated, IP for anonymous
+- [ ] Sensitive endpoints (login, password reset) have stricter limits
+- [ ] Tiered limits aligned with pricing plans
+- [ ] Lua script ensures atomic check-and-increment in Redis
+- [ ] Rate limiter tested for boundary conditions and clock drift

package/assets/skills/react-components.md

@@ -0,0 +1,201 @@
+---
+name: react-components
+description: Build maintainable React components using composition, hooks, memoization, and error boundaries.
+---
+
+# React Component Patterns
+
+## When to Use
+
+Apply these patterns when building any React UI — new features, refactoring
+existing components, or reviewing PRs. They keep components small, testable,
+and resilient to change.
+
+## How It Works
+
+### 1. Composition Over Props Drilling
+
+Pass components as children or render props instead of threading data through
+five layers of props.
+
+```tsx
+// Bad — LayoutPage knows about User, Sidebar, and every child
+<LayoutPage user={user} sidebarItems={items} headerTitle="Dashboard" />
+
+// Good — parent composes, children are independent
+<Layout>
+  <Layout.Header>
+    <h1>Dashboard</h1>
+  </Layout.Header>
+  <Layout.Sidebar>
+    <NavItems items={items} />
+  </Layout.Sidebar>
+  <Layout.Content>
+    <UserProfile user={user} />
+  </Layout.Content>
+</Layout>
+```
+
+Use compound components (dot notation) for tightly related UI groups.
+
+### 2. Custom Hooks Extract Logic
+
+Move stateful logic out of components into reusable hooks.
+
+```tsx
+function useDebounce<T>(value: T, delayMs: number): T {
+  const [debounced, setDebounced] = useState(value);
+  useEffect(() => {
+    const timer = setTimeout(() => setDebounced(value), delayMs);
+    return () => clearTimeout(timer);
+  }, [value, delayMs]);
+  return debounced;
+}
+
+function SearchInput() {
+  const [query, setQuery] = useState('');
+  const debouncedQuery = useDebounce(query, 300);
+  // fetch with debouncedQuery, component stays thin
+}
+```
+
+Rules: prefix with `use`, don't return JSX, test independently with
+`renderHook` from Testing Library.
+
+### 3. Memoization — When It Matters
+
+`React.memo` prevents re-renders when props haven't changed. Use it for
+expensive renders, not everywhere.
+
+```tsx
+// Memoize: renders a large list, parent re-renders often
+const UserList = memo(function UserList({ users }: { users: User[] }) {
+  return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
+});
+
+// Stabilize callbacks passed to memoized children
+function Parent() {
+  const handleClick = useCallback((id: string) => {
+    navigate(`/users/${id}`);
+  }, [navigate]);
+
+  return <UserList users={users} onClick={handleClick} />;
+}
+```
+
+Skip memo for: leaf components, components that always get new props, or
+anything that renders in < 1ms.
+
+### 4. Error Boundaries
+
+Catch render errors so one broken component doesn't crash the entire page.
+
+```tsx
+class ErrorBoundary extends Component<PropsWithChildren<{ fallback: ReactNode }>> {
+  state = { hasError: false, error: null as Error | null };
+
+  static getDerivedStateFromError(error: Error) {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error: Error, info: ErrorInfo) {
+    reportError(error, info.componentStack);
+  }
+
+  render() {
+    if (this.state.hasError) return this.props.fallback;
+    return this.props.children;
+  }
+}
+
+// Usage — isolate feature boundaries
+<ErrorBoundary fallback={<p>Something went wrong.</p>}>
+  <Dashboard />
+</ErrorBoundary>
+```
+
+Place boundaries around: route-level pages, third-party widgets, data-dependent
+feature sections.
+
+### 5. Suspense for Async UI
+
+Use Suspense with lazy components and data fetching libraries that support it.
+
+```tsx
+const AnalyticsChart = lazy(() => import('./AnalyticsChart'));
+
+function Dashboard() {
+  return (
+    <Suspense fallback={<ChartSkeleton />}>
+      <AnalyticsChart />
+    </Suspense>
+  );
+}
+```
+
+Combine with error boundaries for the complete async pattern:
+
+```tsx
+<ErrorBoundary fallback={<ErrorCard />}>
+  <Suspense fallback={<Skeleton />}>
+    <AsyncFeature />
+  </Suspense>
+</ErrorBoundary>
+```
+
+### 6. Prop Types That Document Intent
+
+```tsx
+interface ButtonProps {
+  variant: 'primary' | 'secondary' | 'danger';
+  size?: 'sm' | 'md' | 'lg';
+  isLoading?: boolean;
+  children: ReactNode;
+  onClick: () => void;
+}
+```
+
+Use discriminated unions for mutually exclusive prop groups:
+
+```tsx
+type ModalProps =
+  | { mode: 'confirm'; onConfirm: () => void; onCancel: () => void }
+  | { mode: 'alert'; onDismiss: () => void };
+```
+
+### 7. Forwarding Refs and Polymorphism
+
+```tsx
+const Input = forwardRef<HTMLInputElement, InputProps>(
+  function Input({ label, error, ...rest }, ref) {
+    return (
+      <div>
+        <label>{label}</label>
+        <input ref={ref} aria-invalid={!!error} {...rest} />
+        {error && <span role="alert">{error}</span>}
+      </div>
+    );
+  }
+);
+```
+
+## Examples
+
+| Problem | Pattern | Result |
+|---------|---------|--------|
+| Props drilled 4+ levels | Composition / Context | Each component gets only what it needs |
+| Logic duplicated across components | Custom hook | Single source, tested independently |
+| Parent re-render cascades | `memo` + `useCallback` | Child skips unnecessary renders |
+| One crash kills the page | Error boundary | Graceful fallback per section |
+| Large bundle, slow initial load | `lazy` + `Suspense` | Code-split, skeleton loading |
+
+## Checklist
+
+- [ ] No component file exceeds 200 lines — extract hooks or sub-components
+- [ ] Stateful logic lives in custom hooks, not inline in JSX
+- [ ] Error boundaries wrap every route-level page and risky third-party widget
+- [ ] `Suspense` with skeleton fallbacks wraps lazy-loaded and data-fetching components
+- [ ] `React.memo` is applied only where profiling shows wasted re-renders
+- [ ] Props use discriminated unions for mutually exclusive states
+- [ ] Interactive elements have accessible names (`aria-label`, visible label, or `aria-labelledby`)
+- [ ] No `any` in component props — every prop is explicitly typed