@nockdev/awf 6.2.0 → 6.2.2

package/.agent/skills/cross-cutting/electron/SKILL.md

@@ -842,20 +842,16 @@ my-electron-app/
 
 ## 🔌 HSA Integration
 
-```python
-from hsa.adapters.runtime_adapters import (
-    search_electron_patterns,
-    get_electron_api,
-)
-
-# Search patterns
-results = search_electron_patterns("auto update security")
-# Returns: [{'name': 'autoUpdater', 'category': 'updates', ...}, ...]
-
-# Get API info
-api = get_electron_api("contextBridge")
-# Returns: {'name': 'contextBridge', 'category': 'security', ...}
-```
+Data powered by HSA BM25 search engine. Query YAML data via skill search:
+
+| Domain   | Query Examples                              |
+| -------- | ------------------------------------------- |
+| Security | "context isolation sandbox preload"         |
+| IPC      | "invoke handle ipcMain ipcRenderer"         |
+| Updates  | "auto update electron-updater signing"      |
+| Storage  | "better-sqlite3 electron-store safeStorage" |
+| Native   | "tray notification shortcut deep link"      |
+| Testing  | "Playwright E2E Vitest unit test"           |
 
 ---
 

package/.agent/skills/cross-cutting/event-driven/META.yaml

@@ -0,0 +1,108 @@
+name: event-driven
+version: "1.0.0"
+display: Event-Driven Architecture
+category: cross-cutting
+tier: 1
+priority: 7
+
+desc: "Event-driven architecture patterns: message queues (Kafka, RabbitMQ, NATS), pub/sub, event sourcing, CQRS, saga pattern. Covers production patterns like DLQ, idempotency, and schema evolution."
+
+  ### Data Files (3 domains, ~24 patterns)
+  - eda-patterns.yaml: pub/sub, event sourcing, CQRS, saga (8)
+  - broker-comparison.yaml: Kafka vs RabbitMQ vs NATS feature matrix (8)
+  - production-patterns.yaml: DLQ, idempotency, schema evolution (8)
+
+triggers:
+  file_patterns:
+    # Kafka
+    - "kafka.config.*"
+    - "**/kafka/**"
+    # RabbitMQ
+    - "rabbitmq.conf"
+    - "**/amqp/**"
+    # NATS
+    - "nats.conf"
+    - "**/nats/**"
+    # General
+    - "**/events/**"
+    - "**/consumers/**"
+    - "**/producers/**"
+  keywords:
+    # Core concepts
+    - event driven
+    - event-driven architecture
+    - EDA
+    - message queue
+    - message broker
+    - pub/sub
+    - publish subscribe
+    # Brokers
+    - kafka
+    - Apache Kafka
+    - rabbitmq
+    - RabbitMQ
+    - NATS
+    - nats jetstream
+    - AMQP
+    # Patterns
+    - event sourcing
+    - CQRS
+    - command query responsibility segregation
+    - saga pattern
+    - choreography
+    - orchestration saga
+    - event-carried state transfer
+    # Production
+    - dead letter queue
+    - DLQ
+    - competing consumers
+    - consumer group
+    - idempotent consumer
+    - exactly-once semantics
+    - at-least-once
+    # Schema
+    - event schema
+    - schema registry
+    - avro
+    - schema evolution
+
+caps:
+  # Patterns
+  - Publish/Subscribe (topic-based, queue-based)
+  - Event Sourcing (immutable event log, replay)
+  - CQRS (separate read/write models)
+  - Saga Pattern (orchestration vs choreography)
+  - Event-Carried State Transfer
+  - Competing Consumers for horizontal scaling
+  # Kafka
+  - Kafka: partitioning, consumer groups, offsets
+  - Kafka: exactly-once semantics (idempotent producers + transactions)
+  - Kafka Connect & Kafka Streams
+  - Kafka: topic design & retention policies
+  # RabbitMQ
+  - RabbitMQ: exchanges (direct, topic, fanout, headers)
+  - RabbitMQ: quorum queues (RAFT-based HA)
+  - RabbitMQ: routing keys & bindings
+  - RabbitMQ: publisher confirms & consumer ACKs
+  # NATS
+  - NATS: core NATS (fire-and-forget, sub-ms latency)
+  - NATS: JetStream (persistence, exactly-once)
+  - NATS: request-reply pattern
+  # Production
+  - Dead Letter Queue (DLQ) management & recovery
+  - Idempotent consumers (deduplication)
+  - Schema evolution (backward/forward compatibility)
+  - Event versioning strategies
+  - Monitoring & alerting (consumer lag, throughput)
+
+related_skills:
+  - microservices
+  - api-design
+  - database
+  - docker
+  - kubernetes
+
+hsa_adapter:
+  enabled: true
+  data_dir: "skills/cross-cutting/event-driven/data"
+  preload_data: true

