@dewtech/dare-cli 3.11.0 → 3.12.0

package/skills/dare-realtime/tests/realtime.spec.ts

@@ -0,0 +1,482 @@
+/**
+ * dare-realtime — test suite
+ * 35+ tests covering schema validator, event registry, reconnect strategy,
+ * subscription manager, and metrics.
+ * License: MIT
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+import { SchemaValidator } from '../schema_validator.js';
+import { EventRegistry } from '../event_registry.js';
+import { ReconnectStrategy } from '../reconnect_strategy.js';
+import { SubscriptionManager } from '../subscription_manager.js';
+import { collectRealtimeMetrics } from '../metrics.js';
+import type { EventSchema } from '../types.js';
+
+// ---------------------------------------------------------------------------
+// SchemaValidator
+// ---------------------------------------------------------------------------
+
+describe('SchemaValidator', () => {
+  let validator: SchemaValidator;
+
+  beforeEach(() => {
+    validator = new SchemaValidator();
+  });
+
+  it('validates a valid payload', () => {
+    const schema: EventSchema = {
+      type: 'object',
+      properties: {
+        userId: { type: 'string' },
+        email: { type: 'string' },
+      },
+      required: ['userId', 'email'],
+    };
+    const result = validator.validate({ userId: '123', email: 'a@b.com' }, schema);
+    expect(result.ok).toBe(true);
+    expect(result.errors).toHaveLength(0);
+  });
+
+  it('fails when required field is missing', () => {
+    const schema: EventSchema = {
+      type: 'object',
+      required: ['userId', 'createdAt'],
+    };
+    const result = validator.validate({ userId: '1' }, schema);
+    expect(result.ok).toBe(false);
+    expect(result.errors.some((e) => e.message.includes('createdAt'))).toBe(true);
+  });
+
+  it('fails when type is wrong', () => {
+    const schema: EventSchema = { type: 'string' };
+    const result = validator.validate(42, schema);
+    expect(result.ok).toBe(false);
+    expect(result.errors[0].message).toContain('Expected type "string"');
+  });
+
+  it('validates nested object', () => {
+    const schema: EventSchema = {
+      type: 'object',
+      properties: {
+        data: {
+          type: 'object',
+          required: ['id'],
+        },
+      },
+      required: ['data'],
+    };
+    const result = validator.validate({ data: { id: '1' } }, schema);
+    expect(result.ok).toBe(true);
+  });
+
+  it('fails on nested missing field', () => {
+    const schema: EventSchema = {
+      type: 'object',
+      properties: {
+        data: { type: 'object', required: ['id'] },
+      },
+      required: ['data'],
+    };
+    const result = validator.validate({ data: {} }, schema);
+    expect(result.ok).toBe(false);
+    expect(result.errors.some((e) => e.field.includes('id'))).toBe(true);
+  });
+
+  it('validates array of strings', () => {
+    const schema: EventSchema = {
+      type: 'array',
+      items: { type: 'string' },
+    };
+    const result = validator.validate(['a', 'b', 'c'], schema);
+    expect(result.ok).toBe(true);
+  });
+
+  it('fails on array with wrong item type', () => {
+    const schema: EventSchema = {
+      type: 'array',
+      items: { type: 'string' },
+    };
+    const result = validator.validate(['a', 2, 'c'], schema);
+    expect(result.ok).toBe(false);
+    expect(result.errors.some((e) => e.field.includes('[1]'))).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// EventRegistry
+// ---------------------------------------------------------------------------
+
+describe('EventRegistry', () => {
+  let registry: EventRegistry;
+
+  beforeEach(() => {
+    registry = new EventRegistry();
+  });
+
+  it('registers and retrieves schema', () => {
+    const schema: EventSchema = { type: 'object', required: ['userId'] };
+    registry.register('user.created', schema);
+    expect(registry.getSchema('user.created')).toEqual(schema);
+  });
+
+  it('throws when registering duplicate type', () => {
+    const schema: EventSchema = { type: 'object' };
+    registry.register('user.created', schema);
+    expect(() => registry.register('user.created', schema)).toThrow('already registered');
+  });
+
+  it('registerOrUpdate overwrites existing', () => {
+    const schema1: EventSchema = { type: 'object', required: ['a'] };
+    const schema2: EventSchema = { type: 'object', required: ['b'] };
+    registry.register('evt', schema1);
+    registry.registerOrUpdate('evt', schema2);
+    expect(registry.getSchema('evt')).toEqual(schema2);
+  });
+
+  it('returns null for unknown schema', () => {
+    expect(registry.getSchema('unknown.type')).toBeNull();
+  });
+
+  it('validate returns error for unknown type', () => {
+    const result = registry.validate('unknown.type', {});
+    expect(result.ok).toBe(false);
+    expect(result.errors[0].message).toContain('Unknown event type');
+  });
+
+  it('validate passes for valid payload', () => {
+    registry.register('user.deleted', {
+      type: 'object',
+      required: ['userId'],
+      properties: { userId: { type: 'string' } },
+    });
+    const result = registry.validate('user.deleted', { userId: '123' });
+    expect(result.ok).toBe(true);
+  });
+
+  it('validate fails for invalid payload', () => {
+    registry.register('order.placed', {
+      type: 'object',
+      required: ['orderId', 'amount'],
+    });
+    const result = registry.validate('order.placed', { orderId: '1' }); // missing amount
+    expect(result.ok).toBe(false);
+  });
+
+  it('listTypes returns all registered types', () => {
+    registry.register('a', { type: 'object' });
+    registry.register('b', { type: 'string' });
+    const types = registry.listTypes();
+    expect(types).toContain('a');
+    expect(types).toContain('b');
+  });
+
+  it('has() returns true for registered type', () => {
+    registry.register('x', { type: 'object' });
+    expect(registry.has('x')).toBe(true);
+  });
+
+  it('has() returns false for unregistered type', () => {
+    expect(registry.has('y')).toBe(false);
+  });
+
+  it('unregister removes event type', () => {
+    registry.register('t', { type: 'object' });
+    registry.unregister('t');
+    expect(registry.has('t')).toBe(false);
+  });
+
+  it('clear removes all types', () => {
+    registry.register('a', { type: 'object' });
+    registry.register('b', { type: 'object' });
+    registry.clear();
+    expect(registry.size).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// ReconnectStrategy
+// ---------------------------------------------------------------------------
+
+describe('ReconnectStrategy', () => {
+  it('first delay is initialDelay (1s default)', () => {
+    const strategy = new ReconnectStrategy();
+    expect(strategy.getDelay(0)).toBe(1_000);
+  });
+
+  it('doubles delay each attempt', () => {
+    const strategy = new ReconnectStrategy({ initialDelayMs: 1_000 });
+    expect(strategy.getDelay(0)).toBe(1_000);
+    expect(strategy.getDelay(1)).toBe(2_000);
+    expect(strategy.getDelay(2)).toBe(4_000);
+    expect(strategy.getDelay(3)).toBe(8_000);
+  });
+
+  it('caps at maxDelay (30s default)', () => {
+    const strategy = new ReconnectStrategy();
+    expect(strategy.getDelay(10)).toBe(30_000); // 1024s > 30s
+  });
+
+  it('respects custom initialDelayMs and maxDelayMs', () => {
+    const strategy = new ReconnectStrategy({ initialDelayMs: 500, maxDelayMs: 5_000 });
+    expect(strategy.getDelay(0)).toBe(500);
+    expect(strategy.getDelay(1)).toBe(1_000);
+    expect(strategy.getDelay(5)).toBe(5_000); // 16_000 > 5_000
+  });
+
+  it('reset() sets attempt back to 0', () => {
+    const strategy = new ReconnectStrategy();
+    strategy.nextDelay();
+    strategy.nextDelay();
+    strategy.reset();
+    expect(strategy.attempt).toBe(0);
+    expect(strategy.nextDelay()).toBe(1_000);
+  });
+
+  it('nextDelay() auto-increments attempt', () => {
+    const strategy = new ReconnectStrategy();
+    const d0 = strategy.nextDelay();
+    const d1 = strategy.nextDelay();
+    const d2 = strategy.nextDelay();
+    expect(d0).toBe(1_000);
+    expect(d1).toBe(2_000);
+    expect(d2).toBe(4_000);
+  });
+
+  it('getDelay(0) with negative returns same as 0', () => {
+    const strategy = new ReconnectStrategy();
+    expect(strategy.getDelay(-1)).toBe(strategy.getDelay(0));
+  });
+
+  it('exposes initialDelay and maxDelay', () => {
+    const strategy = new ReconnectStrategy({ initialDelayMs: 200, maxDelayMs: 10_000 });
+    expect(strategy.initialDelay).toBe(200);
+    expect(strategy.maxDelay).toBe(10_000);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// SubscriptionManager
+// ---------------------------------------------------------------------------
+
+describe('SubscriptionManager', () => {
+  let manager: SubscriptionManager;
+
+  beforeEach(() => {
+    manager = new SubscriptionManager();
+  });
+
+  it('subscribe and publish delivers payload', () => {
+    const handler = vi.fn();
+    manager.subscribe('channel:1', handler);
+    manager.publish('channel:1', { type: 'update', data: 'x' });
+    expect(handler).toHaveBeenCalledOnce();
+    expect(handler).toHaveBeenCalledWith({ type: 'update', data: 'x' });
+  });
+
+  it('unsubscribe function removes specific handler', () => {
+    const h1 = vi.fn();
+    const h2 = vi.fn();
+    const unsub1 = manager.subscribe('ch', h1);
+    manager.subscribe('ch', h2);
+
+    unsub1();
+    manager.publish('ch', 'payload');
+    expect(h1).not.toHaveBeenCalled();
+    expect(h2).toHaveBeenCalledOnce();
+  });
+
+  it('unsubscribeAll removes all handlers for channel', () => {
+    const h1 = vi.fn();
+    const h2 = vi.fn();
+    manager.subscribe('ch', h1);
+    manager.subscribe('ch', h2);
+    manager.unsubscribeAll('ch');
+    manager.publish('ch', 'x');
+    expect(h1).not.toHaveBeenCalled();
+    expect(h2).not.toHaveBeenCalled();
+  });
+
+  it('getActiveChannels returns only channels with active subscriptions', () => {
+    manager.subscribe('a', vi.fn());
+    manager.subscribe('b', vi.fn());
+    expect(manager.getActiveChannels()).toContain('a');
+    expect(manager.getActiveChannels()).toContain('b');
+  });
+
+  it('channel removed from active after unsubscribeAll', () => {
+    manager.subscribe('ch', vi.fn());
+    manager.unsubscribeAll('ch');
+    expect(manager.getActiveChannels()).not.toContain('ch');
+  });
+
+  it('channel removed from active after last unsubscribe', () => {
+    const unsub = manager.subscribe('ch', vi.fn());
+    unsub();
+    expect(manager.getActiveChannels()).not.toContain('ch');
+    expect(manager.isEmpty).toBe(true);
+  });
+
+  it('zero ghost listeners after unsubscribeAll', () => {
+    manager.subscribe('ch', vi.fn());
+    manager.subscribe('ch', vi.fn());
+    manager.unsubscribeAll('ch');
+    expect(manager.countSubscriptions('ch')).toBe(0);
+    expect(manager.isEmpty).toBe(true);
+  });
+
+  it('multiple channels are independent', () => {
+    const h1 = vi.fn();
+    const h2 = vi.fn();
+    manager.subscribe('a', h1);
+    manager.subscribe('b', h2);
+    manager.publish('a', 'msg');
+    expect(h1).toHaveBeenCalledOnce();
+    expect(h2).not.toHaveBeenCalled();
+  });
+
+  it('publish to unknown channel does not throw', () => {
+    expect(() => manager.publish('no-subs', 'x')).not.toThrow();
+  });
+
+  it('totalSubscriptions counts across channels', () => {
+    manager.subscribe('a', vi.fn());
+    manager.subscribe('a', vi.fn());
+    manager.subscribe('b', vi.fn());
+    expect(manager.totalSubscriptions).toBe(3);
+  });
+
+  it('clear() removes everything', () => {
+    manager.subscribe('a', vi.fn());
+    manager.subscribe('b', vi.fn());
+    manager.clear();
+    expect(manager.isEmpty).toBe(true);
+    expect(manager.totalSubscriptions).toBe(0);
+  });
+
+  it('handler called with correct type when typed', () => {
+    const results: string[] = [];
+    manager.subscribe<string>('typed', (payload) => results.push(payload));
+    manager.publish<string>('typed', 'hello');
+    expect(results).toEqual(['hello']);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Metrics
+// ---------------------------------------------------------------------------
+
+describe('collectRealtimeMetrics', () => {
+  it('M-01 passes when all events have schemas', () => {
+    const results = collectRealtimeMetrics({
+      eventTypesWithSchema: 5,
+      totalEventTypes: 5,
+      authorizedSubscriptions: 3,
+      totalSubscriptions: 3,
+      ghostListenerCount: 0,
+      reconnectConfigured: true,
+    });
+    expect(results.find((r) => r.id === 'M-01')!.pass).toBe(true);
+  });
+
+  it('M-01 fails when event types missing schema', () => {
+    const results = collectRealtimeMetrics({
+      eventTypesWithSchema: 3,
+      totalEventTypes: 5,
+      authorizedSubscriptions: 0,
+      totalSubscriptions: 0,
+      ghostListenerCount: 0,
+      reconnectConfigured: true,
+    });
+    const m01 = results.find((r) => r.id === 'M-01')!;
+    expect(m01.pass).toBe(false);
+    expect(m01.detail).toContain('2 event type(s) missing schema');
+  });
+
+  it('M-02 passes when all subscriptions authorized', () => {
+    const results = collectRealtimeMetrics({
+      eventTypesWithSchema: 2,
+      totalEventTypes: 2,
+      authorizedSubscriptions: 4,
+      totalSubscriptions: 4,
+      ghostListenerCount: 0,
+      reconnectConfigured: true,
+    });
+    expect(results.find((r) => r.id === 'M-02')!.pass).toBe(true);
+  });
+
+  it('M-02 fails when unauthorized subscriptions exist', () => {
+    const results = collectRealtimeMetrics({
+      eventTypesWithSchema: 2,
+      totalEventTypes: 2,
+      authorizedSubscriptions: 2,
+      totalSubscriptions: 4,
+      ghostListenerCount: 0,
+      reconnectConfigured: true,
+    });
+    expect(results.find((r) => r.id === 'M-02')!.pass).toBe(false);
+  });
+
+  it('M-03 passes when no ghost listeners', () => {
+    const results = collectRealtimeMetrics({
+      eventTypesWithSchema: 2,
+      totalEventTypes: 2,
+      authorizedSubscriptions: 1,
+      totalSubscriptions: 1,
+      ghostListenerCount: 0,
+      reconnectConfigured: true,
+    });
+    expect(results.find((r) => r.id === 'M-03')!.pass).toBe(true);
+  });
+
+  it('M-03 fails when ghost listeners present', () => {
+    const results = collectRealtimeMetrics({
+      eventTypesWithSchema: 2,
+      totalEventTypes: 2,
+      authorizedSubscriptions: 1,
+      totalSubscriptions: 1,
+      ghostListenerCount: 3,
+      reconnectConfigured: true,
+    });
+    const m03 = results.find((r) => r.id === 'M-03')!;
+    expect(m03.pass).toBe(false);
+    expect(m03.detail).toContain('3 ghost listener(s)');
+  });
+
+  it('M-04 passes when reconnect configured', () => {
+    const results = collectRealtimeMetrics({
+      eventTypesWithSchema: 0,
+      totalEventTypes: 0,
+      authorizedSubscriptions: 0,
+      totalSubscriptions: 0,
+      ghostListenerCount: 0,
+      reconnectConfigured: true,
+    });
+    expect(results.find((r) => r.id === 'M-04')!.pass).toBe(true);
+  });
+
+  it('M-04 fails when reconnect not configured', () => {
+    const results = collectRealtimeMetrics({
+      eventTypesWithSchema: 0,
+      totalEventTypes: 0,
+      authorizedSubscriptions: 0,
+      totalSubscriptions: 0,
+      ghostListenerCount: 0,
+      reconnectConfigured: false,
+    });
+    expect(results.find((r) => r.id === 'M-04')!.pass).toBe(false);
+  });
+
+  it('returns exactly 4 metrics', () => {
+    const results = collectRealtimeMetrics({
+      eventTypesWithSchema: 0,
+      totalEventTypes: 0,
+      authorizedSubscriptions: 0,
+      totalSubscriptions: 0,
+      ghostListenerCount: 0,
+      reconnectConfigured: true,
+    });
+    expect(results).toHaveLength(4);
+  });
+});

package/skills/dare-realtime/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "extends": "../../../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": ".",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": [
+    "*.ts",
+    "tests/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist"
+  ]
+}

package/skills/dare-realtime/types.ts

@@ -0,0 +1,51 @@
+/**
+ * dare-realtime — shared types
+ * License: MIT
+ */
+
+export interface ValidationResult {
+  ok: boolean;
+  errors: ValidationError[];
+}
+
+export interface ValidationError {
+  field: string;
+  message: string;
+  value?: unknown;
+}
+
+export interface EventSchema {
+  type: 'object' | 'array' | 'string' | 'number' | 'boolean' | 'null';
+  properties?: Record<string, EventSchema>;
+  required?: string[];
+  items?: EventSchema;
+  [key: string]: unknown;
+}
+
+export interface RegisteredEvent {
+  type: string;
+  schema: EventSchema;
+  registeredAt: number;
+}
+
+export interface RealtimeMetricsInput {
+  /** M-01: number of event types with schema defined */
+  eventTypesWithSchema: number;
+  /** M-01: total event types in use */
+  totalEventTypes: number;
+  /** M-02: number of subscriptions that have auth checks */
+  authorizedSubscriptions: number;
+  /** M-02: total subscriptions */
+  totalSubscriptions: number;
+  /** M-03: known ghost listener count (should be 0) */
+  ghostListenerCount: number;
+  /** M-04: reconnect strategy is configured */
+  reconnectConfigured: boolean;
+}
+
+export interface MetricResult {
+  id: string;
+  pass: boolean;
+  description: string;
+  detail?: string;
+}

