claude-flow 3.28.0 → 3.29.0

package/v3/@claude-flow/shared/dist/hooks/index.js

@@ -0,0 +1,51 @@
+/**
+ * V3 Hooks System - Main Export
+ *
+ * Provides extensible hook points for tool execution, file operations,
+ * and session lifecycle events. Integrates with event bus for coordination.
+ *
+ * Example usage:
+ *
+ * ```typescript
+ * import { createHookRegistry, createHookExecutor, HookEvent, HookPriority } from '@claude-flow/shared/hooks';
+ *
+ * const registry = createHookRegistry();
+ * const executor = createHookExecutor(registry, eventBus);
+ *
+ * // Register a hook
+ * const hookId = registry.register(
+ *   HookEvent.PreToolUse,
+ *   async (context) => {
+ *     console.log('Before tool use:', context.tool?.name);
+ *     return { success: true };
+ *   },
+ *   HookPriority.High
+ * );
+ *
+ * // Execute hooks
+ * const result = await executor.execute(
+ *   HookEvent.PreToolUse,
+ *   {
+ *     event: HookEvent.PreToolUse,
+ *     timestamp: new Date(),
+ *     tool: { name: 'Read', parameters: { path: 'file.ts' } }
+ *   }
+ * );
+ *
+ * // Unregister hook
+ * registry.unregister(hookId);
+ * ```
+ *
+ * @module v3/shared/hooks
+ */
+export { HookEvent, HookPriority, } from './types.js';
+// Export registry
+export { HookRegistry, createHookRegistry, } from './registry.js';
+export { HookExecutor, createHookExecutor, } from './executor.js';
+// Export task hooks
+export { TaskHooksManager, createTaskHooksManager, } from './task-hooks.js';
+// Export session hooks
+export { SessionHooksManager, createSessionHooksManager, InMemorySessionStorage, } from './session-hooks.js';
+// Export safety hooks
+export { BashSafetyHook, createBashSafetyHook, FileOrganizationHook, createFileOrganizationHook, GitCommitHook, createGitCommitHook, } from './safety/index.js';
+//# sourceMappingURL=index.js.map

package/v3/@claude-flow/shared/dist/hooks/registry.d.ts

@@ -0,0 +1,133 @@
+/**
+ * V3 Hooks System - Hook Registry
+ *
+ * Central registry for managing hook definitions and lifecycle.
+ * Provides registration, unregistration, and discovery of hooks.
+ *
+ * @module v3/shared/hooks/registry
+ */
+import { HookEvent, HookPriority, HookHandler, HookDefinition, HookStats } from './types.js';
+/**
+ * Hook registry implementation
+ */
+export declare class HookRegistry {
+    private hooks;
+    private hooksById;
+    private hookIdCounter;
+    private stats;
+    /**
+     * Register a new hook
+     *
+     * @param event - Hook event type
+     * @param handler - Hook handler function
+     * @param priority - Hook priority (default: Normal)
+     * @param options - Additional hook options
+     * @returns Hook ID for later unregistration
+     */
+    register(event: HookEvent, handler: HookHandler, priority?: HookPriority, options?: {
+        name?: string;
+        timeout?: number;
+        enabled?: boolean;
+        metadata?: Record<string, unknown>;
+    }): string;
+    /**
+     * Unregister a hook by ID
+     *
+     * @param hookId - Hook ID to unregister
+     * @returns Whether hook was found and removed
+     */
+    unregister(hookId: string): boolean;
+    /**
+     * Unregister all hooks for an event
+     *
+     * @param event - Event type to clear hooks for
+     * @returns Number of hooks removed
+     */
+    unregisterAll(event?: HookEvent): number;
+    /**
+     * Get all hooks for a specific event (sorted by priority)
+     *
+     * @param event - Event type
+     * @param includeDisabled - Whether to include disabled hooks
+     * @returns Array of hook definitions
+     */
+    getHandlers(event: HookEvent, includeDisabled?: boolean): HookDefinition[];
+    /**
+     * Get a hook by ID
+     *
+     * @param hookId - Hook ID
+     * @returns Hook definition or undefined
+     */
+    getHook(hookId: string): HookDefinition | undefined;
+    /**
+     * Enable a hook
+     *
+     * @param hookId - Hook ID
+     * @returns Whether hook was found and enabled
+     */
+    enable(hookId: string): boolean;
+    /**
+     * Disable a hook
+     *
+     * @param hookId - Hook ID
+     * @returns Whether hook was found and disabled
+     */
+    disable(hookId: string): boolean;
+    /**
+     * List all registered hooks
+     *
+     * @param filter - Optional filter options
+     * @returns Array of hook definitions
+     */
+    listHooks(filter?: {
+        event?: HookEvent;
+        enabled?: boolean;
+        minPriority?: HookPriority;
+    }): HookDefinition[];
+    /**
+     * Get all event types with registered hooks
+     *
+     * @returns Array of event types
+     */
+    getEventTypes(): HookEvent[];
+    /**
+     * Get count of hooks for an event
+     *
+     * @param event - Event type (optional)
+     * @returns Hook count
+     */
+    count(event?: HookEvent): number;
+    /**
+     * Record hook execution statistics
+     *
+     * @param success - Whether execution succeeded
+     * @param executionTime - Execution time in ms
+     */
+    recordExecution(success: boolean, executionTime: number): void;
+    /**
+     * Get hook statistics
+     *
+     * @returns Hook statistics
+     */
+    getStats(): HookStats;
+    /**
+     * Reset statistics
+     */
+    resetStats(): void;
+    /**
+     * Check if a hook exists
+     *
+     * @param hookId - Hook ID
+     * @returns Whether hook exists
+     */
+    has(hookId: string): boolean;
+    /**
+     * Clear all hooks and reset state
+     */
+    clear(): void;
+}
+/**
+ * Create a new hook registry
+ */
+export declare function createHookRegistry(): HookRegistry;
+//# sourceMappingURL=registry.d.ts.map

