@dewtech/dare-cli 3.11.0 → 3.12.0

package/skills/dare-realtime/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@dewtech/dare-realtime",
+  "version": "1.0.0",
+  "description": "dare-realtime — Real-time communication patterns skill for DARE Method v3.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "skill.yml"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.41",
+    "typescript": "^5.9.3",
+    "vitest": "^1.6.1"
+  },
+  "keywords": [
+    "dare",
+    "dare-method",
+    "dare-realtime",
+    "websocket",
+    "sse",
+    "pubsub",
+    "realtime"
+  ],
+  "author": "Dewtech Technologies",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/skills/dare-realtime/reconnect_strategy.ts

@@ -0,0 +1,85 @@
+/**
+ * dare-realtime — ReconnectStrategy
+ * Exponential backoff for WebSocket / SSE reconnection.
+ *
+ * Delays: attempt 0=1s, 1=2s, 2=4s, 3=8s, … capped at maxDelay (30s).
+ * License: MIT
+ */
+
+export interface ReconnectStrategyConfig {
+  /** Initial delay in milliseconds. Default: 1000 (1s). */
+  initialDelayMs?: number;
+  /** Maximum delay in milliseconds. Default: 30000 (30s). */
+  maxDelayMs?: number;
+  /** Jitter factor (0–1) to randomize delay and avoid thundering herd. Default: 0 (no jitter). */
+  jitter?: number;
+}
+
+export class ReconnectStrategy {
+  private readonly initialDelayMs: number;
+  private readonly maxDelayMs: number;
+  private readonly jitter: number;
+  private _attempt: number = 0;
+
+  constructor(config: ReconnectStrategyConfig = {}) {
+    this.initialDelayMs = config.initialDelayMs ?? 1_000;
+    this.maxDelayMs = config.maxDelayMs ?? 30_000;
+    this.jitter = Math.min(1, Math.max(0, config.jitter ?? 0));
+  }
+
+  /**
+   * Get the delay in milliseconds for a given attempt number.
+   * Follows exponential backoff: initialDelay * 2^attempt, capped at maxDelay.
+   *
+   * @param attempt - Zero-based attempt count (0 = first reconnect)
+   */
+  getDelay(attempt: number): number {
+    if (attempt < 0) attempt = 0;
+    const base = this.initialDelayMs * Math.pow(2, attempt);
+    const capped = Math.min(base, this.maxDelayMs);
+
+    if (this.jitter > 0) {
+      const jitterAmount = capped * this.jitter * Math.random();
+      return Math.round(capped + jitterAmount);
+    }
+
+    return capped;
+  }
+
+  /**
+   * Get the delay for the next attempt (auto-incrementing internal counter).
+   */
+  nextDelay(): number {
+    const delay = this.getDelay(this._attempt);
+    this._attempt++;
+    return delay;
+  }
+
+  /**
+   * Reset the attempt counter back to 0 (call after a successful connection).
+   */
+  reset(): void {
+    this._attempt = 0;
+  }
+
+  /**
+   * Current attempt count.
+   */
+  get attempt(): number {
+    return this._attempt;
+  }
+
+  /**
+   * Configured initial delay in milliseconds.
+   */
+  get initialDelay(): number {
+    return this.initialDelayMs;
+  }
+
+  /**
+   * Configured maximum delay in milliseconds.
+   */
+  get maxDelay(): number {
+    return this.maxDelayMs;
+  }
+}

package/skills/dare-realtime/schema_validator.ts

@@ -0,0 +1,80 @@
+/**
+ * dare-realtime — SchemaValidator
+ * Validates a real-time event payload against a JSON Schema definition.
+ * Zero external dependencies.
+ * License: MIT
+ */
+
+import type { ValidationResult, ValidationError, EventSchema } from './types.js';
+
+export class SchemaValidator {
+  /**
+   * Validate a payload against a schema.
+   */
+  validate(payload: unknown, schema: EventSchema): ValidationResult {
+    const errors: ValidationError[] = [];
+    validateValue(payload, schema, '$', errors);
+    return { ok: errors.length === 0, errors };
+  }
+}
+
+function validateValue(
+  value: unknown,
+  schema: EventSchema,
+  path: string,
+  errors: ValidationError[]
+): void {
+  // Type check
+  if (schema.type !== undefined) {
+    const actualType = getType(value);
+    if (schema.type !== actualType) {
+      errors.push({
+        field: path,
+        message: `Expected type "${schema.type}", got "${actualType}"`,
+        value,
+      });
+      return; // No further checks if type is wrong
+    }
+  }
+
+  // Object checks
+  if (schema.type === 'object' && typeof value === 'object' && value !== null && !Array.isArray(value)) {
+    const obj = value as Record<string, unknown>;
+
+    // Required fields
+    if (schema.required) {
+      for (const field of schema.required) {
+        if (!(field in obj) || obj[field] === undefined || obj[field] === null) {
+          errors.push({
+            field: `${path}.${field}`,
+            message: `Required field "${field}" is missing`,
+          });
+        }
+      }
+    }
+
+    // Properties
+    if (schema.properties) {
+      for (const [key, propSchema] of Object.entries(schema.properties)) {
+        if (key in obj) {
+          validateValue(obj[key], propSchema, `${path}.${key}`, errors);
+        }
+      }
+    }
+  }
+
+  // Array checks
+  if (schema.type === 'array' && Array.isArray(value)) {
+    if (schema.items) {
+      (value as unknown[]).forEach((item, i) => {
+        validateValue(item, schema.items!, `${path}[${i}]`, errors);
+      });
+    }
+  }
+}
+
+function getType(value: unknown): string {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'array';
+  return typeof value;
+}

