@nockdev/awf 6.2.0 → 6.2.2

package/.agent/skills/cross-cutting/playwright/data/open-source-tools.yaml

@@ -0,0 +1,95 @@
+# =============================================================================
+# open-source-tools.yaml — Browser Automation Ecosystem Reference
+# =============================================================================
+
+version: "1.0.0"
+
+tools:
+  - name: "Playwright MCP"
+    url: "https://github.com/microsoft/playwright-mcp"
+    stars: "14k+"
+    approach: "Accessibility snapshots for LLM interaction"
+    key_feature: "Official Microsoft — 19 MCP tools, structured page state"
+    language: "TypeScript"
+    use_when: "AI agent needs to interact with browser via structured data"
+    integration: "Built-in MCP server, works with Claude, Cursor, Antigravity"
+
+  - name: "Stagehand"
+    url: "https://github.com/browserbase/stagehand"
+    stars: "12k+"
+    approach: "Hybrid code + natural language automation"
+    key_feature: "v3: modular driver (Puppeteer/CDP), AI-first automation"
+    language: "TypeScript"
+    use_when: "Need flexibility between explicit code and NL commands"
+    integration: "Browserbase cloud, session replay, CAPTCHA solving"
+
+  - name: "Browser-Use"
+    url: "https://github.com/browser-use/browser-use"
+    stars: "10k+"
+    approach: "Multi-LLM browser agent framework"
+    key_feature: "Foundation for many agentic projects, supports multiple LLMs"
+    language: "Python"
+    use_when: "Building custom AI browser agent with different LLM backends"
+    integration: "Puppeteer/Playwright compatible"
+
+  - name: "Midscene.js"
+    url: "https://github.com/anthropics/midscene"
+    stars: "5k+"
+    approach: "Visual AI + natural language UI testing"
+    key_feature: "Visual debugging tools, AI-powered test creation"
+    language: "TypeScript"
+    use_when: "Complex UI testing with visual AI understanding"
+    integration: "Works with Puppeteer and Playwright"
+
+  - name: "Shortest"
+    url: "https://github.com/shortest-inc/shortest"
+    stars: "4k+"
+    approach: "NL-based E2E testing framework"
+    key_feature: "Natural language test descriptions, Anthropic Claude powered"
+    language: "TypeScript"
+    use_when: "Writing tests in plain English, rapid test creation"
+    integration: "Built on Playwright, Anthropic Claude API"
+
+  - name: "TestDriver.ai"
+    url: "https://github.com/testdriverai/testdriver"
+    stars: "3k+"
+    approach: "Autonomous AI QA agent"
+    key_feature: "AI vision + OS-level emulation, web + desktop"
+    language: "TypeScript"
+    use_when: "Need to test desktop apps alongside web, human-like testing"
+    integration: "OS-level clicks, GitHub Actions support"
+
+  - name: "Skyvern"
+    url: "https://github.com/Skyvern-AI/skyvern"
+    stars: "2k+"
+    approach: "No-code + LLM + computer vision"
+    key_feature: "Adapts to website changes via NL commands"
+    language: "Python"
+    use_when: "Automating workflows on third-party websites"
+    integration: "REST API, cloud deployment"
+
+  - name: "BrowserOS"
+    url: "https://github.com/nicholasgasior/browseros"
+    stars: "1k+"
+    approach: "AI-native agentic browser"
+    key_feature: "Privacy-first, local AI via Ollama"
+    language: "TypeScript"
+    use_when: "Need local/private AI-powered browser automation"
+    integration: "Ollama for local LLM, privacy controls"
+
+accessibility_tools:
+  - name: "axe-core"
+    url: "https://github.com/dequelabs/axe-core"
+    purpose: "WCAG 2.0/2.1/2.2 compliance scanning"
+    integration: "npm install @axe-core/playwright"
+    usage: |
+      import AxeBuilder from '@axe-core/playwright';
+      const results = await new AxeBuilder({ page }).analyze();
+      expect(results.violations).toEqual([]);
+
+  - name: "mcp-accessibility-scanner"
+    url: "https://github.com/nicholasgasior/mcp-accessibility-scanner"
+    purpose: "MCP server for automated accessibility audits"
+    integration: "MCP server + axe-core + Playwright"
+
+# _DOMYH Awesome Code • Browser Automation Ecosystem v1.0.0_

package/.agent/skills/cross-cutting/real-time/META.yaml