package/.agent/skills/cross-cutting/event-driven/SKILL.md

@@ -0,0 +1,123 @@
+# Event-Driven Architecture — Kafka • RabbitMQ • NATS
+
+> Pub/Sub • Event Sourcing • CQRS • Saga Pattern  
+> Dead Letter Queues • Idempotent Consumers • Schema Evolution
+
+---
+
+## Khi Nào Dùng
+
+- Thiết kế async messaging giữa microservices
+- Chọn message broker (Kafka vs RabbitMQ vs NATS)
+- Implement event sourcing, CQRS, hoặc saga pattern
+- Xử lý DLQ, idempotency, schema evolution
+
+## Broker Selection Guide
+
+| Feature         | Kafka                                 | RabbitMQ                    | NATS                             |
+| --------------- | ------------------------------------- | --------------------------- | -------------------------------- |
+| **Throughput**  | 1M+ msg/s                             | 50K-100K msg/s              | 200K-400K msg/s                  |
+| **Latency**     | 10-50ms                               | 5-20ms                      | <1ms (core)                      |
+| **Persistence** | Always                                | Configurable                | JetStream                        |
+| **Delivery**    | At-least-once (exactly-once possible) | At-least-once               | At-most-once / Exactly-once (JS) |
+| **Best For**    | Data streaming, event log             | Business workflows, routing | Real-time, IoT, cloud-native     |
+| **Complexity**  | ⭐⭐⭐ High                           | ⭐⭐ Medium                 | ⭐ Low                           |
+
+## Core Patterns
+
+### Pub/Sub
+
+```
+Producer ──▶ Topic/Exchange ──▶ Consumer A
+                            ──▶ Consumer B
+                            ──▶ Consumer C
+```
+
+### Event Sourcing + CQRS
+
+```
+Command ──▶ Event Store ──▶ [OrderCreated, ItemAdded, OrderPaid]
+                                          │
+                      ┌───────────────────┤
+                      ▼                   ▼
+               Read Model A        Read Model B
+              (Order Summary)     (Analytics)
+```
+
+### Saga Pattern
+
+```
+Orchestrator Saga:
+  Orchestrator ──▶ Service A (Book Order)
+                   ├── Success ──▶ Service B (Process Payment)
+                   │                ├── Success ──▶ Service C (Ship)
+                   │                └── Failure ──▶ Compensate A
+                   └── Failure ──▶ Done
+
+Choreography Saga:
+  Service A ──event──▶ Service B ──event──▶ Service C
+       ◀──compensate──      ◀──compensate──
+```
+
+## Production Patterns
+
+### Dead Letter Queue (DLQ)
+
+```typescript
+// Consumer with DLQ fallback
+async function consume(message: Message) {
+  try {
+    await process(message);
+    await message.ack();
+  } catch (err) {
+    if (message.retryCount >= MAX_RETRIES) {
+      await dlq.publish(message); // Send to DLQ
+      await message.ack(); // Remove from main queue
+    } else {
+      await message.nack({ requeue: true, delay: backoff(message.retryCount) });
+    }
+  }
+}
+```
+
+### Idempotent Consumer
+
+```typescript
+// Deduplication by event ID
+async function handleEvent(event: Event) {
+  const processed = await redis.setnx(`event:${event.id}`, "1", "EX", 86400);
+  if (!processed) return; // Already handled
+  await processEvent(event);
+}
+```
+
+### Schema Evolution
+
+| Strategy            | Compatibility       | Example                   |
+| ------------------- | ------------------- | ------------------------- |
+| **Add field**       | Backward compatible | New optional field        |
+| **Deprecate field** | Forward compatible  | Mark as deprecated        |
+| **Rename field**    | Breaking!           | Add alias, deprecate old  |
+| **Remove field**    | Breaking!           | Schema registry + version |
+
+## Common Traps
+
+| Trap                    | Fix                                             |
+| ----------------------- | ----------------------------------------------- |
+| Message ordering        | Kafka: partition key; RabbitMQ: single consumer |
+| Duplicate processing    | Idempotent consumers + dedup by event ID        |
+| Consumer lag            | Monitor lag, auto-scale consumers               |
+| Poison messages         | DLQ + max retry count                           |
+| Schema breaking changes | Schema registry, versioned events               |
+| Back-pressure           | Consumer rate limiting, buffering               |
+
+## Monitoring Essentials
+
+- Consumer lag (Kafka: `kafka-consumer-groups`, RabbitMQ: management UI)
+- Message throughput (in/out per second)
+- Error rate & DLQ depth
+- End-to-end latency (publish → consume)
+
+---
+
+_DOMYH Awesome Code • Event-Driven Architecture Skill v1.0.0_

