tribunal-kit 2.4.6 → 3.1.0

package/.agent/skills/realtime-patterns/SKILL.md

@@ -1,296 +1,269 @@
 ---
 name: realtime-patterns
-description: Real-time and collaborative application patterns. WebSockets, Server-Sent Events for AI streaming, CRDTs for conflict-free collaboration, presence, and sync engines. Use when building live collaboration, AI streaming UIs, live dashboards, or multiplayer features.
+description: Real-time application mastery. WebSockets, Server-Sent Events (SSE), CRDTs for conflict-free collaboration, presence systems, optimistic updates, live cursors, multiplayer state sync, reconnection strategies, and real-time database patterns (Supabase Realtime, Firebase). Use when building chat, live collaboration, dashboards, or multiplayer features.
 allowed-tools: Read, Write, Edit, Glob, Grep
-version: 1.0.0
-last-updated: 2026-03-12
+version: 2.0.0
+last-updated: 2026-04-01
 applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
 ---
 
-# Real-Time Patterns
-
-> The hardest part of real-time systems is not the latency — it's the concurrent state.
-> Two users editing the same document at the same millisecond must both win.
+# Real-Time Patterns — Live Application Mastery
 
 ---
 
-## Transport Selection
-
-Choose the transport based on what the data flow looks like:
+## Protocol Selection
 
-| Transport | Direction | Best For | Avoid When |
-|---|---|---|---|
-| **WebSocket** | Bidirectional | Chat, multiplayer, collaboration | Simple server push |
-| **SSE (Server-Sent Events)** | Server → client only | AI streaming, dashboards, notifications | Client needs to send data |
-| **WebRTC** | Peer-to-peer | Video/audio, P2P file transfer | Server coordination needed |
-| **HTTP Polling** | Client pull | Low-frequency updates, fallback | > 1 update per second |
-| **HTTP Streaming** | Server → client | Large response streaming, AI output | Need bidirectionality |
+```
+┌─────────────────────────────────────────────────────────────┐
+│              When to Use What                                │
+├─────────────────────────────────────────────────────────────┤
+│ SSE (Server-Sent Events)                                    │
+│   ✅ Server → Client only (one-way)                        │
+│   ✅ AI token streaming                                    │
+│   ✅ Live feeds, notifications, dashboards                  │
+│   ✅ Auto-reconnection built in                             │
+│   ✅ Works through HTTP proxies and CDNs                    │
+│                                                              │
+│ WebSocket                                                    │
+│   ✅ Bidirectional (client ↔ server)                        │
+│   ✅ Chat, gaming, collaborative editing                    │
+│   ✅ High-frequency updates (< 100ms intervals)            │
+│   ❌ Doesn't work through some proxies/CDNs                │
+│   ❌ No auto-reconnection (must implement)                  │
+│                                                              │
+│ HTTP Polling                                                 │
+│   ✅ Simplest implementation                                │
+│   ✅ Works everywhere                                       │
+│   ❌ Latency (poll interval)                                │
+│   ❌ Wasted requests when nothing changed                   │
+│                                                              │
+│ WebTransport (emerging)                                      │
+│   ✅ UDP-based, lowest latency                              │
+│   ✅ Multiplayer gaming, video streaming                    │
+│   ❌ Limited browser support (2024+)                        │
+└─────────────────────────────────────────────────────────────┘
+
+❌ HALLUCINATION TRAP: Don't default to WebSocket for everything
+   AI streaming → SSE (one-way, auto-reconnect)
+   Notifications → SSE (one-way)
+   Chat → WebSocket (bidirectional)
+   Live dashboard → SSE (one-way)
+   Collaborative editing → WebSocket + CRDT
+```
 
 ---
 