@@ -0,0 +1,72 @@
+name: real-time
+version: "1.0.0"
+display: Real-time Communication
+category: cross-cutting
+tier: 1
+priority: 6
+
+desc: "Real-time communication patterns: WebSocket (full-duplex), Socket.IO (rooms/namespaces), SSE (server-push). Covers scaling, auth, reconnection, and LLM streaming."
+
+  ### Data Files (3 domains, ~21 patterns)
+  - websocket-patterns.yaml: connection, reconnect, auth, scaling (7)
+  - sse-patterns.yaml: event format, LLM streaming, NGINX config (7)
+  - socketio-patterns.yaml: rooms, namespaces, Redis adapter (7)
+
+triggers:
+  file_patterns:
+    - "**/ws/**"
+    - "**/socket/**"
+    - "**/websocket/**"
+  keywords:
+    - websocket
+    - WebSocket
+    - socket.io
+    - Socket.IO
+    - server-sent events
+    - SSE
+    - EventSource
+    - real-time
+    - real time
+    - live updates
+    - push notifications
+    - chat application
+    - collaborative editing
+    - bidirectional
+    - full-duplex
+    - streaming
+    - ws library
+    - socket connection
+
+caps:
+  # WebSocket
+  - WebSocket native API (browser + Node.js)
+  - Full-duplex bidirectional communication
+  - Connection lifecycle (open/close/error/message)
+  - Reconnection with exponential backoff
+  - Binary data support (ArrayBuffer, Blob)
+  # Socket.IO
+  - Rooms & namespaces for grouping
+  - Horizontal scaling (Redis adapter, NATS adapter)
+  - Automatic reconnection & transport fallback
+  - Acknowledgement callbacks
+  # SSE
+  - Server-Sent Events (unidirectional server → client)
+  - EventSource API with auto-reconnect
+  - Custom event types & lastEventId
+  - LLM streaming pattern (token-by-token)
+  # Production
+  - Authentication for persistent connections
+  - Heartbeat & ping-pong keep-alive
+  - Load balancing (sticky sessions vs stateless)
+  - NGINX/reverse proxy WebSocket config
+  - Horizontal scaling patterns
+
+related_skills:
+  - event-driven
+  - api-design
+  - ai-agents
+
+hsa_adapter:
+  enabled: true
+  data_dir: "skills/cross-cutting/real-time/data"
+  preload_data: true

package/.agent/skills/cross-cutting/real-time/SKILL.md