package/.agent/skills/cross-cutting/event-driven/data/broker-comparison.yaml

@@ -0,0 +1,123 @@
+# Message Broker Comparison - HSA Event-Driven Skill
+# Updated: 2026-02-12
+
+metadata:
+  skill: event-driven
+  domain: broker-comparison
+  version: "1.0.0"
+  updated: "2026-02-12"
+  patterns_count: 8
+
+patterns:
+  - id: bkr001
+    name: kafka_overview
+    category: broker
+    description: Apache Kafka - distributed streaming platform
+    text: kafka streaming platform distributed log partitions consumer group
+    features:
+      throughput: "1M+ msg/s per broker"
+      latency: "10-50ms (batching)"
+      persistence: "Always (configurable retention)"
+      delivery: "At-least-once (exactly-once with transactions)"
+      ordering: "Per partition"
+      best_for: "Event streaming, data pipelines, event sourcing"
+    example: |
+      const kafka = new Kafka({ brokers: ["localhost:9092"] });
+      const producer = kafka.producer();
+      await producer.send({ topic: "events", messages: [{ key: orderId, value: data }] });
+
+  - id: bkr002
+    name: rabbitmq_overview
+    category: broker
+    description: RabbitMQ - mature message broker with flexible routing
+    text: rabbitmq AMQP exchange queue routing binding acknowledge
+    features:
+      throughput: "50K-100K msg/s"
+      latency: "5-20ms"
+      persistence: "Configurable per queue"
+      delivery: "At-least-once (publisher confirms + consumer ACK)"
+      ordering: "Per queue"
+      best_for: "Business workflows, complex routing, task queues"
+    example: |
+      const channel = await connection.createChannel();
+      await channel.assertQueue("tasks", { durable: true });
+      channel.sendToQueue("tasks", Buffer.from(JSON.stringify(task)));
+
+  - id: bkr003
+    name: nats_overview
+    category: broker
+    description: NATS - ultra-low latency cloud-native messaging
+    text: NATS jetstream core lightweight cloud-native IoT microservices
+    features:
+      throughput: "200K-400K msg/s (JetStream)"
+      latency: "<1ms (core), 1-5ms (JetStream)"
+      persistence: "JetStream only"
+      delivery: "At-most-once (core), exactly-once (JetStream)"
+      ordering: "Per subject"
+      best_for: "Real-time, IoT, cloud-native, low latency"
+    example: |
+      const nc = await connect({ servers: "localhost:4222" });
+      nc.publish("orders.created", encode(order));
+      const sub = nc.subscribe("orders.*");
+
+  - id: bkr004
+    name: selection_guide
+    category: reference
+    description: Decision matrix for choosing a message broker
+    text: selection guide choose broker decision matrix when to use
+    decision_matrix:
+      high_throughput_streaming: "Kafka"
+      complex_routing_workflows: "RabbitMQ"
+      ultra_low_latency: "NATS"
+      event_sourcing: "Kafka"
+      task_queue: "RabbitMQ"
+      iot_edge: "NATS"
+      cloud_native_simple: "NATS"
+      enterprise_integration: "RabbitMQ"
+
+  - id: bkr005
+    name: kafka_partitioning
+    category: broker
+    description: Kafka partition strategy for ordering and scaling
+    text: kafka partition key ordering consumer group scalability
+    example: |
+      // Partition by order ID → all events for same order in same partition
+      await producer.send({
+        topic: "orders",
+        messages: [{ key: order.id, value: JSON.stringify(event) }]
+      });
+
+  - id: bkr006
+    name: rabbitmq_exchanges
+    category: broker
+    description: RabbitMQ exchange types and routing patterns
+    text: rabbitmq exchange direct topic fanout headers routing
+    types:
+      direct: "Route by exact routing key match"
+      topic: "Route by pattern (order.* or order.#)"
+      fanout: "Broadcast to all bound queues"
+      headers: "Route by message headers"
+
+  - id: bkr007
+    name: nats_jetstream
+    category: broker
+    description: NATS JetStream for persistent streaming
+    text: nats jetstream persistence stream consumer durable exactly-once
+    example: |
+      const jsm = await nc.jetstreamManager();
+      await jsm.streams.add({ name: "ORDERS", subjects: ["orders.>"] });
+      const js = nc.jetstream();
+      await js.publish("orders.created", encode(order));
+
+  - id: bkr008
+    name: migration_guide
+    category: reference
+    description: Migration considerations when switching brokers
+    text: migration broker switch considerations compatibility
+    considerations:
+      - "Message format compatibility (serialize/deserialize)"
+      - "Delivery guarantee differences"
+      - "Ordering guarantee differences"
+      - "Consumer group / queue semantics"
+      - "Monitoring & operations tooling"
+      - "Dual-write period for zero-downtime migration"

