@sparkleideas/shared 3.0.0-alpha.7

package/src/hooks/README.md

@@ -0,0 +1,532 @@
+# V3 Hooks System
+
+Extensible hook points for tool execution, file operations, and lifecycle events. Integrates with the event bus for coordination and monitoring.
+
+## Features
+
+- **26 Hook Events**: Comprehensive lifecycle hooks for tools, files, commands, sessions, agents, tasks, memory, and errors
+- **Priority-Based Execution**: Control execution order with 5 priority levels
+- **Timeout Handling**: Configurable timeouts per hook with graceful degradation
+- **Error Recovery**: Continue execution on errors or abort based on configuration
+- **Context Modification**: Hooks can modify context for downstream hooks
+- **Parallel & Sequential Execution**: Execute hooks in parallel or chain them sequentially
+- **Event Bus Integration**: Emit coordination events to the event bus
+- **Statistics Tracking**: Monitor hook performance and execution metrics
+
+## Installation
+
+```typescript
+import {
+  createHookRegistry,
+  createHookExecutor,
+  HookEvent,
+  HookPriority
+} from '@claude-flow/shared/hooks';
+```
+
+## Quick Start
+
+### 1. Create Registry and Executor
+
+```typescript
+import { createHookRegistry, createHookExecutor } from '@claude-flow/shared/hooks';
+import { createEventBus } from '@claude-flow/shared/core';
+
+const registry = createHookRegistry();
+const eventBus = createEventBus();
+const executor = createHookExecutor(registry, eventBus);
+```
+
+### 2. Register a Hook
+
+```typescript
+const hookId = registry.register(
+  HookEvent.PreToolUse,
+  async (context) => {
+    console.log(`About to use tool: ${context.tool?.name}`);
+
+    // Validate tool parameters
+    if (!context.tool?.parameters) {
+      return {
+        success: false,
+        error: new Error('Missing tool parameters'),
+        abort: true // Abort tool execution
+      };
+    }
+
+    return { success: true };
+  },
+  HookPriority.High,
+  {
+    name: 'Tool Validation Hook',
+    timeout: 5000
+  }
+);
+```
+
+### 3. Execute Hooks
+
+```typescript
+const result = await executor.execute(
+  HookEvent.PreToolUse,
+  {
+    event: HookEvent.PreToolUse,
+    timestamp: new Date(),
+    tool: {
+      name: 'Read',
+      parameters: { path: '/path/to/file.ts' },
+      category: 'file'
+    }
+  }
+);
+
+if (result.success) {
+  console.log(`✓ All hooks passed (${result.hooksExecuted} executed)`);
+} else {
+  console.log(`✗ Hook execution failed: ${result.hooksFailed} failures`);
+}
+```
+
+## Hook Events
+
+### Tool Execution
+
+```typescript
+HookEvent.PreToolUse   // Before any tool is used
+HookEvent.PostToolUse  // After tool execution completes
+```
+
+### File Operations
+
+```typescript
+HookEvent.PreRead      // Before reading a file
+HookEvent.PostRead     // After reading a file
+HookEvent.PreWrite     // Before writing a file
+HookEvent.PostWrite    // After writing a file
+HookEvent.PreEdit      // Before editing a file
+HookEvent.PostEdit     // After editing a file
+```
+
+### Command Execution
+
+```typescript
+HookEvent.PreCommand   // Before executing bash command
+HookEvent.PostCommand  // After command execution
+```
+
+### Session Lifecycle
+
+```typescript
+HookEvent.SessionStart   // When session starts
+HookEvent.SessionEnd     // When session ends
+HookEvent.SessionPause   // When session is paused
+HookEvent.SessionResume  // When session resumes
+```
+
+### Agent Lifecycle
+
+```typescript
+HookEvent.PreAgentSpawn       // Before spawning agent
+HookEvent.PostAgentSpawn      // After agent spawned
+HookEvent.PreAgentTerminate   // Before terminating agent
+HookEvent.PostAgentTerminate  // After agent terminated
+```
+
+### Task Lifecycle
+
+```typescript
+HookEvent.PreTaskExecute    // Before task execution
+HookEvent.PostTaskExecute   // After task execution
+HookEvent.PreTaskComplete   // Before marking task complete
+HookEvent.PostTaskComplete  // After task completed
+```
+
+### Memory Operations
+
+```typescript
+HookEvent.PreMemoryStore      // Before storing memory
+HookEvent.PostMemoryStore     // After storing memory
+HookEvent.PreMemoryRetrieve   // Before retrieving memory
+HookEvent.PostMemoryRetrieve  // After retrieving memory
+```
+
+### Error Handling
+
+```typescript
+HookEvent.OnError     // When error occurs
+HookEvent.OnWarning   // When warning occurs
+```
+
+## Hook Priorities
+
+Control execution order with priority levels:
+
+```typescript
+HookPriority.Critical = 1000    // Execute first
+HookPriority.High     = 500
+HookPriority.Normal   = 0       // Default
+HookPriority.Low      = -500
+HookPriority.Lowest   = -1000   // Execute last
+```
+
+## Advanced Usage
+
+### Context Modification
+
+Hooks can modify context for downstream hooks:
+
+```typescript
+registry.register(
+  HookEvent.PreCommand,
+  async (context) => {
+    // Add risk assessment to context
+    const isDestructive = context.command?.command.includes('rm -rf');
+
+    return {
+      success: true,
+      data: {
+        metadata: {
+          ...context.metadata,
+          riskLevel: isDestructive ? 'high' : 'low'
+        }
+      }
+    };
+  },
+  HookPriority.High
+);
+
+// Later hook can access the risk level
+registry.register(
+  HookEvent.PreCommand,
+  async (context) => {
+    if (context.metadata?.riskLevel === 'high') {
+      console.warn('⚠️  High-risk command detected!');
+    }
+    return { success: true };
+  },
+  HookPriority.Normal
+);
+```
+
+### Abort Operations
+
+Hooks can abort the operation:
+
+```typescript
+registry.register(
+  HookEvent.PreCommand,
+  async (context) => {
+    const isDangerous = context.command?.command.includes('format c:');
+
+    if (isDangerous) {
+      return {
+        success: false,
+        abort: true, // Prevent command execution
+        error: new Error('Dangerous command blocked by security hook')
+      };
+    }
+
+    return { success: true };
+  },
+  HookPriority.Critical
+);
+```
+
+### Timeout Handling
+
+Configure timeouts per hook:
+
+```typescript
+registry.register(
+  HookEvent.PreToolUse,
+  async (context) => {
+    // Expensive operation
+    await analyzeCodeComplexity(context.tool?.parameters);
+    return { success: true };
+  },
+  HookPriority.Normal,
+  {
+    timeout: 3000 // 3 second timeout
+  }
+);
+```
+
+### Parallel Execution
+
+Execute hooks for multiple events in parallel:
+
+```typescript
+const results = await executor.executeParallel(
+  [HookEvent.PreRead, HookEvent.PreWrite, HookEvent.PreEdit],
+  [
+    { event: HookEvent.PreRead, timestamp: new Date(), file: { path: 'a.ts', operation: 'read' } },
+    { event: HookEvent.PreWrite, timestamp: new Date(), file: { path: 'b.ts', operation: 'write' } },
+    { event: HookEvent.PreEdit, timestamp: new Date(), file: { path: 'c.ts', operation: 'edit' } }
+  ],
+  { maxParallel: 3 }
+);
+```
+
+### Sequential Execution with Context Chaining
+
+Execute hooks sequentially, passing context modifications:
+
+```typescript
+const result = await executor.executeSequential(
+  [
+    HookEvent.PreTaskExecute,
+    HookEvent.PostTaskExecute,
+    HookEvent.PreTaskComplete,
+    HookEvent.PostTaskComplete
+  ],
+  {
+    event: HookEvent.PreTaskExecute,
+    timestamp: new Date(),
+    task: { id: 'task-1', description: 'Process data' }
+  }
+);
+
+// result.finalContext contains all modifications from all hooks
+```
+
+## Hook Statistics
+
+Track hook performance:
+
+```typescript
+const stats = registry.getStats();
+
+console.log(`Total hooks: ${stats.totalHooks}`);
+console.log(`Total executions: ${stats.totalExecutions}`);
+console.log(`Total failures: ${stats.totalFailures}`);
+console.log(`Average execution time: ${stats.avgExecutionTime}ms`);
+
+// Hooks by event type
+for (const [event, count] of Object.entries(stats.byEvent)) {
+  console.log(`${event}: ${count} hooks`);
+}
+```
+
+## Integration with Event Bus
+
+The executor emits coordination events to the event bus:
+
+```typescript
+eventBus.on('hooks:pre-execute', (event) => {
+  console.log(`Executing ${event.payload.hookCount} hooks for ${event.payload.event}`);
+});
+
+eventBus.on('hooks:post-execute', (event) => {
+  console.log(`Completed in ${event.payload.totalExecutionTime}ms`);
+});
+
+eventBus.on('hooks:error', (event) => {
+  console.error(`Hook ${event.payload.hookId} failed:`, event.payload.error);
+});
+```
+
+## Best Practices
+
+### 1. Use Appropriate Priorities
+
+- `Critical`: Security checks, validation that must happen first
+- `High`: Important preprocessing (risk assessment, logging)
+- `Normal`: Standard business logic
+- `Low`: Optional enhancements, metrics
+- `Lowest`: Cleanup, final logging
+
+### 2. Handle Errors Gracefully
+
+```typescript
+registry.register(
+  HookEvent.PreToolUse,
+  async (context) => {
+    try {
+      await performValidation(context);
+      return { success: true };
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error : new Error(String(error)),
+        continueChain: true // Allow other hooks to run
+      };
+    }
+  }
+);
+```
+
+### 3. Keep Hooks Fast
+
+Hooks should be fast (<100ms). For expensive operations:
+
+```typescript
+registry.register(
+  HookEvent.PostToolUse,
+  async (context) => {
+    // Queue expensive work for background processing
+    backgroundQueue.add({
+      type: 'analyze-tool-usage',
+      context
+    });
+
+    return { success: true };
+  },
+  HookPriority.Low
+);
+```
+
+### 4. Use Descriptive Names
+
+```typescript
+registry.register(
+  HookEvent.PreCommand,
+  handler,
+  HookPriority.Critical,
+  {
+    name: 'Security: Prevent Destructive Commands',
+    metadata: {
+      purpose: 'Block dangerous shell commands',
+      blockedPatterns: ['rm -rf /', 'format c:']
+    }
+  }
+);
+```
+
+## Example: Pre-Edit Hook for Learning
+
+```typescript
+import { HookEvent, HookPriority } from '@claude-flow/shared/hooks';
+
+// Register pre-edit hook for context retrieval
+registry.register(
+  HookEvent.PreEdit,
+  async (context) => {
+    const filePath = context.file?.path;
+
+    if (!filePath) {
+      return { success: true };
+    }
+
+    // Get similar past edits from ReasoningBank
+    const similarEdits = await reasoningBank.searchPatterns({
+      task: `Edit file: ${filePath}`,
+      k: 5,
+      minReward: 0.85
+    });
+
+    console.log(`📚 Found ${similarEdits.length} similar past edits`);
+
+    return {
+      success: true,
+      data: {
+        metadata: {
+          ...context.metadata,
+          learningContext: similarEdits,
+          editCount: similarEdits.length
+        }
+      }
+    };
+  },
+  HookPriority.High,
+  {
+    name: 'Learning: Pre-Edit Context Retrieval',
+    timeout: 2000
+  }
+);
+
+// Register post-edit hook for learning storage
+registry.register(
+  HookEvent.PostEdit,
+  async (context) => {
+    const success = context.metadata?.success ?? true;
+    const filePath = context.file?.path;
+
+    if (!filePath) {
+      return { success: true };
+    }
+
+    // Store edit pattern for future learning
+    await reasoningBank.storePattern({
+      sessionId: context.session?.id || 'unknown',
+      task: `Edit file: ${filePath}`,
+      input: context.file?.previousContent || '',
+      output: context.file?.content || '',
+      reward: success ? 0.9 : 0.3,
+      success,
+      tokensUsed: estimateTokens(context.file?.content),
+      latencyMs: context.metadata?.executionTime || 0
+    });
+
+    return { success: true };
+  },
+  HookPriority.Normal,
+  {
+    name: 'Learning: Post-Edit Pattern Storage',
+    timeout: 1000
+  }
+);
+```
+
+## API Reference
+
+### HookRegistry
+
+- `register(event, handler, priority, options)` - Register a hook
+- `unregister(hookId)` - Unregister a hook
+- `unregisterAll(event?)` - Unregister all hooks for an event
+- `getHandlers(event, includeDisabled)` - Get handlers for an event
+- `getHook(hookId)` - Get hook by ID
+- `enable(hookId)` - Enable a hook
+- `disable(hookId)` - Disable a hook
+- `listHooks(filter)` - List all hooks with optional filter
+- `getEventTypes()` - Get all event types with hooks
+- `count(event?)` - Get hook count
+- `getStats()` - Get execution statistics
+- `resetStats()` - Reset statistics
+- `has(hookId)` - Check if hook exists
+- `clear()` - Clear all hooks
+
+### HookExecutor
+
+- `execute(event, context, options)` - Execute hooks for an event
+- `executeWithTimeout(event, context, timeout)` - Execute with timeout
+- `executeParallel(events, contexts, options)` - Execute multiple events in parallel
+- `executeSequential(events, initialContext, options)` - Execute sequentially with context chaining
+- `setEventBus(eventBus)` - Set event bus for coordination
+- `getRegistry()` - Get hook registry
+
+## Testing
+
+Run the test suite:
+
+```bash
+cd /workspaces/claude-flow/v3/@claude-flow/shared
+npm test -- hooks.test.ts
+```
+
+All 23 tests pass:
+- 11 registry tests
+- 12 executor tests
+
+## File Structure
+
+```
+v3/@claude-flow/shared/src/hooks/
+├── types.ts           # Type definitions (~150 lines)
+├── registry.ts        # Hook registry (~200 lines)
+├── executor.ts        # Hook executor (~250 lines)
+├── index.ts           # Main exports
+├── hooks.test.ts      # Test suite (~20 tests)
+└── README.md          # This file
+```
+
+## Integration Points
+
+- **Event Bus**: Emits coordination events (`hooks:pre-execute`, `hooks:post-execute`, `hooks:error`)
+- **Event Store**: Can log hook executions for audit trail (ADR-007)
+- **ReasoningBank**: Hooks can integrate with learning system for context retrieval and pattern storage
+- **Security**: Critical hooks can enforce security policies (CVE-1, CVE-2, CVE-3)
+
+## License
+
+Part of Claude-Flow V3 - See main LICENSE file