-## WebSocket Patterns
-
-### Connection Lifecycle
-
-```ts
-class WebSocketManager {
-  private ws: WebSocket | null = null;
-  private reconnectDelay = 1000;
-  private maxReconnectDelay = 30000;
-
-  connect(url: string) {
-    this.ws = new WebSocket(url);
-
-    this.ws.onopen = () => {
-      this.reconnectDelay = 1000;  // Reset on successful connect
-      this.authenticate();
-    };
-
-    this.ws.onclose = (event) => {
-      if (!event.wasClean) {
-        // Exponential backoff reconnect — never hammer the server
-        setTimeout(() => this.connect(url), this.reconnectDelay);
-        this.reconnectDelay = Math.min(this.reconnectDelay * 2, this.maxReconnectDelay);
-      }
-    };
-
-    this.ws.onerror = (err) => {
-      console.error('WebSocket error:', err);
-      // onclose fires after onerror — let it handle reconnect
-    };
-  }
-
-  private authenticate() {
-    // ✅ Always authenticate AFTER connection — never trust URL params for auth
-    this.ws!.send(JSON.stringify({
-      type: 'auth',
-      token: getAccessToken(),
-    }));
-  }
-}
-```
+## Server-Sent Events (SSE)
+
+```typescript
+// Server (Node.js/Express)
+app.get("/api/events", (req, res) => {
+  res.setHeader("Content-Type", "text/event-stream");
+  res.setHeader("Cache-Control", "no-cache");
+  res.setHeader("Connection", "keep-alive");
+  res.setHeader("X-Accel-Buffering", "no"); // disable nginx buffering
+
+  // Send initial connection event
+  res.write(`data: ${JSON.stringify({ type: "connected" })}\n\n`);
+
+  // Heartbeat to keep connection alive
+  const heartbeat = setInterval(() => {
+    res.write(": heartbeat\n\n"); // comment line, ignored by client
+  }, 15000);
+
+  // Subscribe to events
+  const handler = (event: AppEvent) => {
+    res.write(`event: ${event.type}\n`);
+    res.write(`data: ${JSON.stringify(event.data)}\n`);
+    res.write(`id: ${event.id}\n\n`);  // enables auto-resume
+  };
+  eventBus.subscribe(handler);
+
+  // Cleanup on disconnect
+  req.on("close", () => {
+    clearInterval(heartbeat);
+    eventBus.unsubscribe(handler);
+  });
+});
 
-### Backpressure
+// Client
+const eventSource = new EventSource("/api/events");
 
-```ts
-// ❌ Unbounded send — crashes if network is slow
-for (const item of hugeArray) {
-  ws.send(JSON.stringify(item));  // Buffers infinitely if slow
-}
+eventSource.addEventListener("notification", (e) => {
+  const data = JSON.parse(e.data);
+  showNotification(data);
+});
 
-// ✅ Check bufferedAmount before sending
-function sendWhenReady(ws: WebSocket, data: string) {
-  if (ws.bufferedAmount > 65536) {  // 64KB threshold
-    setTimeout(() => sendWhenReady(ws, data), 50);
-    return;
-  }
-  ws.send(data);
-}
+// Auto-reconnection is built-in!
+// The browser automatically reconnects with Last-Event-ID header
+eventSource.onerror = () => {
+  console.log("Connection lost — auto-reconnecting...");
+};
 ```
 
 ---
 
-## SSE for AI Streaming
+## WebSocket
 
-The right transport for one-directional AI text streaming:
+```typescript
+// Server (ws library)
+import { WebSocketServer, WebSocket } from "ws";
 
-### Server (Node.js / Hono)
+const wss = new WebSocketServer({ server: httpServer, path: "/ws" });
 