package/.agent/skills/cross-cutting/event-driven/data/eda-patterns.yaml

@@ -0,0 +1,120 @@
+# EDA Core Patterns - HSA Event-Driven Skill
+# Updated: 2026-02-12
+
+metadata:
+  skill: event-driven
+  domain: eda-patterns
+  version: "1.0.0"
+  updated: "2026-02-12"
+  patterns_count: 8
+
+patterns:
+  - id: eda001
+    name: pub_sub
+    category: pattern
+    description: Publish-Subscribe pattern for event distribution
+    text: pub sub publish subscribe topic fan-out broadcast
+    example: |
+      // Publisher
+      await producer.send({ topic: "order.created", messages: [{ value: JSON.stringify(order) }] });
+      // Subscriber
+      await consumer.subscribe({ topic: "order.created" });
+      await consumer.run({ eachMessage: async ({ message }) => { ... } });
+
+  - id: eda002
+    name: event_sourcing
+    category: pattern
+    description: Store state changes as immutable events
+    text: event sourcing immutable event log append only replay aggregate
+    example: |
+      // Append events (never update/delete)
+      await eventStore.append("order-123", [
+        { type: "OrderCreated", data: { items, total } },
+        { type: "PaymentReceived", data: { amount, method } },
+        { type: "OrderShipped", data: { trackingId } }
+      ]);
+      // Rebuild state by replaying events
+      const order = events.reduce(applyEvent, initialState);
+
+  - id: eda003
+    name: cqrs
+    category: pattern
+    description: Separate read and write models for optimization
+    text: CQRS command query responsibility segregation read write separate
+    example: |
+      // Write side: commands → events
+      async function placeOrder(cmd) {
+        validate(cmd);
+        const event = { type: "OrderPlaced", data: cmd };
+        await eventStore.append(cmd.orderId, [event]);
+        await eventBus.publish(event);
+      }
+      // Read side: projections
+      eventBus.on("OrderPlaced", async (event) => {
+        await readDb.upsert("orders", buildProjection(event));
+      });
+
+  - id: eda004
+    name: saga_orchestration
+    category: pattern
+    description: Centralized saga orchestrator for distributed transactions
+    text: saga orchestration distributed transaction compensate coordinator
+    example: |
+      class OrderSaga {
+        async execute(order) {
+          try {
+            await paymentService.charge(order);
+            await inventoryService.reserve(order);
+            await shippingService.create(order);
+          } catch (err) {
+            await this.compensate(order, err.failedStep);
+          }
+        }
+        async compensate(order, failedStep) {
+          if (failedStep >= 2) await inventoryService.release(order);
+          if (failedStep >= 1) await paymentService.refund(order);
+        }
+      }
+
+  - id: eda005
+    name: saga_choreography
+    category: pattern
+    description: Decentralized saga via event chain (no coordinator)
+    text: saga choreography decentralized event chain no coordinator
+    flow: "OrderCreated → PaymentCharged → InventoryReserved → OrderFulfilled"
+    compensate: "PaymentFailed → OrderCancelled (each service listens and compensates)"
+
+  - id: eda006
+    name: outbox_pattern
+    category: pattern
+    description: Transactional outbox for reliable event publishing
+    text: outbox pattern transactional publish reliable atomicity
+    example: |
+      // Within database transaction
+      await db.transaction(async (tx) => {
+        await tx.insert("orders", order);
+        await tx.insert("outbox", { topic: "order.created", payload: order });
+      });
+      // Separate process polls outbox → publishes to broker
+
+  - id: eda007
+    name: event_carried_state
+    category: pattern
+    description: Events carry all needed data (no callback queries)
+    text: event carried state transfer self-contained no callback query
+    example: |
+      // ✅ Self-contained event
+      { type: "OrderCreated", data: { orderId, userId, userName, items, total } }
+      // ❌ Event requiring callback
+      { type: "OrderCreated", data: { orderId } } // Consumer must query for details
+
+  - id: eda008
+    name: event_versioning
+    category: evolution
+    description: Event schema versioning strategies
+    text: event version schema evolution backward forward compatible
+    strategies:
+      - "v1 → v2: Add optional fields (backward compatible)"
+      - "Upcasting: Transform old events to new format on read"
+      - "Event version field: { version: 2, type: 'OrderCreated', ... }"
+      - "Schema registry: Central store for event schemas"

