@girardmedia/bootspring 3.3.2 → 3.4.0

package/assets/skills/react-native-patterns.md

@@ -0,0 +1,299 @@
+---
+name: react-native-patterns
+description: React Native patterns for navigation, native modules, animations, platform-specific code, and OTA updates.
+---
+
+# React Native Patterns
+
+## When to Use
+Apply these patterns when building cross-platform mobile applications with React Native. These cover the core challenges: navigation architecture, bridging to native APIs, performant animations, writing platform-specific code, and shipping updates without app store delays. Use these from project setup to avoid costly refactors later.
+
+## How It Works
+
+### Navigation with React Navigation
+
+```typescript
+// src/navigation/RootNavigator.tsx
+import { NavigationContainer } from '@react-navigation/native';
+import { createNativeStackNavigator } from '@react-navigation/native-stack';
+import { createBottomTabNavigator } from '@react-navigation/bottom-tabs';
+
+type RootStackParamList = {
+  Auth: undefined;
+  Main: undefined;
+};
+
+type MainTabParamList = {
+  Home: undefined;
+  Profile: { userId: string };
+  Settings: undefined;
+};
+
+const Stack = createNativeStackNavigator<RootStackParamList>();
+const Tab = createBottomTabNavigator<MainTabParamList>();
+
+function MainTabs() {
+  return (
+    <Tab.Navigator screenOptions={{ headerShown: false }}>
+      <Tab.Screen name="Home" component={HomeScreen} />
+      <Tab.Screen name="Profile" component={ProfileScreen} initialParams={{ userId: 'me' }} />
+      <Tab.Screen name="Settings" component={SettingsScreen} />
+    </Tab.Navigator>
+  );
+}
+
+export function RootNavigator() {
+  const { isAuthenticated } = useAuth();
+
+  return (
+    <NavigationContainer>
+      <Stack.Navigator screenOptions={{ headerShown: false }}>
+        {isAuthenticated ? (
+          <Stack.Screen name="Main" component={MainTabs} />
+        ) : (
+          <Stack.Screen name="Auth" component={AuthScreen} />
+        )}
+      </Stack.Navigator>
+    </NavigationContainer>
+  );
+}
+```
+
+### Type-Safe Navigation Hooks
+
+```typescript
+// src/navigation/hooks.ts
+import { useNavigation, useRoute } from '@react-navigation/native';
+import type { NativeStackNavigationProp } from '@react-navigation/native-stack';
+import type { RouteProp } from '@react-navigation/native';
+
+export function useAppNavigation() {
+  return useNavigation<NativeStackNavigationProp<RootStackParamList>>();
+}
+
+export function useProfileRoute() {
+  return useRoute<RouteProp<MainTabParamList, 'Profile'>>();
+}
+
+// Usage in component:
+function ProfileScreen() {
+  const { params } = useProfileRoute();
+  const navigation = useAppNavigation();
+
+  return (
+    <Button title="Go Home" onPress={() => navigation.navigate('Main')} />
+  );
+}
+```
+
+### Native Module Bridge (Turbo Modules)
+
+```typescript
+// src/native/HapticModule.ts
+import { TurboModuleRegistry } from 'react-native';
+import type { TurboModule } from 'react-native';
+
+export interface Spec extends TurboModule {
+  trigger(type: string): void;
+  impactFeedback(style: 'light' | 'medium' | 'heavy'): void;
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>('HapticModule');
+```
+
+```swift
+// ios/HapticModule.swift
+@objc(HapticModule)
+class HapticModule: NSObject {
+  @objc func trigger(_ type: String) {
+    let generator = UINotificationFeedbackGenerator()
+    switch type {
+    case "success": generator.notificationOccurred(.success)
+    case "warning": generator.notificationOccurred(.warning)
+    case "error":   generator.notificationOccurred(.error)
+    default: break
+    }
+  }
+
+  @objc func impactFeedback(_ style: String) {
+    let s: UIImpactFeedbackGenerator.FeedbackStyle = style == "heavy" ? .heavy : style == "medium" ? .medium : .light
+    UIImpactFeedbackGenerator(style: s).impactOccurred()
+  }
+
+  @objc static func requiresMainQueueSetup() -> Bool { true }
+}
+```
+
+### Reanimated Animations
+
+```typescript
+// src/components/AnimatedCard.tsx
+import Animated, {
+  useSharedValue,
+  useAnimatedStyle,
+  withSpring,
+  withTiming,
+  interpolate,
+} from 'react-native-reanimated';
+import { Gesture, GestureDetector } from 'react-native-gesture-handler';
+
+export function AnimatedCard({ children }: { children: React.ReactNode }) {
+  const translateX = useSharedValue(0);
+  const scale = useSharedValue(1);
+
+  const panGesture = Gesture.Pan()
+    .onUpdate((e) => {
+      translateX.value = e.translationX;
+    })
+    .onEnd(() => {
+      if (Math.abs(translateX.value) > 150) {
+        translateX.value = withTiming(Math.sign(translateX.value) * 500);
+      } else {
+        translateX.value = withSpring(0);
+      }
+    });
+
+  const tapGesture = Gesture.Tap()
+    .onBegin(() => { scale.value = withSpring(0.95); })
+    .onFinalize(() => { scale.value = withSpring(1); });
+
+  const animatedStyle = useAnimatedStyle(() => ({
+    transform: [
+      { translateX: translateX.value },
+      { scale: scale.value },
+      { rotateZ: `${interpolate(translateX.value, [-200, 0, 200], [-15, 0, 15])}deg` },
+    ],
+    opacity: interpolate(Math.abs(translateX.value), [0, 200], [1, 0.5]),
+  }));
+
+  const composed = Gesture.Simultaneous(panGesture, tapGesture);
+
+  return (
+    <GestureDetector gesture={composed}>
+      <Animated.View style={[styles.card, animatedStyle]}>{children}</Animated.View>
+    </GestureDetector>
+  );
+}
+```
+
+### Platform-Specific Code
+
+```typescript
+// src/components/Shadow.tsx
+import { Platform, StyleSheet, View, ViewProps } from 'react-native';
+
+const styles = StyleSheet.create({
+  shadow: Platform.select({
+    ios: {
+      shadowColor: '#000',
+      shadowOffset: { width: 0, height: 2 },
+      shadowOpacity: 0.1,
+      shadowRadius: 8,
+    },
+    android: {
+      elevation: 4,
+    },
+    default: {},
+  })!,
+});
+
+// File-based platform splitting:
+// src/components/BiometricAuth.ios.ts   — Face ID implementation
+// src/components/BiometricAuth.android.ts — Fingerprint implementation
+// src/components/BiometricAuth.ts        — exports from platform file
+
+export function Shadow({ style, ...props }: ViewProps) {
+  return <View style={[styles.shadow, style]} {...props} />;
+}
+```
+
+### OTA Updates with EAS Update
+
+```typescript
+// src/updates/useAppUpdate.ts
+import * as Updates from 'expo-updates';
+import { useEffect, useState } from 'react';
+import { AppState } from 'react-native';
+
+export function useAppUpdate() {
+  const [updateAvailable, setUpdateAvailable] = useState(false);
+
+  useEffect(() => {
+    const subscription = AppState.addEventListener('change', async (state) => {
+      if (state !== 'active' || __DEV__) return;
+
+      try {
+        const update = await Updates.checkForUpdateAsync();
+        if (update.isAvailable) {
+          await Updates.fetchUpdateAsync();
+          setUpdateAvailable(true);
+        }
+      } catch (e) {
+        console.warn('Update check failed:', e);
+      }
+    });
+
+    return () => subscription.remove();
+  }, []);
+
+  const applyUpdate = async () => {
+    await Updates.reloadAsync();
+  };
+
+  return { updateAvailable, applyUpdate };
+}
+```
+
+### Performance: FlatList Optimization
+
+```typescript
+// src/components/OptimizedList.tsx
+import { FlatList, View, Text } from 'react-native';
+import { useCallback, memo } from 'react';
+
+interface Item { id: string; title: string; subtitle: string }
+
+const ListItem = memo(({ item }: { item: Item }) => (
+  <View style={{ padding: 16 }}>
+    <Text style={{ fontSize: 16, fontWeight: '600' }}>{item.title}</Text>
+    <Text style={{ fontSize: 14, color: '#666' }}>{item.subtitle}</Text>
+  </View>
+));
+
+export function OptimizedList({ data }: { data: Item[] }) {
+  const renderItem = useCallback(({ item }: { item: Item }) => <ListItem item={item} />, []);
+  const keyExtractor = useCallback((item: Item) => item.id, []);
+
+  return (
+    <FlatList
+      data={data}
+      renderItem={renderItem}
+      keyExtractor={keyExtractor}
+      getItemLayout={(_, index) => ({ length: 64, offset: 64 * index, index })}
+      maxToRenderPerBatch={20}
+      windowSize={5}
+      removeClippedSubviews
+      initialNumToRender={15}
+    />
+  );
+}
+```
+
+## Examples
+
+| Pattern | Problem | Solution |
+|---------|---------|----------|
+| Conditional navigator | Auth vs main flow | Render different Stack.Screens based on auth state |
+| Turbo Module | Need native haptics/biometrics | Define spec interface, implement per platform |
+| Reanimated shared value | Smooth gesture animations | `useSharedValue` + `useAnimatedStyle` on UI thread |
+| Platform.select | Different shadow APIs | iOS shadowColor vs Android elevation |
+| EAS Update | Ship fixes without app store | `expo-updates` check on app foreground |
+
+## Checklist
+- [ ] Navigation typed with ParamList generics for compile-time route safety
+- [ ] Native modules use Turbo Module spec for New Architecture compatibility
+- [ ] Animations run on UI thread via Reanimated worklets (no `runOnJS` in hot paths)
+- [ ] Platform-specific files use `.ios.ts` / `.android.ts` suffixes where divergence is large
+- [ ] FlatList uses `getItemLayout`, `memo`, and `removeClippedSubviews` for large lists
+- [ ] OTA updates checked on app foreground with user-visible apply prompt
+- [ ] Hermes engine enabled for both iOS and Android builds

