@nockdev/awf 6.2.0 → 6.2.1

package/.agent/skills/cross-cutting/microservices/data/resilience.yaml

@@ -0,0 +1,189 @@
+# =============================================================================
+# resilience.yaml — Resilience Patterns for Microservices
+# =============================================================================
+
+version: "1.0.0"
+
+# =============================================================================
+# CIRCUIT BREAKER
+# =============================================================================
+
+circuit_breaker:
+  description: "Prevent cascade failures by stopping requests to failing services"
+
+  states:
+    closed: "Normal operation — requests pass through"
+    open: "Service failing — requests immediately rejected"
+    half_open: "Testing recovery — limited requests allowed"
+
+  config:
+    failure_threshold: 5
+    success_threshold: 3
+    timeout_seconds: 30
+    half_open_max_calls: 3
+
+  example_go: |
+    type CircuitBreaker struct {
+        mu              sync.Mutex
+        state           State
+        failureCount    int
+        successCount    int
+        failureThreshold int
+        successThreshold int
+        timeout         time.Duration
+        lastFailure     time.Time
+    }
+
+    func (cb *CircuitBreaker) Execute(fn func() error) error {
+        cb.mu.Lock()
+        if cb.state == Open {
+            if time.Since(cb.lastFailure) > cb.timeout {
+                cb.state = HalfOpen
+                cb.mu.Unlock()
+            } else {
+                cb.mu.Unlock()
+                return ErrCircuitOpen
+            }
+        } else {
+            cb.mu.Unlock()
+        }
+
+        err := fn()
+
+        cb.mu.Lock()
+        defer cb.mu.Unlock()
+
+        if err != nil {
+            cb.failureCount++
+            cb.lastFailure = time.Now()
+            if cb.failureCount >= cb.failureThreshold {
+                cb.state = Open
+            }
+            return err
+        }
+
+        if cb.state == HalfOpen {
+            cb.successCount++
+            if cb.successCount >= cb.successThreshold {
+                cb.state = Closed
+                cb.failureCount = 0
+                cb.successCount = 0
+            }
+        }
+        return nil
+    }
+
+  libraries:
+    go: ["sony/gobreaker", "afex/hystrix-go"]
+    java: ["resilience4j", "Netflix Hystrix (deprecated)"]
+    dotnet: ["Polly"]
+    typescript: ["opossum", "cockatiel"]
+
+# =============================================================================
+# BULKHEAD
+# =============================================================================
+
+bulkhead:
+  description: "Isolate failures so one component can't take down the whole system"
+
+  types:
+    - name: "Thread Pool Bulkhead"
+      description: "Dedicated thread pool per downstream service"
+      example: "Service A gets 10 threads, Service B gets 20 threads"
+
+    - name: "Semaphore Bulkhead"
+      description: "Limit concurrent calls with semaphore"
+      example: "max 5 concurrent calls to payment service"
+
+  example_go: |
+    type Bulkhead struct {
+        sem chan struct{}
+    }
+
+    func NewBulkhead(maxConcurrent int) *Bulkhead {
+        return &Bulkhead{sem: make(chan struct{}, maxConcurrent)}
+    }
+
+    func (b *Bulkhead) Execute(fn func() error) error {
+        select {
+        case b.sem <- struct{}{}:
+            defer func() { <-b.sem }()
+            return fn()
+        default:
+            return ErrBulkheadFull
+        }
+    }
+
+# =============================================================================
+# RETRY
+# =============================================================================
+
+retry:
+  description: "Automatically retry failed operations with backoff"
+
+  strategies:
+    - name: "Fixed Delay"
+      wait: "Same delay between retries"
+    - name: "Exponential Backoff"
+      wait: "2^attempt * base (100ms, 200ms, 400ms, 800ms)"
+    - name: "Exponential + Jitter"
+      wait: "Backoff + random jitter to prevent thundering herd"
+
+  config:
+    max_retries: 3
+    initial_delay_ms: 100
+    max_delay_ms: 5000
+    jitter: true
+    retryable_errors: ["timeout", "connection_refused", "503"]
+
+  example_go: |
+    func RetryWithBackoff(ctx context.Context, maxRetries int, fn func() error) error {
+        for i := 0; i <= maxRetries; i++ {
+            err := fn()
+            if err == nil {
+                return nil
+            }
+            if !isRetryable(err) || i == maxRetries {
+                return err
+            }
+            // Exponential backoff with jitter
+            delay := time.Duration(1<<uint(i)) * 100 * time.Millisecond
+            jitter := time.Duration(rand.Int63n(int64(delay / 2)))
+            select {
+            case <-time.After(delay + jitter):
+            case <-ctx.Done():
+                return ctx.Err()
+            }
+        }
+        return nil
+    }
+
+# =============================================================================
+# TIMEOUT
+# =============================================================================
+
+timeout:
+  description: "Prevent hanging by setting time limits"
+  recommended_values:
+    http_client: "3-5 seconds"
+    database_query: "5-10 seconds"
+    grpc_call: "1-3 seconds"
+    message_processing: "30 seconds"
+
+# =============================================================================
+# FALLBACK
+# =============================================================================
+
+fallback:
+  description: "Provide alternative when primary fails"
+  strategies:
+    - name: "Cache Fallback"
+      description: "Return cached data when service unavailable"
+    - name: "Default Value"
+      description: "Return sensible defaults"
+    - name: "Degraded Service"
+      description: "Reduced functionality instead of total failure"
+    - name: "Queue for Later"
+      description: "Accept request, process when service recovers"
+
+# _DOMYH Awesome Code • Resilience Patterns_