package/templates/ide/antigravity/.agents/skills/dare-ai/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: dare-ai
+description: Terminal-first AI providers for DARE enrichment (dare ai doctor/providers/run). Use when running semantic enrichment from the CLI instead of IDE chat.
+---
+
+# dare-ai
+
+Prefer terminal workflows:
+
+```bash
+dare ai doctor
+dare ai providers
+dare reverse --ai --provider codex
+dare dna --ai
+```
+
+Related: `dare-execute --agent --driver codex`

package/templates/ide/antigravity/.agents/skills/dare-blueprint/SKILL.md

@@ -14,6 +14,8 @@ Você é um arquiteto de software especializado em design de APIs e sistemas. Se
 - Necessário documentar endpoints e modelos
 - Segunda fase do Método DARE
 
+> **Equivalente no terminal:** `dare blueprint --ai`
+
 ## Como usar
 
 ### Passo 1: Ler o Design Aprovado

package/templates/ide/antigravity/.agents/skills/dare-design/SKILL.md

@@ -14,6 +14,8 @@ Você é um especialista em planejamento e análise de requisitos. Seu objetivo
 - Necessário documentar escopo e restrições
 - Primeira fase do Método DARE
 
+> **Equivalente no terminal:** `dare design "<description>" --ai`
+
 ## Como usar
 
 ### Passo 1: Entender a Ideia