package/assets/skills/real-time-patterns.md

@@ -0,0 +1,181 @@
+---
+name: real-time-patterns
+description: Real-time patterns for SSE, WebSockets, reconnection with backoff, presence channels, and Redis scaling.
+---
+
+# Real-Time Patterns
+
+## When to Use
+Use real-time patterns when users need instant updates: chat messages, notifications, live dashboards, collaborative editing, or auction bidding. Choose SSE for server-to-client streaming, WebSockets for bidirectional communication, and long polling as a universal fallback. This skill covers implementation, reconnection, presence, and multi-server scaling.
+
+## How It Works
+
+### Server-Sent Events (SSE) -- Simplest Server Push
+
+```typescript
+// Server -- one-direction, built-in auto-reconnection
+app.get("/events/:userId", (req, res) => {
+  res.writeHead(200, {
+    "Content-Type": "text/event-stream",
+    "Cache-Control": "no-cache",
+    "Connection": "keep-alive",
+    "X-Accel-Buffering": "no",
+  });
+
+  const userId = req.params.userId;
+  const heartbeat = setInterval(() => res.write(": heartbeat\n\n"), 30_000);
+
+  const handler = (event: AppEvent) => {
+    res.write(`event: ${event.type}\n`);
+    res.write(`data: ${JSON.stringify(event.payload)}\n`);
+    res.write(`id: ${event.id}\n\n`);
+  };
+  eventBus.subscribe(userId, handler);
+
+  req.on("close", () => {
+    clearInterval(heartbeat);
+    eventBus.unsubscribe(userId, handler);
+  });
+});
+
+// Client -- browser auto-reconnects with Last-Event-ID header
+const source = new EventSource("/events/user-123");
+source.addEventListener("notification", (e) => {
+  showNotification(JSON.parse(e.data));
+});
+```
+
+### WebSockets -- Bidirectional Communication
+
+```typescript
+import { WebSocketServer, WebSocket } from "ws";
+
+const wss = new WebSocketServer({ server: httpServer, path: "/ws" });
+const rooms = new Map<string, Set<WebSocket>>();
+
+wss.on("connection", (ws, req) => {
+  const userId = authenticateFromCookie(req);
+  if (!userId) { ws.close(4001, "Unauthorized"); return; }
+
+  ws.on("message", (raw) => {
+    const msg = JSON.parse(raw.toString());
+    switch (msg.type) {
+      case "join": joinRoom(msg.room, ws); break;
+      case "message":
+        broadcastToRoom(msg.room, {
+          type: "message", from: userId, text: msg.text, timestamp: Date.now(),
+        }, ws);
+        break;
+      case "ping": ws.send(JSON.stringify({ type: "pong" })); break;
+    }
+  });
+
+  ws.on("close", () => removeFromAllRooms(ws));
+});
+
+function broadcastToRoom(room: string, data: object, exclude?: WebSocket) {
+  const members = rooms.get(room);
+  if (!members) return;
+  const payload = JSON.stringify(data);
+  for (const client of members) {
+    if (client !== exclude && client.readyState === WebSocket.OPEN) {
+      client.send(payload);
+    }
+  }
+}
+```
+
+### Client Reconnection with Backoff
+
+```typescript
+class ReconnectingSocket {
+  private ws: WebSocket | null = null;
+  private attempt = 0;
+  private maxDelay = 30_000;
+
+  constructor(private url: string, private onMessage: (data: any) => void) {
+    this.connect();
+  }
+
+  private connect() {
+    this.ws = new WebSocket(this.url);
+    this.ws.onopen = () => { this.attempt = 0; };
+    this.ws.onmessage = (e) => this.onMessage(JSON.parse(e.data));
+    this.ws.onclose = (e) => {
+      if (e.code !== 1000) this.scheduleReconnect();
+    };
+  }
+
+  private scheduleReconnect() {
+    const delay = Math.min(1000 * Math.pow(2, this.attempt), this.maxDelay);
+    const jitter = delay * 0.3 * Math.random();
+    this.attempt++;
+    setTimeout(() => this.connect(), delay + jitter);
+  }
+
+  send(data: object) {
+    if (this.ws?.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify(data));
+    }
+  }
+}
+```
+
+### Presence Channels -- Who Is Online
+
+```typescript
+const presence = new Map<string, { userId: string; lastSeen: number }>();
+
+function updatePresence(userId: string) {
+  presence.set(userId, { userId, lastSeen: Date.now() });
+}
+
+function getOnlineUsers(staleMs = 60_000): string[] {
+  const cutoff = Date.now() - staleMs;
+  const online: string[] = [];
+  for (const [userId, info] of presence) {
+    if (info.lastSeen > cutoff) online.push(userId);
+    else presence.delete(userId);
+  }
+  return online;
+}
+```
+
+### Multi-Server Scaling with Redis
+
+```typescript
+import { createClient } from "redis";
+
+const pub = createClient();
+const sub = createClient();
+await pub.connect();
+await sub.connect();
+
+function broadcastToCluster(channel: string, data: object) {
+  pub.publish(`ws:${channel}`, JSON.stringify(data));
+}
+
+await sub.pSubscribe("ws:*", (message, channel) => {
+  const room = channel.replace("ws:", "");
+  broadcastToRoom(room, JSON.parse(message));
+});
+```
+
+## Examples
+
+| Transport | Direction | Auto-Reconnect | Use Case |
+|-----------|-----------|----------------|----------|
+| SSE | Server to client | Yes (built-in) | Notifications, live feeds |
+| WebSocket | Bidirectional | Manual (implement) | Chat, gaming, collaboration |
+| Long polling | Simulated push | N/A (client loops) | Legacy browser fallback |
+| Socket.io | Bidirectional | Yes (built-in) | WebSocket + fallback + rooms |
+
+## Checklist
+- [ ] Transport chosen based on requirements (SSE for push-only, WS for bidirectional)
+- [ ] Authentication checked on connection, not just on first message
+- [ ] Heartbeat/keepalive prevents proxy and load balancer timeouts
+- [ ] Client reconnects with exponential backoff and jitter
+- [ ] Last-Event-ID or cursor used to resume without data loss
+- [ ] Presence tracking uses heartbeat + stale cleanup
+- [ ] Multi-server scaling uses Redis pub/sub or a message broker
+- [ ] Connection count monitored with alerting configured