-```ts
-app.get('/api/chat/stream', async (c) => {
-  const { message } = c.req.query();
+// Connection management
+const clients = new Map<string, WebSocket>();
 
-  // Set SSE headers
-  c.res.headers.set('Content-Type', 'text/event-stream');
-  c.res.headers.set('Cache-Control', 'no-cache');
-  c.res.headers.set('Connection', 'keep-alive');
+wss.on("connection", (ws, req) => {
+  const userId = authenticateFromHeaders(req);
+  clients.set(userId, ws);
 
-  const stream = await openai.chat.completions.create({
-    model: 'gpt-4o',
-    messages: [{ role: 'user', content: message }],
-    stream: true,
+  ws.on("message", (raw) => {
+    try {
+      const message = JSON.parse(raw.toString());
+      handleMessage(userId, message);
+    } catch (e) {
+      ws.send(JSON.stringify({ error: "Invalid message format" }));
+    }
   });
 
-  const encoder = new TextEncoder();
-  const readable = new ReadableStream({
-    async start(controller) {
-      for await (const chunk of stream) {
-        const text = chunk.choices[0]?.delta?.content ?? '';
-        if (text) {
-          controller.enqueue(encoder.encode(`data: ${JSON.stringify({ text })}\n\n`));
-        }
-      }
-      controller.enqueue(encoder.encode('data: [DONE]\n\n'));
-      controller.close();
-    },
+  ws.on("close", () => {
+    clients.delete(userId);
+    broadcastPresence();
   });
 
-  return new Response(readable);
+  ws.on("pong", () => {
+    // Client is alive
+  });
 });
-```
-
-### Client (React)
-
-```tsx
-function useAIStream(prompt: string) {
-  const [text, setText] = useState('');
-  const [done, setDone] = useState(false);
-
-  useEffect(() => {
-    const source = new EventSource(`/api/chat/stream?message=${encodeURIComponent(prompt)}`);
-
-    source.onmessage = (e) => {
-      if (e.data === '[DONE]') {
-        setDone(true);
-        source.close();
-        return;
-      }
-      const { text: chunk } = JSON.parse(e.data);
-      setText(prev => prev + chunk);
-    };
-
-    source.onerror = () => source.close();
-
-    return () => source.close();  // Cleanup on unmount
-  }, [prompt]);
 
-  return { text, done };
+// Heartbeat — detect dead connections
+const interval = setInterval(() => {
+  wss.clients.forEach((ws) => {
+    if (ws.readyState === WebSocket.OPEN) {
+      ws.ping();
+    }
+  });
+}, 30000);
+
+// Broadcast to room
+function broadcastToRoom(roomId: string, message: unknown, excludeUser?: string) {
+  const roomMembers = getRoomMembers(roomId);
+  for (const memberId of roomMembers) {
+    if (memberId === excludeUser) continue;
+    const ws = clients.get(memberId);
+    if (ws?.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify(message));
+    }
+  }
 }
-```
-
----
-
-## CRDTs: Conflict-Free Collaboration
-
-CRDTs (Conflict-free Replicated Data Types) guarantee that concurrent edits from multiple users always merge to the same result, regardless of order or network conditions.
-
-### When to Use CRDTs vs Last-Write-Wins
 
-```
-Last-Write-Wins (LWW):
-  ✅ Settings, preferences, single-value fields
-  ❌ Text editing — loses concurrent edits
-
-Operational Transform (OT):
-  ✅ Google Docs-style (centralized server required)
-  ❌ Peer-to-peer, offline-first (server is the truth arbiter)
-
-CRDTs:
-  ✅ Collaborative text (Yjs), presence, shared lists
-  ✅ Offline-first, peer-to-peer
-  ✅ No central server required for convergence
-```
-
-### Yjs — The Standard CRDT Library
-
-```ts
-import * as Y from 'yjs';
-import { WebsocketProvider } from 'y-websocket';
-
-// Create a shared document
-const doc = new Y.Doc();
-
-// Connect to sync server — providers handle conflict resolution
-const provider = new WebsocketProvider('wss://your-server.com', 'room-id', doc);
-
-// Y.Text — CRDT for collaborative text editing
-const yText = doc.getText('document');
+// Client with reconnection
+class ReconnectingWebSocket {
+  private ws: WebSocket | null = null;
+  private retryCount = 0;
+  private maxRetries = 10;
 
-// Bind to a rich text editor (Tiptap, ProseMirror, CodeMirror)
-const editor = new Editor({
-  extensions: [Collaboration.configure({ document: doc })],
-});
+  connect(url: string) {
+    this.ws = new WebSocket(url);
+    this.ws.onopen = () => { this.retryCount = 0; };
+    this.ws.onclose = () => { this.reconnect(url); };
+    this.ws.onerror = () => { this.ws?.close(); };
+  }
 
-// Y.Map — CRDT for key-value shared state
-const awareness = new Y.Map();
-awareness.set('cursor', { userId, position });
+  private reconnect(url: string) {
+    if (this.retryCount >= this.maxRetries) return;
+    const delay = Math.min(1000 * 2 ** this.retryCount, 30000);
+    this.retryCount++;
+    setTimeout(() => this.connect(url), delay);
+  }
+}
 ```
 
 ---
 