package/skills/dare-realtime/skill.yml

@@ -0,0 +1,21 @@
+name: dare-realtime
+version: 1.0.0
+license: MIT
+description: >
+  Skill transversal DARE para real-time communication. Fornece schema validation
+  de eventos, registro central de tipos de evento, estratégia de reconexão com
+  exponential backoff, e gerenciamento de subscriptions com limpeza garantida
+  (zero ghost listeners).
+author: Dewtech Technologies
+metrics:
+  - id: M-01
+    description: 100% de event types com JSON Schema definido
+  - id: M-02
+    description: 100% de subscriptions autorizadas
+  - id: M-03
+    description: 0 ghost listeners após desconexão
+  - id: M-04
+    description: Estratégia de reconexão configurada
+transports:
+  - WebSocket
+  - SSE

package/skills/dare-realtime/subscription_manager.ts

@@ -0,0 +1,106 @@
+/**
+ * dare-realtime — SubscriptionManager
+ * Manages subscriptions per channel with guaranteed cleanup (zero ghost listeners).
+ * License: MIT
+ */
+
+type Handler<T = unknown> = (payload: T) => void;
+
+interface Subscription<T = unknown> {
+  handler: Handler<T>;
+  id: string;
+}
+
+export class SubscriptionManager {
+  private readonly channels: Map<string, Subscription[]> = new Map();
+  private nextId = 0;
+
+  /**
+   * Subscribe to a channel.
+   * @returns Unsubscribe function — call it to remove this specific handler.
+   */
+  subscribe<T = unknown>(channel: string, handler: Handler<T>): () => void {
+    if (!this.channels.has(channel)) {
+      this.channels.set(channel, []);
+    }
+
+    const id = String(this.nextId++);
+    const subscription: Subscription<T> = { handler: handler as Handler, id };
+    this.channels.get(channel)!.push(subscription as Subscription);
+
+    // Return unsubscribe function
+    return () => {
+      const subs = this.channels.get(channel);
+      if (!subs) return;
+      const idx = subs.findIndex((s) => s.id === id);
+      if (idx >= 0) {
+        subs.splice(idx, 1);
+        // Clean up empty channel entry to prevent memory accumulation
+        if (subs.length === 0) {
+          this.channels.delete(channel);
+        }
+      }
+    };
+  }
+
+  /**
+   * Remove all handlers for a channel.
+   * Guarantees zero ghost listeners after this call.
+   */
+  unsubscribeAll(channel: string): void {
+    this.channels.delete(channel);
+  }
+
+  /**
+   * Publish a payload to all handlers of a channel.
+   */
+  publish<T = unknown>(channel: string, payload: T): void {
+    const subs = this.channels.get(channel);
+    if (!subs || subs.length === 0) return;
+
+    // Iterate over a snapshot to avoid issues if a handler removes itself
+    const snapshot = [...subs];
+    for (const sub of snapshot) {
+      sub.handler(payload);
+    }
+  }
+
+  /**
+   * Get all channels that have at least one active subscription.
+   */
+  getActiveChannels(): string[] {
+    return Array.from(this.channels.keys());
+  }
+
+  /**
+   * Count active subscriptions for a specific channel.
+   */
+  countSubscriptions(channel: string): number {
+    return this.channels.get(channel)?.length ?? 0;
+  }
+
+  /**
+   * Total subscriptions across all channels.
+   */
+  get totalSubscriptions(): number {
+    let count = 0;
+    for (const subs of this.channels.values()) {
+      count += subs.length;
+    }
+    return count;
+  }
+
+  /**
+   * True if no active subscriptions exist (no ghost listeners).
+   */
+  get isEmpty(): boolean {
+    return this.channels.size === 0;
+  }
+
+  /**
+   * Remove all subscriptions across all channels.
+   */
+  clear(): void {
+    this.channels.clear();
+  }
+}