package/assets/skills/redis-patterns.md

@@ -0,0 +1,188 @@
+---
+name: redis-patterns
+description: Redis patterns for caching, pub/sub, streams, sorted sets, Lua scripts, and cluster configuration.
+---
+
+# Redis Patterns
+
+## When to Use
+Use Redis when you need sub-millisecond reads, ephemeral data structures, or coordination between services. Common use cases: caching expensive queries, rate limiting API endpoints, real-time leaderboards, job queues, session storage, and distributed locking. Choose the right data structure for each problem.
+
+## How It Works
+
+### Cache-Aside with TTL
+
+```typescript
+async function getUser(userId: string): Promise<User> {
+  const cacheKey = `user:${userId}`;
+  const cached = await redis.get(cacheKey);
+  if (cached) return JSON.parse(cached);
+
+  const user = await db.users.findUnique({ where: { id: userId } });
+  if (user) {
+    await redis.set(cacheKey, JSON.stringify(user), "EX", 3600);
+  }
+  return user;
+}
+
+// Invalidate on write
+async function updateUser(userId: string, data: Partial<User>): Promise<User> {
+  const user = await db.users.update({ where: { id: userId }, data });
+  await redis.del(`user:${userId}`);
+  return user;
+}
+```
+
+Keep values under 100KB. Use Hash for structured data when you need partial reads.
+
+### Rate Limiting -- Sliding Window
+
+```typescript
+async function isRateLimited(
+  key: string, limit: number, windowSec: number
+): Promise<boolean> {
+  const now = Date.now();
+  const windowStart = now - windowSec * 1000;
+
+  const pipeline = redis.pipeline();
+  pipeline.zremrangebyscore(key, 0, windowStart);
+  pipeline.zadd(key, now, `${now}-${Math.random()}`);
+  pipeline.zcard(key);
+  pipeline.expire(key, windowSec);
+
+  const results = await pipeline.exec();
+  const count = results![2][1] as number;
+  return count > limit;
+}
+
+// Usage: 100 requests per minute per user
+const limited = await isRateLimited(`rate:${userId}`, 100, 60);
+```
+
+### Distributed Lock -- Redlock Pattern
+
+```typescript
+async function acquireLock(resource: string, ttlMs: number): Promise<string | null> {
+  const token = crypto.randomUUID();
+  const acquired = await redis.set(`lock:${resource}`, token, "PX", ttlMs, "NX");
+  return acquired ? token : null;
+}
+
+async function releaseLock(resource: string, token: string): Promise<boolean> {
+  const script = `
+    if redis.call("get", KEYS[1]) == ARGV[1] then
+      return redis.call("del", KEYS[1])
+    else
+      return 0
+    end
+  `;
+  const result = await redis.eval(script, 1, `lock:${resource}`, token);
+  return result === 1;
+}
+
+// Usage
+const token = await acquireLock("order-123", 30000);
+if (token) {
+  try {
+    await processOrder("order-123");
+  } finally {
+    await releaseLock("order-123", token);
+  }
+}
+```
+
+### Pub/Sub -- Event Broadcasting
+
+```typescript
+// Publisher
+await redis.publish("orders:created", JSON.stringify({ orderId, userId }));
+
+// Subscriber (must use a separate connection)
+const sub = redis.duplicate();
+await sub.subscribe("orders:created");
+sub.on("message", (channel, message) => {
+  const event = JSON.parse(message);
+  notifyDashboard(event);
+});
+```
+
+Pub/Sub is fire-and-forget. If subscribers are down, messages are lost. Use Streams for durable messaging.
+
+### Streams -- Durable Event Log
+
+```typescript
+// Produce
+await redis.xadd("events:orders", "*", "type", "created", "orderId", orderId);
+
+// Consumer group -- each message delivered to one consumer
+await redis.xgroup("CREATE", "events:orders", "workers", "0", "MKSTREAM").catch(() => {});
+
+const messages = await redis.xreadgroup(
+  "GROUP", "workers", "worker-1",
+  "COUNT", 10, "BLOCK", 5000,
+  "STREAMS", "events:orders", ">"
+);
+
+// Acknowledge after processing
+if (messages) {
+  for (const [, msgs] of messages) {
+    for (const [id] of msgs) {
+      await redis.xack("events:orders", "workers", id);
+    }
+  }
+}
+```
+
+### Sorted Sets -- Leaderboards and Rankings
+
+```typescript
+// Add/update score
+await redis.zadd("leaderboard:weekly", score, `user:${userId}`);
+
+// Get top 10 with scores
+const top10 = await redis.zrevrange("leaderboard:weekly", 0, 9, "WITHSCORES");
+
+// Get a user's rank (0-indexed)
+const rank = await redis.zrevrank("leaderboard:weekly", `user:${userId}`);
+```
+
+### Lua Scripts -- Atomic Multi-Step Operations
+
+```typescript
+// Atomic increment with ceiling
+const script = `
+  local current = tonumber(redis.call("GET", KEYS[1]) or "0")
+  local ceiling = tonumber(ARGV[1])
+  if current >= ceiling then
+    return -1
+  end
+  return redis.call("INCR", KEYS[1])
+`;
+
+const result = await redis.eval(script, 1, "counter:signups", "1000");
+if (result === -1) {
+  throw new Error("Signup limit reached");
+}
+```
+
+## Examples
+
+| Pattern | Data Structure | Use Case |
+|---------|---------------|----------|
+| Cache-aside | String / Hash | DB query results, API responses |
+| Rate limiter | Sorted Set | API throttling per IP/user |
+| Distributed lock | String + NX + Lua | Singleton job execution |
+| Pub/Sub | Channels | Real-time notifications |
+| Streams | Stream | Durable event processing |
+| Leaderboard | Sorted Set | Rankings, top-N queries |
+| Session store | Hash + TTL | User sessions |
+
+## Checklist
+- [ ] Every cache key has a TTL -- no unbounded growth
+- [ ] Cache keys use consistent namespace: `entity:id:field`
+- [ ] Cache invalidation happens in same transaction as write
+- [ ] Rate limiter uses sorted set sliding window
+- [ ] Distributed locks use NX + PX + unique token + Lua release
+- [ ] Pub/Sub subscribers run on dedicated Redis connection
+- [ ] Streams use consumer groups with XACK
+- [ ] Memory policy set (`maxmemory-policy allkeys-lru` for caches)