package/v3/@claude-flow/shared/dist/hooks/registry.js

@@ -0,0 +1,277 @@
+/**
+ * V3 Hooks System - Hook Registry
+ *
+ * Central registry for managing hook definitions and lifecycle.
+ * Provides registration, unregistration, and discovery of hooks.
+ *
+ * @module v3/shared/hooks/registry
+ */
+import { HookPriority, } from './types.js';
+/**
+ * Hook registry implementation
+ */
+export class HookRegistry {
+    hooks = new Map();
+    hooksById = new Map();
+    hookIdCounter = 0;
+    // Statistics tracking
+    stats = {
+        executions: 0,
+        failures: 0,
+        totalExecutionTime: 0,
+    };
+    /**
+     * Register a new hook
+     *
+     * @param event - Hook event type
+     * @param handler - Hook handler function
+     * @param priority - Hook priority (default: Normal)
+     * @param options - Additional hook options
+     * @returns Hook ID for later unregistration
+     */
+    register(event, handler, priority = HookPriority.Normal, options = {}) {
+        // Generate unique hook ID
+        const id = `hook_${++this.hookIdCounter}_${Date.now()}`;
+        // Create hook definition
+        const definition = {
+            id,
+            event,
+            handler,
+            priority,
+            name: options.name,
+            enabled: options.enabled ?? true,
+            timeout: options.timeout,
+            metadata: options.metadata,
+        };
+        // Add to event-specific list
+        let eventHooks = this.hooks.get(event);
+        if (!eventHooks) {
+            eventHooks = [];
+            this.hooks.set(event, eventHooks);
+        }
+        eventHooks.push(definition);
+        // Sort by priority (highest first)
+        eventHooks.sort((a, b) => b.priority - a.priority);
+        // Add to ID map
+        this.hooksById.set(id, definition);
+        return id;
+    }
+    /**
+     * Unregister a hook by ID
+     *
+     * @param hookId - Hook ID to unregister
+     * @returns Whether hook was found and removed
+     */
+    unregister(hookId) {
+        const definition = this.hooksById.get(hookId);
+        if (!definition) {
+            return false;
+        }
+        // Remove from event-specific list
+        const eventHooks = this.hooks.get(definition.event);
+        if (eventHooks) {
+            const index = eventHooks.findIndex(h => h.id === hookId);
+            if (index !== -1) {
+                eventHooks.splice(index, 1);
+            }
+            // Clean up empty arrays
+            if (eventHooks.length === 0) {
+                this.hooks.delete(definition.event);
+            }
+        }
+        // Remove from ID map
+        this.hooksById.delete(hookId);
+        return true;
+    }
+    /**
+     * Unregister all hooks for an event
+     *
+     * @param event - Event type to clear hooks for
+     * @returns Number of hooks removed
+     */
+    unregisterAll(event) {
+        if (event) {
+            const eventHooks = this.hooks.get(event) || [];
+            const count = eventHooks.length;
+            // Remove from ID map
+            for (const hook of eventHooks) {
+                this.hooksById.delete(hook.id);
+            }
+            // Clear event hooks
+            this.hooks.delete(event);
+            return count;
+        }
+        else {
+            // Clear all hooks
+            const count = this.hooksById.size;
+            this.hooks.clear();
+            this.hooksById.clear();
+            this.hookIdCounter = 0;
+            return count;
+        }
+    }
+    /**
+     * Get all hooks for a specific event (sorted by priority)
+     *
+     * @param event - Event type
+     * @param includeDisabled - Whether to include disabled hooks
+     * @returns Array of hook definitions
+     */
+    getHandlers(event, includeDisabled = false) {
+        const eventHooks = this.hooks.get(event) || [];
+        if (includeDisabled) {
+            return [...eventHooks];
+        }
+        return eventHooks.filter(h => h.enabled);
+    }
+    /**
+     * Get a hook by ID
+     *
+     * @param hookId - Hook ID
+     * @returns Hook definition or undefined
+     */
+    getHook(hookId) {
+        return this.hooksById.get(hookId);
+    }
+    /**
+     * Enable a hook
+     *
+     * @param hookId - Hook ID
+     * @returns Whether hook was found and enabled
+     */
+    enable(hookId) {
+        const hook = this.hooksById.get(hookId);
+        if (hook) {
+            hook.enabled = true;
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Disable a hook
+     *
+     * @param hookId - Hook ID
+     * @returns Whether hook was found and disabled
+     */
+    disable(hookId) {
+        const hook = this.hooksById.get(hookId);
+        if (hook) {
+            hook.enabled = false;
+            return true;
+        }
+        return false;
+    }
+    /**
+     * List all registered hooks
+     *
+     * @param filter - Optional filter options
+     * @returns Array of hook definitions
+     */
+    listHooks(filter) {
+        let hooks;
+        if (filter?.event) {
+            hooks = this.hooks.get(filter.event) || [];
+        }
+        else {
+            hooks = Array.from(this.hooksById.values());
+        }
+        // Apply filters
+        if (filter?.enabled !== undefined) {
+            hooks = hooks.filter(h => h.enabled === filter.enabled);
+        }
+        if (filter?.minPriority !== undefined) {
+            const minPriority = filter.minPriority;
+            hooks = hooks.filter(h => h.priority >= minPriority);
+        }
+        return hooks;
+    }
+    /**
+     * Get all event types with registered hooks
+     *
+     * @returns Array of event types
+     */
+    getEventTypes() {
+        return Array.from(this.hooks.keys());
+    }
+    /**
+     * Get count of hooks for an event
+     *
+     * @param event - Event type (optional)
+     * @returns Hook count
+     */
+    count(event) {
+        if (event) {
+            return this.hooks.get(event)?.length || 0;
+        }
+        return this.hooksById.size;
+    }
+    /**
+     * Record hook execution statistics
+     *
+     * @param success - Whether execution succeeded
+     * @param executionTime - Execution time in ms
+     */
+    recordExecution(success, executionTime) {
+        this.stats.executions++;
+        this.stats.totalExecutionTime += executionTime;
+        if (!success) {
+            this.stats.failures++;
+        }
+    }
+    /**
+     * Get hook statistics
+     *
+     * @returns Hook statistics
+     */
+    getStats() {
+        const byEvent = {};
+        for (const [event, hooks] of this.hooks) {
+            byEvent[event] = hooks.filter(h => h.enabled).length;
+        }
+        return {
+            totalHooks: this.hooksById.size,
+            byEvent,
+            totalExecutions: this.stats.executions,
+            totalFailures: this.stats.failures,
+            avgExecutionTime: this.stats.executions > 0
+                ? this.stats.totalExecutionTime / this.stats.executions
+                : 0,
+            totalExecutionTime: this.stats.totalExecutionTime,
+        };
+    }
+    /**
+     * Reset statistics
+     */
+    resetStats() {
+        this.stats = {
+            executions: 0,
+            failures: 0,
+            totalExecutionTime: 0,
+        };
+    }
+    /**
+     * Check if a hook exists
+     *
+     * @param hookId - Hook ID
+     * @returns Whether hook exists
+     */
+    has(hookId) {
+        return this.hooksById.has(hookId);
+    }
+    /**
+     * Clear all hooks and reset state
+     */
+    clear() {
+        this.hooks.clear();
+        this.hooksById.clear();
+        this.hookIdCounter = 0;
+        this.resetStats();
+    }
+}
+/**
+ * Create a new hook registry
+ */
+export function createHookRegistry() {
+    return new HookRegistry();
+}
+//# sourceMappingURL=registry.js.map

package/v3/@claude-flow/shared/dist/hooks/safety/bash-safety.d.ts

@@ -0,0 +1,105 @@
+/**
+ * V3 Bash Safety Hook
+ *
+ * TypeScript conversion of V2 bash-hook.sh.
+ * Provides command safety analysis, dangerous command detection,
+ * secret detection, and safe alternatives.
+ *
+ * @module v3/shared/hooks/safety/bash-safety
+ */
+import { HookContext, HookResult } from '../types.js';
+import { HookRegistry } from '../registry.js';
+/**
+ * Bash safety hook result
+ */
+export interface BashSafetyResult extends HookResult {
+    /** Risk level assessment */
+    riskLevel: 'low' | 'medium' | 'high' | 'critical';
+    /** Whether the command should be blocked */
+    blocked: boolean;
+    /** Reason for blocking (if blocked) */
+    blockReason?: string;
+    /** Modified command (if applicable) */
+    modifiedCommand?: string;
+    /** Detected risks */
+    risks: CommandRisk[];
+    /** Safe alternatives */
+    safeAlternatives?: string[];
+    /** Warnings (non-blocking) */
+    warnings?: string[];
+    /** Missing dependencies detected */
+    missingDependencies?: string[];
+    /** Redacted command (secrets removed) */
+    redactedCommand?: string;
+}
+/**
+ * Command risk definition
+ */
+export interface CommandRisk {
+    /** Risk type */
+    type: 'dangerous' | 'destructive' | 'secret' | 'privilege' | 'network' | 'resource';
+    /** Risk severity */
+    severity: 'low' | 'medium' | 'high' | 'critical';
+    /** Risk description */
+    description: string;
+    /** Pattern that matched */
+    pattern?: string;
+}
+/**
+ * Bash Safety Hook Manager
+ */
+export declare class BashSafetyHook {
+    private registry;
+    private blockedCommands;
+    private availableDependencies;
+    constructor(registry: HookRegistry);
+    /**
+     * Register bash safety hooks
+     */
+    private registerHooks;
+    /**
+     * Detect available dependencies
+     */
+    private detectAvailableDependencies;
+    /**
+     * Analyze a command for safety
+     */
+    analyzeCommand(context: HookContext): Promise<BashSafetyResult>;
+    /**
+     * Detect secrets in command
+     */
+    private detectSecrets;
+    /**
+     * Check for missing dependencies
+     */
+    private checkDependencies;
+    /**
+     * Calculate overall risk level
+     */
+    private calculateRiskLevel;
+    /**
+     * Create a result object
+     */
+    private createResult;
+    /**
+     * Manually analyze a command
+     */
+    analyze(command: string): Promise<BashSafetyResult>;
+    /**
+     * Add a custom dangerous pattern
+     */
+    addDangerousPattern(pattern: RegExp, type: CommandRisk['type'], severity: CommandRisk['severity'], description: string, block?: boolean): void;
+    /**
+     * Mark a dependency as available
+     */
+    markDependencyAvailable(dependency: string): void;
+    /**
+     * Check if a command would be blocked
+     */
+    wouldBlock(command: string): boolean;
+}
+/**
+ * Create bash safety hook
+ */
+export declare function createBashSafetyHook(registry: HookRegistry): BashSafetyHook;
+//# sourceMappingURL=bash-safety.d.ts.map