package/.agent/skills/cross-cutting/microservices/data/saga-patterns.yaml

@@ -0,0 +1,161 @@
+# =============================================================================
+# saga-patterns.yaml — Saga Pattern Implementation
+# =============================================================================
+
+version: "1.0.0"
+
+# =============================================================================
+# ORCHESTRATION SAGA
+# =============================================================================
+
+orchestration:
+  description: "Central orchestrator coordinates saga steps"
+
+  pattern:
+    name: "Order Saga Orchestrator"
+    steps:
+      - id: create_order
+        service: order-service
+        action: createOrder
+        compensation: cancelOrder
+
+      - id: reserve_inventory
+        service: inventory-service
+        action: reserveStock
+        compensation: releaseStock
+
+      - id: process_payment
+        service: payment-service
+        action: chargePayment
+        compensation: refundPayment
+
+      - id: arrange_shipping
+        service: shipping-service
+        action: createShipment
+        compensation: cancelShipment
+
+  example_go: |
+    type OrderSaga struct {
+        steps []SagaStep
+        compensations []CompensationFn
+    }
+
+    type SagaStep struct {
+        Name         string
+        Execute      func(ctx context.Context, state *SagaState) error
+        Compensate   func(ctx context.Context, state *SagaState) error
+    }
+
+    func (s *OrderSaga) Run(ctx context.Context, state *SagaState) error {
+        for i, step := range s.steps {
+            if err := step.Execute(ctx, state); err != nil {
+                // Compensate in reverse order
+                for j := i - 1; j >= 0; j-- {
+                    if compErr := s.steps[j].Compensate(ctx, state); compErr != nil {
+                        log.Error("compensation failed", "step", s.steps[j].Name, "err", compErr)
+                    }
+                }
+                return fmt.Errorf("saga failed at step %s: %w", step.Name, err)
+            }
+        }
+        return nil
+    }
+
+  example_typescript: |
+    interface SagaStep<T> {
+      name: string;
+      execute: (state: T) => Promise<T>;
+      compensate: (state: T) => Promise<T>;
+    }
+
+    class SagaOrchestrator<T> {
+      constructor(private steps: SagaStep<T>[]) {}
+
+      async run(initialState: T): Promise<T> {
+        let state = initialState;
+        const completed: SagaStep<T>[] = [];
+
+        for (const step of this.steps) {
+          try {
+            state = await step.execute(state);
+            completed.push(step);
+          } catch (error) {
+            // Compensate in reverse
+            for (const done of completed.reverse()) {
+              await done.compensate(state);
+            }
+            throw new SagaFailedError(step.name, error);
+          }
+        }
+        return state;
+      }
+    }
+
+# =============================================================================
+# CHOREOGRAPHY SAGA
+# =============================================================================
+
+choreography:
+  description: "Services communicate via events, no central coordinator"
+
+  pattern:
+    flow: |
+      OrderService → OrderCreated
+        → InventoryService listens → StockReserved
+          → PaymentService listens → PaymentProcessed
+            → ShippingService listens → ShipmentCreated
+              → OrderService listens → OrderCompleted
+
+    failure_flow: |
+      ShippingService → ShipmentFailed
+        → PaymentService listens → PaymentRefunded
+          → InventoryService listens → StockReleased
+            → OrderService listens → OrderCancelled
+
+  example_event: |
+    // Domain Events
+    type OrderCreated struct {
+        OrderID   string    `json:"order_id"`
+        UserID    string    `json:"user_id"`
+        Items     []Item    `json:"items"`
+        Total     float64   `json:"total"`
+        Timestamp time.Time `json:"timestamp"`
+    }
+
+    type StockReserved struct {
+        OrderID   string    `json:"order_id"`
+        Items     []Item    `json:"items"`
+        Timestamp time.Time `json:"timestamp"`
+    }
+
+# =============================================================================
+# DECISION GUIDE
+# =============================================================================
+
+decision_guide:
+  use_orchestration:
+    - "Complex workflows with 4+ services"
+    - "Need centralized monitoring and debugging"
+    - "Strict ordering requirements"
+    - "Business process changes frequently"
+
+  use_choreography:
+    - "Simple 2-3 service flows"
+    - "Loose coupling is critical"
+    - "Services are independently deployable"
+    - "Event-driven architecture already in place"
+
+  anti_patterns:
+    - name: "Saga without idempotency"
+      problem: "Retry causes duplicate actions"
+      fix: "Use idempotency keys for all operations"
+
+    - name: "Missing compensation"
+      problem: "Partial failure leaves inconsistent state"
+      fix: "Every action MUST have a compensating action"
+
+    - name: "Synchronous saga"
+      problem: "Blocking calls defeat the purpose"
+      fix: "Use async message passing between steps"
+
+# _DOMYH Awesome Code • Saga Patterns_