-## Presence Patterns
-
-Presence = "who is online and what are they doing":
-
-```ts
-// Server: track presence via WebSocket lifecycle
-const presence = new Map<string, { userId: string; cursor: Position }>();
-
-wss.on('connection', (ws, req) => {
-  const userId = authenticate(req);
-
-  ws.on('message', (data) => {
-    const msg = JSON.parse(data.toString());
-    if (msg.type === 'cursor') {
-      presence.set(userId, { userId, cursor: msg.position });
-      broadcast({ type: 'presence', users: [...presence.values()] });
-    }
-  });
+## Optimistic Updates
+
+```typescript
+// React pattern: update UI immediately, reconcile on server response
+async function toggleLike(postId: string) {
+  // 1. Optimistic update (instant UI feedback)
+  setLiked((prev) => !prev);
+  setLikeCount((prev) => liked ? prev - 1 : prev + 1);
+
+  try {
+    // 2. Server request
+    await api.post(`/posts/${postId}/like`);
+  } catch (error) {
+    // 3. Rollback on failure
+    setLiked((prev) => !prev);
+    setLikeCount((prev) => liked ? prev + 1 : prev - 1);
+    toast.error("Failed to update. Please try again.");
+  }
+}
 
-  ws.on('close', () => {
-    presence.delete(userId);
-    broadcast({ type: 'presence', users: [...presence.values()] });
-  });
+// With React Query / TanStack Query:
+const likeMutation = useMutation({
+  mutationFn: (postId: string) => api.post(`/posts/${postId}/like`),
+  onMutate: async (postId) => {
+    await queryClient.cancelQueries({ queryKey: ["post", postId] });
+    const previous = queryClient.getQueryData(["post", postId]);
+    queryClient.setQueryData(["post", postId], (old: Post) => ({
+      ...old,
+      liked: !old.liked,
+      likeCount: old.liked ? old.likeCount - 1 : old.likeCount + 1,
+    }));
+    return { previous };
+  },
+  onError: (err, postId, context) => {
+    queryClient.setQueryData(["post", postId], context?.previous);
+  },
+  onSettled: (data, err, postId) => {
+    queryClient.invalidateQueries({ queryKey: ["post", postId] });
+  },
 });
 ```
 
 ---
 
-## Sync Engine Selection
+## Presence System
 
-| Engine | Model | Best For |
-|---|---|---|
-| **PartyKit** | WebSocket-native, Durable Objects | Multiplayer apps, AI + realtime |
-| **Liveblocks** | Managed CRDT + presence | Collaborative SaaS (Figma-style) |
-| **Supabase Realtime** | PostgreSQL change streams | Postgres-centric apps |
-| **ElectricSQL** | Local-first sync from Postgres | Offline-first apps |
-| **Replicache** | Client-side mutations + sync | Highly interactive, offline-capable |
+```typescript
+// Track who's online, typing, viewing
 
----
+interface PresenceState {
+  userId: string;
+  status: "online" | "away" | "offline";
+  cursor?: { x: number; y: number };
+  lastSeen: number;
+}
 