package/.agent/skills/cross-cutting/event-driven/data/production-patterns.yaml

@@ -0,0 +1,120 @@
+# Production Patterns - HSA Event-Driven Skill
+# Updated: 2026-02-12
+
+metadata:
+  skill: event-driven
+  domain: production
+  version: "1.0.0"
+  updated: "2026-02-12"
+  patterns_count: 8
+
+patterns:
+  - id: prod001
+    name: dead_letter_queue
+    category: production
+    description: DLQ for failed messages after max retries
+    text: dead letter queue DLQ failed message poison retry max
+    example: |
+      async function consume(msg) {
+        try {
+          await process(msg);
+          await msg.ack();
+        } catch (err) {
+          if (msg.retryCount >= MAX_RETRIES) {
+            await dlq.publish(msg); // Move to DLQ
+            await msg.ack(); // Remove from main queue
+            logger.error("Message moved to DLQ", { msgId: msg.id, error: err });
+          } else {
+            await msg.nack({ requeue: true, delay: backoff(msg.retryCount) });
+          }
+        }
+      }
+
+  - id: prod002
+    name: idempotent_consumer
+    category: production
+    description: Prevent duplicate message processing
+    text: idempotent consumer deduplication event id unique processing
+    example: |
+      async function handleEvent(event) {
+        // Check if already processed (atomic operation)
+        const isNew = await redis.set(`event:${event.id}`, "1", "NX", "EX", 86400);
+        if (!isNew) return; // Already processed, skip
+        await processEvent(event);
+      }
+    severity: CRITICAL
+
+  - id: prod003
+    name: schema_evolution
+    category: production
+    description: Backward-compatible schema changes
+    text: schema evolution backward compatible forward add field version
+    rules:
+      safe: ["Add optional fields", "Add new event types", "Deprecate fields"]
+      unsafe: ["Remove fields", "Rename fields", "Change field types"]
+    example: |
+      // Schema registry (Confluent)
+      const registry = new SchemaRegistry({ host: "http://localhost:8081" });
+      const schema = await registry.getLatestSchema("order-value");
+
+  - id: prod004
+    name: consumer_lag_monitoring
+    category: monitoring
+    description: Monitor consumer lag to detect processing delays
+    text: consumer lag monitoring delay backlog alert threshold
+    metrics:
+      - "consumer_lag: messages behind (Kafka: per partition)"
+      - "processing_rate: messages/second"
+      - "error_rate: failed messages/second"
+      - "dlq_depth: messages in DLQ"
+    alert_thresholds:
+      warning: "lag > 1000 messages"
+      critical: "lag > 10000 messages or growing"
+
+  - id: prod005
+    name: backpressure
+    category: production
+    description: Handle backpressure when consumers can't keep up
+    text: backpressure slow consumer rate limiting buffer overflow
+    strategies:
+      - "Consumer-side rate limiting (prefetch count)"
+      - "Buffer with bounded queue"
+      - "Auto-scale consumers based on lag"
+      - "Circuit breaker for downstream services"
+
+  - id: prod006
+    name: ordered_processing
+    category: production
+    description: Maintain message ordering guarantees
+    text: ordered processing sequence partition key FIFO guarantee
+    strategies:
+      kafka: "Same partition key → same partition → ordered"
+      rabbitmq: "Single consumer per queue → ordered"
+      nats: "Deliver policy: all, subject-based ordering"
+
+  - id: prod007
+    name: retry_strategy
+    category: production
+    description: Exponential backoff retry with jitter
+    text: retry strategy exponential backoff jitter delay
+    example: |
+      function backoff(attempt) {
+        const base = 1000; // 1 second
+        const max = 60000; // 60 seconds
+        const delay = Math.min(base * Math.pow(2, attempt), max);
+        const jitter = delay * Math.random() * 0.3; // 30% jitter
+        return delay + jitter;
+      }
+
+  - id: prod008
+    name: graceful_shutdown
+    category: production
+    description: Graceful consumer shutdown without message loss
+    text: graceful shutdown drain stop process signal SIGTERM
+    example: |
+      process.on("SIGTERM", async () => {
+        logger.info("Shutting down consumer...");
+        await consumer.stop(); // Stop fetching new messages
+        await consumer.disconnect(); // Wait for in-flight to complete
+        process.exit(0);
+      });