package/.agent/skills/cross-cutting/microservices/data/service-mesh.yaml

@@ -0,0 +1,179 @@
+# =============================================================================
+# service-mesh.yaml — Service Mesh Patterns
+# =============================================================================
+
+version: "1.0.0"
+
+# =============================================================================
+# OVERVIEW
+# =============================================================================
+
+overview:
+  description: |
+    Infrastructure layer that handles service-to-service communication.
+    Provides mTLS, load balancing, observability, and traffic management.
+
+  architecture: |
+    ┌─────────────────────────────────────┐
+    │  Service A    ←→  Sidecar Proxy     │
+    │                      ↕              │
+    │              Control Plane          │
+    │                      ↕              │
+    │  Service B    ←→  Sidecar Proxy     │
+    └─────────────────────────────────────┘
+
+# =============================================================================
+# COMPARISON
+# =============================================================================
+
+comparison:
+  features:
+    - feature: mTLS
+      istio: "Auto (PeerAuthentication)"
+      linkerd: "Auto (on by default)"
+      consul: "Auto (Connect)"
+
+    - feature: Traffic Management
+      istio: "VirtualService, DestinationRule"
+      linkerd: "TrafficSplit, ServiceProfile"
+      consul: "Service Router, Splitter"
+
+    - feature: Observability
+      istio: "Prometheus, Grafana, Jaeger, Kiali"
+      linkerd: "Built-in dashboard, Prometheus"
+      consul: "Envoy metrics, Consul UI"
+
+    - feature: Resource Overhead
+      istio: "~100MB per sidecar"
+      linkerd: "~20MB per sidecar"
+      consul: "~50MB per sidecar"
+
+    - feature: Complexity
+      istio: "High"
+      linkerd: "Low"
+      consul: "Medium"
+
+    - feature: Best For
+      istio: "Large enterprises, complex routing"
+      linkerd: "Simplicity-focused teams"
+      consul: "Multi-cloud, HashiCorp stack"
+
+# =============================================================================
+# ISTIO PATTERNS
+# =============================================================================
+
+istio:
+  traffic_management:
+    virtual_service: |
+      apiVersion: networking.istio.io/v1
+      kind: VirtualService
+      metadata:
+        name: reviews
+      spec:
+        hosts:
+          - reviews
+        http:
+          - match:
+              - headers:
+                  end-user:
+                    exact: jason
+            route:
+              - destination:
+                  host: reviews
+                  subset: v2
+          - route:
+              - destination:
+                  host: reviews
+                  subset: v1
+
+    canary_release: |
+      apiVersion: networking.istio.io/v1
+      kind: VirtualService
+      metadata:
+        name: my-service
+      spec:
+        hosts:
+          - my-service
+        http:
+          - route:
+              - destination:
+                  host: my-service
+                  subset: v1
+                weight: 90
+              - destination:
+                  host: my-service
+                  subset: v2
+                weight: 10
+
+  security:
+    mtls: |
+      apiVersion: security.istio.io/v1
+      kind: PeerAuthentication
+      metadata:
+        name: default
+        namespace: istio-system
+      spec:
+        mtls:
+          mode: STRICT
+
+    authorization: |
+      apiVersion: security.istio.io/v1
+      kind: AuthorizationPolicy
+      metadata:
+        name: allow-frontend
+      spec:
+        selector:
+          matchLabels:
+            app: backend
+        rules:
+          - from:
+              - source:
+                  principals: ["cluster.local/ns/default/sa/frontend"]
+
+# =============================================================================
+# LINKERD PATTERNS
+# =============================================================================
+
+linkerd:
+  installation: |
+    # Install CLI
+    curl --proto '=https' --tlsv1.2 -sSfL https://run.linkerd.io/install | sh
+
+    # Install control plane
+    linkerd install --crds | kubectl apply -f -
+    linkerd install | kubectl apply -f -
+
+    # Inject sidecar
+    kubectl get deploy -o yaml | linkerd inject - | kubectl apply -f -
+
+  traffic_split: |
+    apiVersion: split.smi-spec.io/v1alpha1
+    kind: TrafficSplit
+    metadata:
+      name: my-service
+    spec:
+      service: my-service
+      backends:
+        - service: my-service-v1
+          weight: 900m     # 90%
+        - service: my-service-v2
+          weight: 100m     # 10%
+
+# =============================================================================
+# DECISION GUIDE
+# =============================================================================
+
+decision_guide:
+  need_service_mesh:
+    - "50+ microservices"
+    - "Need mTLS between all services"
+    - "Need fine-grained traffic control"
+    - "Compliance requires service-level auth"
+
+  dont_need_service_mesh:
+    - "< 10 services"
+    - "Monolith or simple architecture"
+    - "Team lacks Kubernetes experience"
+    - "Can achieve goals with simpler tools"
+
+# _DOMYH Awesome Code • Service Mesh Patterns_