-## Output Format
+// Server-side presence manager
+class PresenceManager {
+  private presence = new Map<string, PresenceState>();
+  private readonly TIMEOUT_MS = 30_000;
+
+  update(userId: string, state: Partial<PresenceState>) {
+    this.presence.set(userId, {
+      ...this.presence.get(userId),
+      userId,
+      status: "online",
+      lastSeen: Date.now(),
+      ...state,
+    } as PresenceState);
+  }
 
-When this skill produces or reviews code, structure your output as follows:
+  getActive(): PresenceState[] {
+    const now = Date.now();
+    return [...this.presence.values()].filter(
+      (p) => now - p.lastSeen < this.TIMEOUT_MS,
+    );
+  }
 
-```
-━━━ Realtime Patterns Report ━━━━━━━━━━━━━━━━━━━━━━━━
-Skill:       Realtime Patterns
-Language:    [detected language / framework]
-Scope:       [N files · N functions]
-─────────────────────────────────────────────────
-✅ Passed:   [checks that passed, or "All clean"]
-⚠️  Warnings: [non-blocking issues, or "None"]
-❌ Blocked:  [blocking issues requiring fix, or "None"]
-─────────────────────────────────────────────────
-VBC status:  PENDING → VERIFIED
-Evidence:    [test output / lint pass / compile success]
+  remove(userId: string) {
+    this.presence.delete(userId);
+  }
+}
 ```
 
-**VBC (Verification-Before-Completion) is mandatory.**
-Do not mark status as VERIFIED until concrete terminal evidence is provided.
-
-
 ---
-
-## 🏛️ Tribunal Integration (Anti-Hallucination)
-
-**Slash command: `/tribunal-backend`**
-**Active reviewers: `logic` · `security` · `performance`**
-
-### ❌ Forbidden AI Tropes in Real-Time Engineering
-
-1. **Auth in URL params** — `ws://server.com?token=abc123` — tokens in URLs appear in logs and browser history. Authenticate via first message after handshake.
-2. **No reconnect logic** — all WebSocket connections will drop. No reconnect = broken app on any network hiccup.
-3. **Unbounded broadcast** — `wss.clients.forEach(ws => ws.send(data))` with no grouping = O(n) for every event.
-4. **Polling instead of streaming** — `setInterval(() => fetch('/api/ai-status'), 500)` for AI responses = wasteful; use SSE.
-5. **No backpressure handling** — sending data faster than the client can process = WebSocket buffer OOM.
-
-### ✅ Pre-Flight Self-Audit
-
-```
-✅ Are WebSocket connections authenticated via first message, not URL params?
-✅ Is there exponential backoff reconnect logic on unexpected disconnect?
-✅ Are broadcasts scoped to rooms/channels — not sent to all connected clients?
-✅ Is backpressure handled (bufferedAmount check before send)?
-✅ Is SSE used for one-directional AI streaming instead of WebSocket?
-```

package/.agent/skills/red-team-tactics/SKILL.md

@@ -9,8 +9,8 @@ applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
 
 # Red Team & Penetration Testing Principles
 
-> A red team engagement is a controlled attack.
-> The goal is to find what a real attacker would find — before they do.
+A red team engagement is a controlled attack.
+The goal is to find what a real attacker would find — before they do.
 
 ⚠️ **These techniques are for authorized security testing only. Unauthorized use is illegal.**
 
@@ -80,14 +80,14 @@ Getting data out without triggering alerts:
 
 ## Common Vulnerability Targets
 
-| Target | What to Test |
+|Target|What to Test|
 |---|---|
-| Web applications | OWASP Top 10, auth bypass, IDOR, SSRF |
-| APIs | Object-level authorization, mass assignment, rate limiting |
-| Authentication | Brute force protection, token entropy, password reset flow |
-| Secrets | Exposed env files, git history, CI/CD environment variables |
-| Third-party integrations | Webhook validation, OAuth redirect URI validation |
-| Infrastructure | Open S3 buckets, exposed admin ports, default credentials |
+|Web applications|OWASP Top 10, auth bypass, IDOR, SSRF|
+|APIs|Object-level authorization, mass assignment, rate limiting|
+|Authentication|Brute force protection, token entropy, password reset flow|
+|Secrets|Exposed env files, git history, CI/CD environment variables|
+|Third-party integrations|Webhook validation, OAuth redirect URI validation|
+|Infrastructure|Open S3 buckets, exposed admin ports, default credentials|
 
 ---
 
@@ -127,7 +127,7 @@ When testing detection capabilities:
 [Chronological story of the full attack path from initial access to objective]
 
 ## Remediation Priority
-| Finding | Severity | Fix By |
+|Finding|Severity|Fix By|
 |---|---|---|
 ```
 
@@ -157,45 +157,4 @@ Pre-Flight:  ✅ All checks passed
              or ❌ [blocking item that must be resolved first]
 ```
 
-
-
 ---
-
-## 🤖 LLM-Specific Traps
-
-AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
-
-1. **Over-engineering:** Proposing complex abstractions or distributed systems when a simpler approach suffices.
-2. **Hallucinated Libraries/Methods:** Using non-existent methods or packages. Always `// VERIFY` or check `package.json` / `requirements.txt`.
-3. **Skipping Edge Cases:** Writing the "happy path" and ignoring error handling, timeouts, or data validation.
-4. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
-5. **Silent Degradation:** Catching and suppressing errors without logging or re-raising.
-
----
-
-## 🏛️ Tribunal Integration (Anti-Hallucination)
-
-**Slash command: `/review` or `/tribunal-full`**
-**Active reviewers: `logic-reviewer` · `security-auditor`**
-
-### ❌ Forbidden AI Tropes
-
-1. **Blind Assumptions:** Never make an assumption without documenting it clearly with `// VERIFY: [reason]`.
-2. **Silent Degradation:** Catching and suppressing errors without logging or handling.
-3. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
-
-### ✅ Pre-Flight Self-Audit
-
-Review these questions before confirming output:
-```
-✅ Did I rely ONLY on real, verified tools and methods?
-✅ Is this solution appropriately scoped to the user's constraints?
-✅ Did I handle potential failure modes and edge cases?
-✅ Have I avoided generic boilerplate that doesn't add value?
-```
-
-### 🛑 Verification-Before-Completion (VBC) Protocol
-
-**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
-- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
-- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.