package/templates/ide/antigravity/.agents/skills/dare-dna/SKILL.md

@@ -5,6 +5,9 @@ description: Camada semântica da extração de DNA do projeto. Roda depois do c
 
 # DARE DNA Skill — Convenções do Projeto (brownfield)
 
+> **Equivalente no terminal:** `dare dna --ai`
+
+
 Você é o agente que transforma os **fatos de convenção** de um codebase legado em **regras acionáveis**.
 Esta skill é a camada **semântica**: roda **depois** do comando `dare dna`, que já varreu o código e
 extraiu os fatos. Sua função é redigir o "como esse codebase faz as coisas" que uma nova feature deve

package/templates/ide/antigravity/.agents/skills/dare-migrate/SKILL.md

@@ -5,6 +5,9 @@ description: Camada semântica da migração (Fase 2 brownfield). Roda depois do
 
 # DARE Migrate Skill — Migração com paridade (brownfield Fase 2)
 
+> **Equivalente no terminal:** `dare migrate --ai`
+
+
 Você é o agente que transforma o entendimento do legado em um **plano de migração com paridade**.
 Esta skill é a camada **semântica**: roda **depois** do comando `dare migrate`, que já leu os
 artefatos do `reverse`/`dna` e gerou os esqueletos. Sua função é **escrever a estratégia de migração