package/.agent/skills/cross-cutting/monorepo/META.yaml

@@ -0,0 +1,54 @@
+# =============================================================================
+# META.yaml — Monorepo Management
+# =============================================================================
+
+name: monorepo
+version: "1.0.0"
+category: cross-cutting
+priority: 3
+
+description: |
+  Monorepo management patterns: Nx, Turborepo, pnpm workspaces,
+  affected CI, versioning strategies, and dependency management.
+
+triggers:
+  keywords:
+    - monorepo
+    - workspace
+    - nx
+    - turborepo
+    - lerna
+    - pnpm workspace
+    - yarn workspace
+    - npm workspace
+    - changesets
+    - affected
+    - task graph
+
+  intents:
+    - "setup monorepo"
+    - "configure nx workspace"
+    - "setup turborepo"
+    - "manage workspace packages"
+    - "affected-only CI"
+
+  detect_patterns:
+    files: ["nx.json", "turbo.json", "lerna.json", "pnpm-workspace.yaml"]
+    content: ["workspaces", '"nx":', '"turbo":']
+
+caps:
+  - nx_workspace_setup
+  - turborepo_config
+  - workspace_management
+  - affected_ci
+  - versioning_strategy
+  - dependency_graph
+
+data_files:
+  - nx-patterns.yaml
+  - turborepo-patterns.yaml
+  - workspace-patterns.yaml
+  - ci-cd-strategies.yaml
+  - versioning.yaml
+
+# _DOMYH Awesome Code • Monorepo Skill_

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

