@sparkleideas/shared 3.0.0-alpha.7

package/src/core/event-bus.ts

@@ -0,0 +1,236 @@
+/**
+ * V3 Event Bus
+ * Core event pub/sub implementation
+ */
+
+import type {
+  IEvent,
+  IEventBus,
+  IEventCreate,
+  IEventHandler,
+  IEventSubscription,
+  IEventFilter,
+} from './interfaces/event.interface.js';
+import { randomBytes } from 'crypto';
+
+// Secure event ID generation
+function generateSecureEventId(): string {
+  const timestamp = Date.now().toString(36);
+  const random = randomBytes(12).toString('hex');
+  return `evt_${timestamp}_${random}`;
+}
+
+/**
+ * Event subscription implementation
+ */
+class EventSubscription implements IEventSubscription {
+  private active = true;
+  private paused = false;
+
+  constructor(
+    readonly id: string,
+    readonly filter: IEventFilter,
+    private removeCallback: () => void,
+  ) {}
+
+  unsubscribe(): void {
+    this.active = false;
+    this.removeCallback();
+  }
+
+  pause(): void {
+    this.paused = true;
+  }
+
+  resume(): void {
+    this.paused = false;
+  }
+
+  isActive(): boolean {
+    return this.active && !this.paused;
+  }
+}
+
+/**
+ * Event bus implementation
+ */
+export class EventBus implements IEventBus {
+  private handlers = new Map<string, Set<IEventHandler>>();
+  private subscriptions = new Map<string, { filter: IEventFilter; handler: IEventHandler; subscription: EventSubscription }>();
+  private subscriptionId = 0;
+
+  emit<T = unknown>(type: string, payload: T, options?: Partial<IEventCreate<T>>): void {
+    const event = this.createEvent(type, payload, options);
+    this.dispatchEvent(event);
+  }
+
+  async emitAsync<T = unknown>(type: string, payload: T, options?: Partial<IEventCreate<T>>): Promise<void> {
+    const event = this.createEvent(type, payload, options);
+    await this.dispatchEventAsync(event);
+  }
+
+  on<T = unknown>(type: string, handler: IEventHandler<T>): IEventSubscription {
+    return this.subscribe({ types: [type] }, handler);
+  }
+
+  subscribe<T = unknown>(filter: IEventFilter, handler: IEventHandler<T>): IEventSubscription {
+    const id = `sub_${++this.subscriptionId}`;
+
+    // Register for all matching types
+    const types = filter.types ?? ['*'];
+    for (const type of types) {
+      let handlers = this.handlers.get(type);
+      if (!handlers) {
+        handlers = new Set();
+        this.handlers.set(type, handlers);
+      }
+      handlers.add(handler as IEventHandler);
+    }
+
+    const subscription = new EventSubscription(id, filter, () => {
+      this.removeSubscription(id);
+    });
+
+    this.subscriptions.set(id, { filter, handler: handler as IEventHandler, subscription });
+
+    return subscription;
+  }
+
+  once<T = unknown>(type: string, handler: IEventHandler<T>): IEventSubscription {
+    const wrappedHandler: IEventHandler<T> = async (event) => {
+      subscription.unsubscribe();
+      await handler(event);
+    };
+
+    const subscription = this.on(type, wrappedHandler);
+    return subscription;
+  }
+
+  off(type: string, handler: IEventHandler): void {
+    const handlers = this.handlers.get(type);
+    if (handlers) {
+      handlers.delete(handler);
+      if (handlers.size === 0) {
+        this.handlers.delete(type);
+      }
+    }
+  }
+
+  removeAllListeners(type?: string): void {
+    if (type) {
+      this.handlers.delete(type);
+    } else {
+      this.handlers.clear();
+    }
+  }
+
+  listenerCount(type: string): number {
+    return this.handlers.get(type)?.size ?? 0;
+  }
+
+  eventNames(): string[] {
+    return Array.from(this.handlers.keys());
+  }
+
+  private createEvent<T>(type: string, payload: T, options?: Partial<IEventCreate<T>>): IEvent<T> {
+    return {
+      id: generateSecureEventId(),
+      type,
+      timestamp: new Date(),
+      source: options?.source ?? 'event-bus',
+      payload,
+      priority: options?.priority,
+      correlationId: options?.correlationId,
+      causationId: options?.causationId,
+      metadata: options?.metadata,
+    };
+  }
+
+  private dispatchEvent<T>(event: IEvent<T>): void {
+    // Get handlers for specific type
+    const typeHandlers = this.handlers.get(event.type);
+
+    // Get wildcard handlers
+    const wildcardHandlers = this.handlers.get('*');
+
+    const allHandlers = new Set<IEventHandler>();
+
+    if (typeHandlers) {
+      for (const handler of typeHandlers) {
+        allHandlers.add(handler);
+      }
+    }
+
+    if (wildcardHandlers) {
+      for (const handler of wildcardHandlers) {
+        allHandlers.add(handler);
+      }
+    }
+
+    for (const handler of allHandlers) {
+      try {
+        const result = handler(event);
+        if (result instanceof Promise) {
+          result.catch((error) => {
+            console.error(`Error in async event handler for ${event.type}:`, error);
+          });
+        }
+      } catch (error) {
+        console.error(`Error in event handler for ${event.type}:`, error);
+      }
+    }
+  }
+
+  private async dispatchEventAsync<T>(event: IEvent<T>): Promise<void> {
+    const typeHandlers = this.handlers.get(event.type);
+    const wildcardHandlers = this.handlers.get('*');
+
+    const allHandlers = new Set<IEventHandler>();
+
+    if (typeHandlers) {
+      for (const handler of typeHandlers) {
+        allHandlers.add(handler);
+      }
+    }
+
+    if (wildcardHandlers) {
+      for (const handler of wildcardHandlers) {
+        allHandlers.add(handler);
+      }
+    }
+
+    const promises = Array.from(allHandlers).map(async (handler) => {
+      try {
+        await handler(event);
+      } catch (error) {
+        console.error(`Error in event handler for ${event.type}:`, error);
+      }
+    });
+
+    await Promise.allSettled(promises);
+  }
+
+  private removeSubscription(id: string): void {
+    const sub = this.subscriptions.get(id);
+    if (sub) {
+      const types = sub.filter.types ?? ['*'];
+      for (const type of types) {
+        const handlers = this.handlers.get(type);
+        if (handlers) {
+          handlers.delete(sub.handler);
+          if (handlers.size === 0) {
+            this.handlers.delete(type);
+          }
+        }
+      }
+      this.subscriptions.delete(id);
+    }
+  }
+}
+
+/**
+ * Create a new event bus instance
+ */
+export function createEventBus(): IEventBus {
+  return new EventBus();
+}