package/templates/ide/antigravity/.agents/skills/dare-patterns/SKILL.md

@@ -1,5 +1,8 @@
 # dare-patterns Skill
 
+> **Equivalente no terminal:** `dare patterns --ai`
+
+
 Expõe `dare patterns` — mineração determinística de padrões brownfield.
 
 ```bash

package/templates/ide/antigravity/.agents/skills/dare-refine/SKILL.md

@@ -5,6 +5,9 @@ description: Analisa complexidade de uma task DARE e, quando alta, quebra em sub
 
 # DARE Refine Skill
 
+> **Equivalente no terminal:** `dare refine <task-id> --split --ai`
+
+
 Você é o refinador de tasks do método DARE. Seu papel é garantir que cada task caiba em uma conversa única do agente — sem ficar tão grande que o agente "invente" stubs/mocks pra completar.
 
 ## Quando usar

package/templates/ide/antigravity/.agents/skills/dare-reverse/SKILL.md

@@ -5,6 +5,9 @@ description: Camada semântica da engenharia reversa (Fase 0 / brownfield). Roda
 
 # DARE Reverse Skill — Engenharia Reversa (Fase 0)
 
+> **Equivalente no terminal:** `dare reverse --ai`
+
+
 Você é o agente da **Fase 0 (brownfield)** do método DARE no Antigravity. Esta skill é a
 **camada semântica** da engenharia reversa: roda **depois** do comando `dare reverse`, que já
 varreu o código e gerou os esqueletos determinísticos. Sua função é **preencher as inferências**

package/templates/ide/antigravity/.agents/skills/dare-review/SKILL.md

@@ -5,6 +5,9 @@ description: Audita uma task DARE implementada — cruza a spec com o código re
 
 # DARE Review Skill
 
+> **Equivalente no terminal:** `dare review <task-id> --ai`
+
+
 Você é o auditor de qualidade do método DARE. Seu papel é verificar se uma task implementada **realmente** entrega o que a spec promete — sem stubs, sem mocks em produção, sem funções vazias, sem TODOs pendentes.
 
 ## Quando usar esta skill

package/templates/ide/claude/.claude/commands/dare-ai.md

@@ -0,0 +1,17 @@
+# /dare-ai
+
+Terminal-first AI providers for DARE command enrichment (`dare ai doctor`, `dare ai providers`, `dare ai run`).
+
+> Prefer running these in the terminal. Brownfield commands also accept `--ai` and `--provider`.
+
+## Commands
+
+```bash
+dare ai doctor
+dare ai providers
+dare ai run --command reverse --facts DARE/REVERSE/reverse-facts.json --provider codex
+```
+
+## Related
+
+`/dare-reverse` · `/dare-dna` · `/dare-execute`

package/templates/ide/claude/.claude/commands/dare-blueprint.md

@@ -4,6 +4,8 @@ Gera **somente** `DARE/BLUEPRINT.md` a partir do `DARE/DESIGN.md`.
 
 > Tasks, DAG e specs de execução são geradas depois com `/dare-tasks`, após aprovação humana do Blueprint.
 
+> **Equivalente no terminal:** `dare blueprint --ai`
+
 ## Como usar
 
 ```

package/templates/ide/claude/.claude/commands/dare-design.md

@@ -2,6 +2,8 @@
 
 Gera ou atualiza o `DARE/DESIGN.md` a partir de uma descrição do projeto ou feature.
 
+> **Equivalente no terminal:** `dare design "<description>" --ai`
+
 ## Como usar
 
 ```