@@ -0,0 +1,128 @@
+# Real-time Communication — WebSocket • Socket.IO • SSE
+
+> Full-duplex • Rooms & Namespaces • Server Push  
+> Scaling • Authentication • LLM Streaming
+
+---
+
+## Khi Nào Dùng
+
+- Chat applications, collaborative editing
+- Live dashboards, real-time notifications
+- LLM response streaming (token-by-token)
+- Game state synchronization
+- IoT device communication
+
+## Protocol Selection
+
+| Protocol      | Direction       | Reconnect | Best For                      |
+| ------------- | --------------- | --------- | ----------------------------- |
+| **WebSocket** | Bidirectional   | Manual    | Chat, gaming, collaboration   |
+| **Socket.IO** | Bidirectional   | Auto      | Apps needing rooms/namespaces |
+| **SSE**       | Server → Client | Auto      | Notifications, LLM streaming  |
+
+## WebSocket Patterns
+
+### Connection with Reconnection
+
+```typescript
+class ReconnectingWS {
+  private retries = 0;
+  connect(url: string) {
+    this.ws = new WebSocket(url);
+    this.ws.onopen = () => {
+      this.retries = 0;
+    };
+    this.ws.onclose = () => {
+      const delay = Math.min(1000 * 2 ** this.retries++, 30000);
+      setTimeout(() => this.connect(url), delay);
+    };
+    this.ws.onmessage = (e) => this.handleMessage(JSON.parse(e.data));
+  }
+}
+```
+
+### Authentication
+
+```typescript
+// Token in URL (simple but exposed)
+new WebSocket(`wss://api.example.com?token=${jwt}`);
+// Token in first message (preferred)
+ws.onopen = () => ws.send(JSON.stringify({ type: "auth", token: jwt }));
+```
+
+## Socket.IO Patterns
+
+### Rooms & Namespaces
+
+```typescript
+// Server
+io.on("connection", (socket) => {
+  socket.join(`room:${roomId}`);
+  io.to(`room:${roomId}`).emit("message", data); // to room
+  socket.broadcast.to(`room:${roomId}`).emit("message", data); // except sender
+});
+// Namespace
+const chatNs = io.of("/chat");
+chatNs.on("connection", (socket) => { ... });
+```
+
+### Horizontal Scaling (Redis Adapter)
+
+```typescript
+import { createAdapter } from "@socket.io/redis-adapter";
+io.adapter(createAdapter(pubClient, subClient));
+// Now works across multiple server instances
+```
+
+## SSE Patterns
+
+### LLM Streaming
+
+```typescript
+// Server: stream LLM response
+app.get("/api/chat", (req, res) => {
+  res.writeHead(200, {
+    "Content-Type": "text/event-stream",
+    "Cache-Control": "no-cache",
+    Connection: "keep-alive",
+  });
+  for await (const chunk of llm.stream(messages)) {
+    res.write(`data: ${JSON.stringify({ content: chunk })}\n\n`);
+  }
+  res.write("data: [DONE]\n\n");
+  res.end();
+});
+
+// Client
+const source = new EventSource("/api/chat");
+source.onmessage = (e) => {
+  if (e.data === "[DONE]") {
+    source.close();
+    return;
+  }
+  appendToUI(JSON.parse(e.data).content);
+};
+```
+
+## Scaling Checklist
+
+- ✅ Sticky sessions OR Redis adapter
+- ✅ NGINX: `proxy_set_header Upgrade $http_upgrade`
+- ✅ Heartbeat/ping-pong for connection health
+- ✅ Connection limits per user
+- ✅ Message rate limiting
+- ✅ Graceful shutdown (drain connections)
+
+## Common Traps
+
+| Trap                                   | Fix                                       |
+| -------------------------------------- | ----------------------------------------- |
+| Connection drops behind proxy          | NGINX upgrade headers                     |
+| Memory leak from unclosed connections  | Track + cleanup on disconnect             |
+| Scaling issues                         | Redis/NATS adapter for multiple instances |
+| SSE max connections (browser limit: 6) | Use HTTP/2 or single multiplexed SSE      |
+
+---
+
+_DOMYH Awesome Code • Real-time Communication Skill v1.0.0_

package/.agent/skills/cross-cutting/real-time/data/socketio-patterns.yaml

@@ -0,0 +1,165 @@
+# Socket.IO Patterns — HSA Tier 3 Data
+version: "1.0.0"
+
+patterns:
+  - id: SIO-001
+    name: Server Setup
+    category: setup
+    description: |
+      Socket.IO server with Express.
+    example: |
+      import { Server } from "socket.io";
+      import { createServer } from "http";
+      import express from "express";
+
+      const app = express();
+      const httpServer = createServer(app);
+      const io = new Server(httpServer, {
+        cors: { origin: "http://localhost:3000", methods: ["GET", "POST"] },
+        pingTimeout: 60000,
+        pingInterval: 25000
+      });
+
+      io.on("connection", (socket) => {
+        console.log(`Connected: ${socket.id}`);
+        socket.on("disconnect", (reason) => console.log(`Disconnected: ${reason}`));
+      });
+
+      httpServer.listen(3001);
+
+  - id: SIO-002
+    name: Rooms and Namespaces
+    category: organization
+    description: |
+      Group connections using rooms and namespaces.
+    text: |
+      Rooms: Group sockets within a namespace. Dynamic join/leave.
+      Namespaces: Separate communication channels. Defined on server.
+
+      Room → For grouping users (e.g., chat rooms, game lobbies)
+      Namespace → For separating features (e.g., /chat, /admin)
+    example: |
+      // Rooms
+      socket.join(`room:${roomId}`);
+      socket.leave(`room:${roomId}`);
+
+      io.to(`room:${roomId}`).emit("message", data);     // To room
+      socket.to(`room:${roomId}`).emit("message", data);  // Except sender
+
+      // Namespaces
+      const chatNs = io.of("/chat");
+      const adminNs = io.of("/admin");
+
+      chatNs.on("connection", (socket) => {
+        socket.on("sendMessage", (msg) => {
+          chatNs.emit("newMessage", msg);
+        });
+      });
+
+  - id: SIO-003
+    name: Redis Adapter (Scaling)
+    category: scaling
+    description: |
+      Scale Socket.IO across multiple server instances.
+    text: |
+      Without adapter: Each server only knows its own connections.
+      With Redis adapter: All servers share events via Redis Pub/Sub.
+    example: |
+      import { createAdapter } from "@socket.io/redis-adapter";
+      import { createClient } from "redis";
+
+      const pubClient = createClient({ url: "redis://localhost:6379" });
+      const subClient = pubClient.duplicate();
+
+      await Promise.all([pubClient.connect(), subClient.connect()]);
+
+      io.adapter(createAdapter(pubClient, subClient));
+      // Now io.to("room").emit() works across all instances
+
+  - id: SIO-004
+    name: Authentication Middleware
+    category: security
+    description: |
+      Authenticate Socket.IO connections.
+    example: |
+      io.use(async (socket, next) => {
+        const token = socket.handshake.auth.token;
+        if (!token) return next(new Error("Authentication required"));
+        
+        try {
+          const user = await verifyJWT(token);
+          socket.data.user = user;
+          next();
+        } catch (err) {
+          next(new Error("Invalid token"));
+        }
+      });
+
+      // Client
+      const socket = io("http://localhost:3001", {
+        auth: { token: "Bearer eyJ..." }
+      });
+
+  - id: SIO-005
+    name: Acknowledgement Callbacks
+    category: reliability
+    description: |
+      Confirm message delivery with ack callbacks.
+    example: |
+      // Client sends with ack
+      socket.emit("sendMessage", { text: "Hello" }, (response) => {
+        console.log("Server confirmed:", response);
+      });
+
+      // Server handles with ack
+      socket.on("sendMessage", (data, callback) => {
+        saveMessage(data);
+        callback({ status: "ok", id: newMessageId });
+      });
+
+  - id: SIO-006
+    name: Error Handling
+    category: reliability
+    description: |
+      Handle connection errors and disconnections.
+    example: |
+      // Client-side
+      socket.on("connect_error", (err) => {
+        console.error("Connection error:", err.message);
+        if (err.message === "Invalid token") {
+          refreshToken();
+        }
+      });
+
+      socket.on("disconnect", (reason) => {
+        if (reason === "io server disconnect") {
+          socket.connect(); // Server disconnected, try reconnecting
+        }
+        // else: client will auto-reconnect
+      });
+
+  - id: SIO-007
+    name: Connection State Recovery
+    category: reliability
+    description: |
+      Socket.IO v4.6+ connection state recovery.
+    text: |
+      Server stores missed packets + room memberships.
+      Client reconnects and gets missed events automatically.
+    example: |
+      // Server: Enable recovery
+      const io = new Server(httpServer, {
+        connectionStateRecovery: {
+          maxDisconnectionDuration: 2 * 60 * 1000, // 2 minutes
+          skipMiddlewares: true
+        }
+      });
+
+      // Client: Check if recovered
+      socket.on("connect", () => {
+        if (socket.recovered) {
+          console.log("Connection recovered, missed events replayed");
+        } else {
+          console.log("Fresh connection, fetch initial state");
+        }
+      });

package/.agent/skills/cross-cutting/real-time/data/sse-patterns.yaml

@@ -0,0 +1,181 @@
+# Server-Sent Events Patterns — HSA Tier 3 Data
+version: "1.0.0"
+
+patterns:
+  - id: SSE-001
+    name: Basic SSE Server
+    category: server
+    description: |
+      Server-Sent Events for unidirectional server → client streaming.
+    example: |
+      // Express.js SSE endpoint
+      app.get("/api/events", (req, res) => {
+        res.writeHead(200, {
+          "Content-Type": "text/event-stream",
+          "Cache-Control": "no-cache",
+          "Connection": "keep-alive",
+          "X-Accel-Buffering": "no"  // NGINX: disable buffering
+        });
+        
+        // Send keepalive comment every 15s
+        const keepAlive = setInterval(() => res.write(": keepalive\n\n"), 15000);
+        
+        // Send events
+        const sendEvent = (event: string, data: unknown) => {
+          res.write(`event: ${event}\n`);
+          res.write(`data: ${JSON.stringify(data)}\n\n`);
+        };
+        
+        sendEvent("connected", { status: "ok" });
+        
+        req.on("close", () => {
+          clearInterval(keepAlive);
+        });
+      });
+
+  - id: SSE-002
+    name: LLM Token Streaming
+    category: ai
+    description: |
+      Stream LLM responses token-by-token via SSE.
+    text: |
+      The de facto standard for AI chat streaming.
+      Used by ChatGPT, Claude, Gemini web interfaces.
+    example: |
+      // Server: Stream LLM response
+      app.post("/api/chat", async (req, res) => {
+        res.writeHead(200, {
+          "Content-Type": "text/event-stream",
+          "Cache-Control": "no-cache",
+          "Connection": "keep-alive"
+        });
+        
+        const stream = await openai.chat.completions.create({
+          model: "gpt-4",
+          messages: req.body.messages,
+          stream: true
+        });
+        
+        for await (const chunk of stream) {
+          const content = chunk.choices[0]?.delta?.content;
+          if (content) {
+            res.write(`data: ${JSON.stringify({ content })}\n\n`);
+          }
+        }
+        res.write("data: [DONE]\n\n");
+        res.end();
+      });
+
+      // Client: Consume stream
+      const response = await fetch("/api/chat", { method: "POST", body, signal });
+      const reader = response.body.getReader();
+      const decoder = new TextDecoder();
+
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        const text = decoder.decode(value);
+        // Parse SSE format and extract data
+        for (const line of text.split("\n")) {
+          if (line.startsWith("data: ")) {
+            const data = line.slice(6);
+            if (data === "[DONE]") break;
+            const { content } = JSON.parse(data);
+            appendToUI(content);
+          }
+        }
+      }
+
+  - id: SSE-003
+    name: EventSource Client
+    category: client
+    description: |
+      Native browser EventSource API.
+    text: |
+      Pros: Auto-reconnect, simple API, HTTP/1.1 compatible
+      Cons: GET only, max 6 connections per domain (HTTP/1.1)
+      Workaround: Use HTTP/2 for unlimited connections
+    example: |
+      const source = new EventSource("/api/events");
+
+      source.onopen = () => console.log("Connected");
+      source.onerror = () => console.log("Error, will auto-reconnect");
+
+      // Default event
+      source.onmessage = (e) => console.log("Message:", e.data);
+
+      // Named events
+      source.addEventListener("notification", (e) => {
+        const data = JSON.parse(e.data);
+        showNotification(data.title, data.body);
+      });
+
+      // Custom last event ID for resumption
+      // Server sends: id: <event-id>\n
+      // Browser sends Last-Event-ID header on reconnect
+
+  - id: SSE-004
+    name: Custom Event Types
+    category: protocol
+    description: |
+      SSE event format with custom types.
+    text: |
+      SSE format:
+      event: <type>\n
+      data: <json>\n
+      id: <event-id>\n
+      retry: <ms>\n
+      \n
+    example: |
+      // Server sends
+      res.write("event: user-joined\n");
+      res.write("data: {\"user\":\"alice\"}\n");
+      res.write("id: evt-123\n\n");
+
+      res.write("event: message\n");
+      res.write("data: {\"text\":\"Hello\"}\n");
+      res.write("id: evt-124\n\n");
+
+      // Set retry interval
+      res.write("retry: 5000\n\n");
+
+  - id: SSE-005
+    name: NGINX SSE Configuration
+    category: infrastructure
+    description: |
+      NGINX configuration for SSE proxying.
+    example: |
+      location /api/events {
+        proxy_pass http://backend:3000;
+        proxy_http_version 1.1;
+        proxy_set_header Connection "";
+        proxy_buffering off;           # Critical for SSE
+        proxy_cache off;
+        proxy_read_timeout 86400;
+        chunked_transfer_encoding off;
+      }
+
+  - id: SSE-006
+    name: SSE vs WebSocket vs Long Polling
+    category: comparison
+    description: |
+      When to use each real-time technology.
+    text: |
+      | Feature | SSE | WebSocket | Long Polling |
+      |---------|-----|-----------|-------------|
+      | Direction | Server→Client | Bidirectional | Server→Client |
+      | Protocol | HTTP/1.1+ | ws:// / wss:// | HTTP |
+      | Auto-reconnect | ✅ Built-in | ❌ Manual | ❌ Manual |
+      | Browser limit | 6 (HTTP/1.1) | Unlimited | Many |
+      | Binary data | ❌ Text only | ✅ Yes | ❌ Text |
+      | Best for | Notifications, LLM | Chat, gaming | Legacy compat |
+
+  - id: SSE-007
+    name: Fetch-based SSE
+    category: client
+    description: |
+      Use fetch + ReadableStream for POST-based SSE (LLM pattern).
+    text: |
+      EventSource only supports GET.
+      For POST (chat messages), use fetch + stream reader.
+      Libraries: eventsource-parser, @microsoft/fetch-event-source