@@ -0,0 +1,108 @@
+# 📦 Monorepo Management
+
+> Patterns for multi-package repository management
+> 📚 Nx • Turborepo • pnpm Workspaces • Changesets
+
+---
+
+## Quick Reference
+
+| Tool                | Best For                  | Package Manager | Remote Cache |
+| ------------------- | ------------------------- | --------------- | :----------: |
+| **Nx**              | Large enterprise, plugins | Any             | ✅ Nx Cloud  |
+| **Turborepo**       | Simple, fast builds       | Any             |  ✅ Vercel   |
+| **pnpm workspaces** | Lightweight, npm-like     | pnpm            |      ❌      |
+| **Lerna**           | Legacy, npm publishing    | npm/yarn        |      ❌      |
+
+---
+
+## Monorepo vs Polyrepo
+
+| Aspect          | Monorepo                    | Polyrepo          |
+| --------------- | --------------------------- | ----------------- |
+| Code sharing    | ✅ Easy                     | ⚠️ Via packages   |
+| Atomic changes  | ✅ Single commit            | ❌ Multi-repo PRs |
+| CI complexity   | ⚠️ Needs affected detection | ✅ Simple         |
+| Team autonomy   | ⚠️ Shared codebase          | ✅ Independent    |
+| Dependency mgmt | ✅ Centralized              | ⚠️ Version matrix |
+
+---
+
+## Nx Workspace
+
+```bash
+# Create Nx workspace
+npx create-nx-workspace@latest my-org --preset=ts
+
+# Add apps
+nx g @nx/next:app my-app
+nx g @nx/node:app api
+
+# Add libraries
+nx g @nx/js:lib shared-types
+nx g @nx/react:lib ui-components
+
+# Run affected
+nx affected --target=build
+nx affected --target=test
+```
+
+---
+
+## Turborepo
+
+```json
+// turbo.json
+{
+  "pipeline": {
+    "build": {
+      "dependsOn": ["^build"],
+      "outputs": ["dist/**", ".next/**"]
+    },
+    "test": {
+      "dependsOn": ["build"]
+    },
+    "lint": {}
+  }
+}
+```
+
+```bash
+turbo run build --filter=@org/web
+turbo run test --affected
+```
+
+---
+
+## Directory Structure
+
+```
+monorepo/
+├── apps/
+│   ├── web/          # Next.js frontend
+│   ├── api/          # Node.js backend
+│   └── mobile/       # React Native
+├── packages/
+│   ├── ui/           # Shared UI components
+│   ├── config/       # Shared configs (ESLint, TS)
+│   └── utils/        # Shared utilities
+├── nx.json / turbo.json
+├── pnpm-workspace.yaml
+└── package.json
+```
+
+---
+
+## HSA Integration
+
+| Query                              | Data File                 |
+| ---------------------------------- | ------------------------- |
+| `nx generators executors affected` | `nx-patterns.yaml`        |
+| `turborepo pipeline cache`         | `turborepo-patterns.yaml` |
+| `pnpm workspace npm yarn`          | `workspace-patterns.yaml` |
+| `affected ci change detection`     | `ci-cd-strategies.yaml`   |
+| `changesets conventional commits`  | `versioning.yaml`         |
+
+---
+
+_DOMYH Awesome Code • Monorepo Management_