@sparkleideas/shared 3.0.0-alpha.7

package/src/hooks/types.ts

@@ -0,0 +1,357 @@
+/**
+ * V3 Hooks System - Type Definitions
+ *
+ * Provides extensible hook points for tool execution, file operations,
+ * and session lifecycle events. Integrates with event bus for coordination.
+ *
+ * @module v3/shared/hooks/types
+ */
+
+/**
+ * Hook event types
+ */
+export enum HookEvent {
+  // Tool execution hooks
+  PreToolUse = 'hook:pre-tool-use',
+  PostToolUse = 'hook:post-tool-use',
+
+  // File operation hooks
+  PreEdit = 'hook:pre-edit',
+  PostEdit = 'hook:post-edit',
+  PreRead = 'hook:pre-read',
+  PostRead = 'hook:post-read',
+  PreWrite = 'hook:pre-write',
+  PostWrite = 'hook:post-write',
+
+  // Command execution hooks
+  PreCommand = 'hook:pre-command',
+  PostCommand = 'hook:post-command',
+
+  // Session lifecycle hooks
+  SessionStart = 'hook:session-start',
+  SessionEnd = 'hook:session-end',
+  SessionPause = 'hook:session-pause',
+  SessionResume = 'hook:session-resume',
+
+  // Agent lifecycle hooks
+  PreAgentSpawn = 'hook:pre-agent-spawn',
+  PostAgentSpawn = 'hook:post-agent-spawn',
+  PreAgentTerminate = 'hook:pre-agent-terminate',
+  PostAgentTerminate = 'hook:post-agent-terminate',
+
+  // Task lifecycle hooks
+  PreTaskExecute = 'hook:pre-task-execute',
+  PostTaskExecute = 'hook:post-task-execute',
+  PreTaskComplete = 'hook:pre-task-complete',
+  PostTaskComplete = 'hook:post-task-complete',
+
+  // Memory hooks
+  PreMemoryStore = 'hook:pre-memory-store',
+  PostMemoryStore = 'hook:post-memory-store',
+  PreMemoryRetrieve = 'hook:pre-memory-retrieve',
+  PostMemoryRetrieve = 'hook:post-memory-retrieve',
+
+  // Error hooks
+  OnError = 'hook:on-error',
+  OnWarning = 'hook:on-warning',
+}
+
+/**
+ * Hook priority levels (higher = earlier execution)
+ */
+export enum HookPriority {
+  Critical = 1000,
+  High = 500,
+  Normal = 0,
+  Low = -500,
+  Lowest = -1000,
+}
+
+/**
+ * Tool information for tool-related hooks
+ */
+export interface ToolInfo {
+  /** Tool name (e.g., 'Read', 'Write', 'Bash') */
+  name: string;
+
+  /** Tool parameters */
+  parameters: Record<string, unknown>;
+
+  /** Estimated execution time in ms */
+  estimatedDuration?: number;
+
+  /** Tool category */
+  category?: 'file' | 'bash' | 'search' | 'edit' | 'git' | 'other';
+}
+
+/**
+ * Command information for command-related hooks
+ */
+export interface CommandInfo {
+  /** Command string */
+  command: string;
+
+  /** Working directory */
+  cwd?: string;
+
+  /** Environment variables */
+  env?: Record<string, string>;
+
+  /** Command timeout in ms */
+  timeout?: number;
+
+  /** Whether command is destructive */
+  isDestructive?: boolean;
+}
+
+/**
+ * File operation information
+ */
+export interface FileOperationInfo {
+  /** File path */
+  path: string;
+
+  /** Operation type */
+  operation: 'read' | 'write' | 'edit' | 'delete';
+
+  /** File content (for write/edit operations) */
+  content?: string;
+
+  /** Previous content (for edit operations) */
+  previousContent?: string;
+
+  /** File size in bytes */
+  size?: number;
+}
+
+/**
+ * Session information
+ */
+export interface SessionInfo {
+  /** Session ID */
+  id: string;
+
+  /** Session start time */
+  startTime: Date;
+
+  /** Session end time */
+  endTime?: Date;
+
+  /** Session metadata */
+  metadata?: Record<string, unknown>;
+
+  /** User ID (if available) */
+  userId?: string;
+}
+
+/**
+ * Agent information
+ */
+export interface AgentInfo {
+  /** Agent ID */
+  id: string;
+
+  /** Agent type/role */
+  type: string;
+
+  /** Agent configuration */
+  config?: Record<string, unknown>;
+
+  /** Parent agent ID */
+  parentId?: string;
+}
+
+/**
+ * Task information
+ */
+export interface TaskInfo {
+  /** Task ID */
+  id: string;
+
+  /** Task description */
+  description: string;
+
+  /** Task priority */
+  priority?: number;
+
+  /** Assigned agent ID */
+  agentId?: string;
+
+  /** Task metadata */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Memory operation information
+ */
+export interface MemoryInfo {
+  /** Memory key */
+  key: string;
+
+  /** Memory value */
+  value?: unknown;
+
+  /** Memory namespace */
+  namespace?: string;
+
+  /** TTL in seconds */
+  ttl?: number;
+}
+
+/**
+ * Error information
+ */
+export interface ErrorInfo {
+  /** Error object */
+  error: Error;
+
+  /** Error context */
+  context?: string;
+
+  /** Error severity */
+  severity: 'warning' | 'error' | 'fatal';
+
+  /** Recoverable flag */
+  recoverable: boolean;
+}
+
+/**
+ * Hook context - contains information about the event being hooked
+ */
+export interface HookContext {
+  /** Event type */
+  event: HookEvent;
+
+  /** Timestamp when hook was triggered */
+  timestamp: Date;
+
+  /** Correlation ID for tracking related events */
+  correlationId?: string;
+
+  /** Tool information (for tool hooks) */
+  tool?: ToolInfo;
+
+  /** Command information (for command hooks) */
+  command?: CommandInfo;
+
+  /** File operation information (for file hooks) */
+  file?: FileOperationInfo;
+
+  /** Session information (for session hooks) */
+  session?: SessionInfo;
+
+  /** Agent information (for agent hooks) */
+  agent?: AgentInfo;
+
+  /** Task information (for task hooks) */
+  task?: TaskInfo;
+
+  /** Memory information (for memory hooks) */
+  memory?: MemoryInfo;
+
+  /** Error information (for error hooks) */
+  error?: ErrorInfo;
+
+  /** Additional metadata */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Hook result - returned by hook handlers
+ */
+export interface HookResult {
+  /** Whether the hook succeeded */
+  success: boolean;
+
+  /** Result data (can modify context) */
+  data?: Partial<HookContext>;
+
+  /** Error if hook failed */
+  error?: Error;
+
+  /** Whether to continue executing other hooks */
+  continueChain?: boolean;
+
+  /** Whether to abort the operation */
+  abort?: boolean;
+
+  /** Hook execution time in ms */
+  executionTime?: number;
+
+  /** Additional metadata */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Hook handler function type
+ */
+export type HookHandler = (context: HookContext) => Promise<HookResult> | HookResult;
+
+/**
+ * Hook definition with metadata
+ */
+export interface HookDefinition {
+  /** Unique hook ID */
+  id: string;
+
+  /** Hook event type */
+  event: HookEvent;
+
+  /** Hook handler function */
+  handler: HookHandler;
+
+  /** Hook priority */
+  priority: HookPriority;
+
+  /** Hook name/description */
+  name?: string;
+
+  /** Whether hook is enabled */
+  enabled: boolean;
+
+  /** Hook timeout in ms */
+  timeout?: number;
+
+  /** Hook metadata */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Hook statistics
+ */
+export interface HookStats {
+  /** Total hooks registered */
+  totalHooks: number;
+
+  /** Hooks by event type */
+  byEvent: Record<HookEvent, number>;
+
+  /** Total executions */
+  totalExecutions: number;
+
+  /** Total failures */
+  totalFailures: number;
+
+  /** Average execution time in ms */
+  avgExecutionTime: number;
+
+  /** Total execution time in ms */
+  totalExecutionTime: number;
+}
+
+/**
+ * Hook execution options
+ */
+export interface HookExecutionOptions {
+  /** Timeout in ms (overrides hook-specific timeout) */
+  timeout?: number;
+
+  /** Whether to continue on error */
+  continueOnError?: boolean;
+
+  /** Maximum parallel executions */
+  maxParallel?: number;
+
+  /** Whether to collect results from all hooks */
+  collectResults?: boolean;
+}

package/src/hooks/verify-exports.test.ts

@@ -0,0 +1,125 @@
+/**
+ * V3 Hooks System - Export Verification
+ *
+ * Verifies that all exports are accessible through the public API.
+ *
+ * @module v3/shared/hooks/verify-exports.test
+ */
+
+import { describe, it, expect } from 'vitest';
+
+describe('Hooks Module Exports', () => {
+  it('should export all types from main module', async () => {
+    const module = await import('./index.js');
+
+    // Enums
+    expect(module.HookEvent).toBeDefined();
+    expect(module.HookPriority).toBeDefined();
+
+    // Classes
+    expect(module.HookRegistry).toBeDefined();
+    expect(module.HookExecutor).toBeDefined();
+
+    // Factory functions
+    expect(module.createHookRegistry).toBeDefined();
+    expect(module.createHookExecutor).toBeDefined();
+  });
+
+  it('should export types (type-only imports)', () => {
+    // This test just verifies TypeScript compilation
+    // Types can't be checked at runtime
+    type Test1 = import('./types.js').HookContext;
+    type Test2 = import('./types.js').HookResult;
+    type Test3 = import('./types.js').HookHandler;
+    type Test4 = import('./types.js').HookDefinition;
+    type Test5 = import('./types.js').HookStats;
+    type Test6 = import('./types.js').HookExecutionOptions;
+    type Test7 = import('./types.js').ToolInfo;
+    type Test8 = import('./types.js').CommandInfo;
+    type Test9 = import('./types.js').FileOperationInfo;
+    type Test10 = import('./types.js').SessionInfo;
+    type Test11 = import('./types.js').AgentInfo;
+    type Test12 = import('./types.js').TaskInfo;
+    type Test13 = import('./types.js').MemoryInfo;
+    type Test14 = import('./types.js').ErrorInfo;
+
+    expect(true).toBe(true);
+  });
+
+  it('should create instances from exported factories', () => {
+    const { createHookRegistry, createHookExecutor } = require('./index.js');
+
+    const registry = createHookRegistry();
+    expect(registry).toBeDefined();
+    expect(typeof registry.register).toBe('function');
+    expect(typeof registry.unregister).toBe('function');
+
+    const executor = createHookExecutor(registry);
+    expect(executor).toBeDefined();
+    expect(typeof executor.execute).toBe('function');
+  });
+
+  it('should have all 26 hook events defined', () => {
+    const { HookEvent } = require('./index.js');
+
+    const expectedEvents = [
+      'PreToolUse',
+      'PostToolUse',
+      'PreEdit',
+      'PostEdit',
+      'PreRead',
+      'PostRead',
+      'PreWrite',
+      'PostWrite',
+      'PreCommand',
+      'PostCommand',
+      'SessionStart',
+      'SessionEnd',
+      'SessionPause',
+      'SessionResume',
+      'PreAgentSpawn',
+      'PostAgentSpawn',
+      'PreAgentTerminate',
+      'PostAgentTerminate',
+      'PreTaskExecute',
+      'PostTaskExecute',
+      'PreTaskComplete',
+      'PostTaskComplete',
+      'PreMemoryStore',
+      'PostMemoryStore',
+      'PreMemoryRetrieve',
+      'PostMemoryRetrieve',
+      'OnError',
+      'OnWarning',
+    ];
+
+    for (const event of expectedEvents) {
+      expect(HookEvent[event]).toBeDefined();
+    }
+  });
+
+  it('should have all 5 priority levels defined', () => {
+    const { HookPriority } = require('./index.js');
+
+    expect(HookPriority.Critical).toBe(1000);
+    expect(HookPriority.High).toBe(500);
+    expect(HookPriority.Normal).toBe(0);
+    expect(HookPriority.Low).toBe(-500);
+    expect(HookPriority.Lowest).toBe(-1000);
+  });
+});
+
+describe('Hooks Integration with Shared Module', () => {
+  it('should be importable from @sparkleideas/shared', async () => {
+    // This would be the actual import path in production
+    const module = await import('../index.js');
+
+    // Verify hooks are exported from main shared module
+    expect(module.HookEvent).toBeDefined();
+    expect(module.HookPriority).toBeDefined();
+    expect(module.HookRegistry).toBeDefined();
+    expect(module.HookExecutor).toBeDefined();
+    expect(module.createHookRegistry).toBeDefined();
+    expect(module.createHookExecutor).toBeDefined();
+  });
+});

package/src/index.ts

@@ -0,0 +1,195 @@
+/**
+ * @sparkleideas/shared - Shared Module
+ * Common types, events, utilities, and core interfaces for V3 Claude-Flow
+ *
+ * Based on ADR-002 (DDD) and ADR-006 (Unified Memory Service)
+ */
+
+// =============================================================================
+// Types - Primary type definitions (from ./types.js)
+// =============================================================================
+export * from './types.js';
+
+// =============================================================================
+// Events - Event bus and basic event interfaces (from ./events.js)
+// =============================================================================
+export { EventBus } from './events.js';
+export type { IEventBus, EventFilter } from './events.js';
+
+// =============================================================================
+// Event Sourcing - ADR-007 Domain events and event store
+// (from ./events/index.js - no duplicates with ./events.js)
+// =============================================================================
+export type {
+  DomainEvent,
+  AllDomainEvents,
+  AgentSpawnedEvent,
+  AgentStartedEvent,
+  AgentStoppedEvent,
+  AgentFailedEvent,
+  AgentStatusChangedEvent,
+  AgentTaskAssignedEvent,
+  AgentTaskCompletedEvent,
+  TaskCreatedEvent,
+  TaskStartedEvent,
+  TaskCompletedEvent,
+  TaskFailedEvent,
+  TaskBlockedEvent,
+  TaskQueuedEvent,
+  MemoryStoredEvent,
+  MemoryRetrievedEvent,
+  MemoryDeletedEvent,
+  MemoryExpiredEvent,
+  SwarmInitializedEvent,
+  SwarmScaledEvent,
+  SwarmTerminatedEvent,
+  SwarmPhaseChangedEvent,
+  SwarmMilestoneReachedEvent,
+  SwarmErrorEvent,
+  EventStoreConfig,
+  EventSnapshot,
+  EventStoreStats,
+  AgentProjectionState,
+  TaskProjectionState,
+  MemoryProjectionState,
+  AggregateRoot,
+  ReconstructorOptions,
+} from './events/index.js';
+
+export {
+  createAgentSpawnedEvent,
+  createAgentStartedEvent,
+  createAgentStoppedEvent,
+  createAgentFailedEvent,
+  createTaskCreatedEvent,
+  createTaskStartedEvent,
+  createTaskCompletedEvent,
+  createTaskFailedEvent,
+  createMemoryStoredEvent,
+  createMemoryRetrievedEvent,
+  createMemoryDeletedEvent,
+  createSwarmInitializedEvent,
+  createSwarmScaledEvent,
+  createSwarmTerminatedEvent,
+  EventStore,
+  Projection,
+  AgentStateProjection,
+  TaskHistoryProjection,
+  MemoryIndexProjection,
+  StateReconstructor,
+  createStateReconstructor,
+  AgentAggregate,
+  TaskAggregate,
+} from './events/index.js';
+
+// =============================================================================
+// Plugin System - ADR-004
+// =============================================================================
+export * from './plugin-loader.js';
+export * from './plugin-registry.js';
+
+// =============================================================================
+// Core - DDD interfaces, config, orchestrator
+// Note: Only export non-overlapping items from core to avoid duplicates with types.js
+// =============================================================================
+export {
+  // Event Bus
+  createEventBus,
+  // Orchestrator
+  createOrchestrator,
+  TaskManager,
+  SessionManager,
+  HealthMonitor,
+  LifecycleManager,
+  EventCoordinator,
+  // Config validation/loading
+  ConfigLoader,
+  loadConfig,
+  ConfigValidator,
+  validateAgentConfig,
+  validateTaskConfig,
+  validateSwarmConfig,
+  validateMemoryConfig,
+  validateMCPServerConfig,
+  validateOrchestratorConfig,
+  validateSystemConfig,
+  // Defaults
+  defaultAgentConfig,
+  defaultTaskConfig,
+  defaultSwarmConfigCore,
+  defaultMemoryConfig,
+  defaultMCPServerConfig,
+  defaultOrchestratorConfig,
+  defaultSystemConfig,
+  agentTypePresets,
+  mergeWithDefaults,
+} from './core/index.js';
+
+export type {
+  // Config types
+  LoadedConfig,
+  ConfigSource,
+  ValidationResult,
+  ValidationError,
+  // Orchestrator types
+  OrchestratorFacadeConfig,
+  OrchestratorComponents,
+  SessionManagerConfig,
+  HealthMonitorConfig,
+  LifecycleManagerConfig,
+  // Schema types (from config - note these extend the basic types from types.js)
+  AgentConfig,
+  TaskConfig,
+  SwarmConfig as SwarmConfigSchema,
+  MemoryConfig,
+  MCPServerConfig,
+  OrchestratorConfig,
+  SystemConfig,
+  AgentConfigInput,
+  TaskConfigInput,
+  SwarmConfigInput,
+  MemoryConfigInput,
+  MCPServerConfigInput,
+  OrchestratorConfigInput,
+  SystemConfigInput,
+  // Interface types
+  ITask,
+  ITaskCreate,
+  ITaskResult,
+  IAgent,
+  IAgentConfig,
+  IEventBus as ICoreEventBus,
+  IMemoryBackend as ICoreMemoryBackend,
+  ISwarmConfig,
+  ISwarmState,
+  ICoordinator,
+  ICoordinationManager,
+  IHealthStatus,
+  IComponentHealth,
+  IHealthMonitor,
+  IMetricsCollector,
+  IOrchestratorMetrics,
+  IOrchestrator,
+  SwarmTopology,
+  CoordinationStatus,
+} from './core/index.js';
+
+// =============================================================================
+// Hooks System
+// =============================================================================
+export * from './hooks/index.js';
+
+// =============================================================================
+// Security Utilities
+// =============================================================================
+export * from './security/index.js';
+
+// =============================================================================
+// Resilience Patterns
+// =============================================================================
+export * from './resilience/index.js';
+
+// =============================================================================
+// Services
+// =============================================================================
+export * from './services/index.js';