package/src/core/index.ts

@@ -0,0 +1,22 @@
+/**
+ * V3 Core Module - Public API
+ * Domain-Driven Design with Clean Architecture
+ *
+ * This module provides the core architecture for @sparkleideas/claude-flow v3:
+ * - Decomposed orchestrator (task, session, health, lifecycle management)
+ * - Event-driven architecture with event bus and coordinator
+ * - Type-safe configuration with Zod validation
+ * - Clean interfaces following DDD principles
+ */
+
+// Interfaces (Domain contracts)
+export * from './interfaces/index.js';
+
+// Event system
+export { EventBus, createEventBus } from './event-bus.js';
+
+// Orchestrator components (decomposed)
+export * from './orchestrator/index.js';
+
+// Configuration
+export * from './config/index.js';

package/src/core/interfaces/agent.interface.ts

@@ -0,0 +1,251 @@
+/**
+ * V3 Agent Interfaces
+ * Domain-Driven Design - Agent Lifecycle Bounded Context
+ */
+
+/**
+ * Agent status in the system
+ */
+export type AgentStatus = 'spawning' | 'active' | 'idle' | 'busy' | 'error' | 'terminated';
+
+/**
+ * Agent type classification
+ */
+export type AgentType =
+  | 'coder'
+  | 'reviewer'
+  | 'tester'
+  | 'researcher'
+  | 'planner'
+  | 'architect'
+  | 'coordinator'
+  | 'security'
+  | 'performance'
+  | 'custom';
+
+/**
+ * Agent capability declaration
+ */
+export interface IAgentCapability {
+  name: string;
+  level: 'basic' | 'intermediate' | 'advanced' | 'expert';
+  description?: string;
+}
+
+/**
+ * Agent configuration for spawning
+ */
+export interface IAgentConfig {
+  readonly id: string;
+  readonly name: string;
+  readonly type: AgentType | string;
+
+  capabilities: string[];
+  maxConcurrentTasks: number;
+  priority: number;
+
+  timeout?: number;
+  retryPolicy?: {
+    maxRetries: number;
+    backoffMs: number;
+    backoffMultiplier: number;
+  };
+
+  resources?: {
+    maxMemoryMb?: number;
+    maxCpuPercent?: number;
+  };
+
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Core agent entity
+ */
+export interface IAgent {
+  readonly id: string;
+  readonly name: string;
+  readonly type: AgentType | string;
+  readonly config: IAgentConfig;
+  readonly createdAt: Date;
+
+  status: AgentStatus;
+  currentTaskCount: number;
+  lastActivity: Date;
+
+  sessionId?: string;
+  terminalId?: string;
+  memoryBankId?: string;
+
+  metrics?: {
+    tasksCompleted: number;
+    tasksFailed: number;
+    avgTaskDuration: number;
+    errorCount: number;
+    uptime: number;
+  };
+
+  health?: {
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    lastCheck: Date;
+    issues?: string[];
+  };
+}
+
+/**
+ * Agent session for tracking active work
+ */
+export interface IAgentSession {
+  readonly id: string;
+  readonly agentId: string;
+  readonly startTime: Date;
+
+  status: 'active' | 'idle' | 'terminated';
+  terminalId: string;
+  memoryBankId: string;
+
+  lastActivity: Date;
+  endTime?: Date;
+
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Agent pool for managing multiple agents
+ */
+export interface IAgentPool {
+  /**
+   * Add an agent to the pool
+   */
+  add(agent: IAgent): void;
+
+  /**
+   * Remove an agent from the pool
+   */
+  remove(agentId: string): boolean;
+
+  /**
+   * Get an agent by ID
+   */
+  get(agentId: string): IAgent | undefined;
+
+  /**
+   * Get all agents in the pool
+   */
+  getAll(): IAgent[];
+
+  /**
+   * Get agents by status
+   */
+  getByStatus(status: AgentStatus): IAgent[];
+
+  /**
+   * Get agents by type
+   */
+  getByType(type: AgentType | string): IAgent[];
+
+  /**
+   * Get available agents (can accept more tasks)
+   */
+  getAvailable(): IAgent[];
+
+  /**
+   * Get pool size
+   */
+  size(): number;
+
+  /**
+   * Check if pool has capacity
+   */
+  hasCapacity(maxSize: number): boolean;
+
+  /**
+   * Clear all agents
+   */
+  clear(): void;
+}
+
+/**
+ * Agent lifecycle manager interface
+ */
+export interface IAgentLifecycleManager {
+  /**
+   * Spawn a new agent
+   */
+  spawn(config: IAgentConfig): Promise<IAgent>;
+
+  /**
+   * Spawn multiple agents in parallel
+   */
+  spawnBatch(configs: IAgentConfig[]): Promise<Map<string, IAgent>>;
+
+  /**
+   * Terminate an agent
+   */
+  terminate(agentId: string, reason?: string): Promise<void>;
+
+  /**
+   * Terminate all agents
+   */
+  terminateAll(reason?: string): Promise<void>;
+
+  /**
+   * Restart an agent
+   */
+  restart(agentId: string): Promise<IAgent>;
+
+  /**
+   * Update agent configuration
+   */
+  updateConfig(agentId: string, config: Partial<IAgentConfig>): Promise<void>;
+
+  /**
+   * Get agent by ID
+   */
+  getAgent(agentId: string): IAgent | undefined;
+
+  /**
+   * Get all agents
+   */
+  getAllAgents(): IAgent[];
+
+  /**
+   * Get active agents count
+   */
+  getActiveCount(): number;
+
+  /**
+   * Check agent health
+   */
+  checkHealth(agentId: string): Promise<IAgent['health']>;
+}
+
+/**
+ * Agent registry for type definitions
+ */
+export interface IAgentRegistry {
+  /**
+   * Register an agent type with default config
+   */
+  register(type: string, defaultConfig: Partial<IAgentConfig>): void;
+
+  /**
+   * Unregister an agent type
+   */
+  unregister(type: string): boolean;
+
+  /**
+   * Get default config for a type
+   */
+  getDefaultConfig(type: string): Partial<IAgentConfig> | undefined;
+
+  /**
+   * Get all registered types
+   */
+  getRegisteredTypes(): string[];
+
+  /**
+   * Check if a type is registered
+   */
+  isRegistered(type: string): boolean;
+}