claude-flow 3.27.4 → 3.29.0

package/v3/@claude-flow/shared/dist/plugin-interface.d.ts

@@ -0,0 +1,544 @@
+/**
+ * V3 Plugin Interface
+ * Domain-Driven Design - Plugin-Based Architecture (ADR-004)
+ *
+ * Microkernel pattern for extensible Claude-Flow V3
+ * Enables modular extension points for agents, tasks, MCP tools, CLI commands, and memory backends
+ */
+import type { IEventBus } from './core/interfaces/event.interface.js';
+import type { IAgentConfig } from './core/interfaces/agent.interface.js';
+import type { MCPTool } from './types/mcp.types.js';
+/**
+ * Logger interface for plugin context
+ */
+export interface ILogger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+/**
+ * Service container for dependency injection
+ */
+export interface ServiceContainer {
+    /**
+     * Register a service in the container
+     */
+    register<T>(name: string, service: T): void;
+    /**
+     * Get a service from the container
+     */
+    get<T>(name: string): T | undefined;
+    /**
+     * Check if a service is registered
+     */
+    has(name: string): boolean;
+    /**
+     * Get all registered service names
+     */
+    getServiceNames(): string[];
+}
+/**
+ * Plugin configuration
+ */
+export interface PluginConfig {
+    /**
+     * Plugin-specific configuration
+     */
+    [key: string]: unknown;
+    /**
+     * Enable/disable features
+     */
+    features?: Record<string, boolean>;
+    /**
+     * Resource limits
+     */
+    resources?: {
+        maxMemoryMb?: number;
+        maxCpuPercent?: number;
+    };
+}
+/**
+ * Plugin context provided during initialization
+ * Contains services and resources available to plugins
+ */
+export interface PluginContext {
+    /**
+     * Plugin-specific configuration
+     */
+    config: PluginConfig;
+    /**
+     * Event bus for pub/sub communication
+     */
+    eventBus: IEventBus;
+    /**
+     * Logger instance
+     */
+    logger: ILogger;
+    /**
+     * Service container for dependency injection
+     */
+    services: ServiceContainer;
+}
+/**
+ * Agent type definition for plugin registration
+ */
+export interface AgentTypeDefinition {
+    /**
+     * Unique type identifier
+     */
+    type: string;
+    /**
+     * Human-readable name
+     */
+    name: string;
+    /**
+     * Description of agent capabilities
+     */
+    description: string;
+    /**
+     * Default configuration for this agent type
+     */
+    defaultConfig: Partial<IAgentConfig>;
+    /**
+     * Required capabilities for this agent type
+     */
+    requiredCapabilities?: string[];
+    /**
+     * Optional metadata
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Task type definition for plugin registration
+ */
+export interface TaskTypeDefinition {
+    /**
+     * Unique type identifier
+     */
+    type: string;
+    /**
+     * Human-readable name
+     */
+    name: string;
+    /**
+     * Description of task purpose
+     */
+    description: string;
+    /**
+     * Default priority (0-100)
+     */
+    defaultPriority: number;
+    /**
+     * Default timeout in milliseconds
+     */
+    defaultTimeout: number;
+    /**
+     * Required agent capabilities to execute this task
+     */
+    requiredCapabilities?: string[];
+    /**
+     * Task input schema (JSON Schema)
+     */
+    inputSchema?: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+    /**
+     * Optional metadata
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * MCP tool definition for plugin registration
+ */
+export interface MCPToolDefinition extends MCPTool {
+    /**
+     * Plugin that registered this tool
+     */
+    pluginName?: string;
+    /**
+     * Tool version
+     */
+    version?: string;
+    /**
+     * Optional metadata
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * CLI command definition for plugin registration
+ */
+export interface CLICommandDefinition {
+    /**
+     * Command name
+     */
+    name: string;
+    /**
+     * Command description
+     */
+    description: string;
+    /**
+     * Command aliases
+     */
+    aliases?: string[];
+    /**
+     * Command options
+     */
+    options?: CLICommandOption[];
+    /**
+     * Command arguments
+     */
+    arguments?: CLICommandArgument[];
+    /**
+     * Command handler function
+     */
+    handler: (args: CLICommandArgs) => Promise<void> | void;
+    /**
+     * Optional metadata
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * CLI command option
+ */
+export interface CLICommandOption {
+    /**
+     * Option name (without dashes)
+     */
+    name: string;
+    /**
+     * Short flag (single character)
+     */
+    short?: string;
+    /**
+     * Option description
+     */
+    description: string;
+    /**
+     * Option type
+     */
+    type: 'string' | 'number' | 'boolean';
+    /**
+     * Default value
+     */
+    default?: string | number | boolean;
+    /**
+     * Is this option required?
+     */
+    required?: boolean;
+}
+/**
+ * CLI command argument
+ */
+export interface CLICommandArgument {
+    /**
+     * Argument name
+     */
+    name: string;
+    /**
+     * Argument description
+     */
+    description: string;
+    /**
+     * Is this argument required?
+     */
+    required?: boolean;
+    /**
+     * Default value
+     */
+    default?: string;
+    /**
+     * Allowed values (for validation)
+     */
+    choices?: string[];
+}
+/**
+ * CLI command parsed arguments
+ */
+export interface CLICommandArgs {
+    /**
+     * Positional arguments
+     */
+    _: string[];
+    /**
+     * Named options
+     */
+    [key: string]: unknown;
+}
+/**
+ * Memory backend factory for plugin registration
+ */
+export interface MemoryBackendFactory {
+    /**
+     * Backend name
+     */
+    name: string;
+    /**
+     * Backend description
+     */
+    description: string;
+    /**
+     * Create a new backend instance
+     */
+    create(config: MemoryBackendConfig): Promise<IMemoryBackend>;
+    /**
+     * Backend capabilities
+     */
+    capabilities: {
+        supportsVectorSearch: boolean;
+        supportsFullText: boolean;
+        supportsTransactions: boolean;
+        supportsPersistence: boolean;
+    };
+    /**
+     * Optional metadata
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Memory backend configuration
+ */
+export interface MemoryBackendConfig {
+    /**
+     * Storage path or connection string
+     */
+    path?: string;
+    /**
+     * Backend-specific options
+     */
+    options?: Record<string, unknown>;
+    /**
+     * Resource limits
+     */
+    limits?: {
+        maxMemoryMb?: number;
+        maxStorageMb?: number;
+    };
+}
+/**
+ * Memory backend interface
+ */
+export interface IMemoryBackend {
+    /**
+     * Initialize the backend
+     */
+    initialize(): Promise<void>;
+    /**
+     * Shutdown the backend
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Store a memory entry
+     */
+    store(key: string, value: unknown, metadata?: Record<string, unknown>): Promise<void>;
+    /**
+     * Retrieve a memory entry
+     */
+    retrieve(key: string): Promise<unknown | null>;
+    /**
+     * Delete a memory entry
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Search memory entries
+     */
+    search(query: string, options?: MemorySearchOptions): Promise<MemorySearchResult[]>;
+    /**
+     * Clear all memory entries
+     */
+    clear(): Promise<void>;
+    /**
+     * Get backend statistics
+     */
+    getStats(): Promise<MemoryBackendStats>;
+}
+/**
+ * Memory search options
+ */
+export interface MemorySearchOptions {
+    /**
+     * Maximum number of results
+     */
+    limit?: number;
+    /**
+     * Result offset for pagination
+     */
+    offset?: number;
+    /**
+     * Minimum similarity score (0-1)
+     */
+    minScore?: number;
+    /**
+     * Filter by metadata
+     */
+    filter?: Record<string, unknown>;
+}
+/**
+ * Memory search result
+ */
+export interface MemorySearchResult {
+    /**
+     * Memory key
+     */
+    key: string;
+    /**
+     * Memory value
+     */
+    value: unknown;
+    /**
+     * Similarity score (0-1)
+     */
+    score: number;
+    /**
+     * Associated metadata
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Memory backend statistics
+ */
+export interface MemoryBackendStats {
+    /**
+     * Total number of entries
+     */
+    entryCount: number;
+    /**
+     * Total storage size in bytes
+     */
+    sizeBytes: number;
+    /**
+     * Memory usage in bytes
+     */
+    memoryUsageBytes: number;
+    /**
+     * Backend-specific metrics
+     */
+    metrics?: Record<string, number>;
+}
+/**
+ * Core ClaudeFlowPlugin interface
+ * All plugins must implement this interface
+ */
+export interface ClaudeFlowPlugin {
+    /**
+     * Unique plugin name
+     */
+    readonly name: string;
+    /**
+     * Plugin version (semver)
+     */
+    readonly version: string;
+    /**
+     * Optional plugin dependencies
+     * List of plugin names that must be loaded before this plugin
+     */
+    readonly dependencies?: string[];
+    /**
+     * Plugin description
+     */
+    readonly description?: string;
+    /**
+     * Plugin author
+     */
+    readonly author?: string;
+    /**
+     * Initialize the plugin
+     * Called after all dependencies are loaded
+     */
+    initialize(context: PluginContext): Promise<void>;
+    /**
+     * Shutdown the plugin
+     * Called during system shutdown
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Register custom agent types (optional)
+     * @returns Array of agent type definitions
+     */
+    registerAgentTypes?(): AgentTypeDefinition[];
+    /**
+     * Register custom task types (optional)
+     * @returns Array of task type definitions
+     */
+    registerTaskTypes?(): TaskTypeDefinition[];
+    /**
+     * Register MCP tools (optional)
+     * @returns Array of MCP tool definitions
+     */
+    registerMCPTools?(): MCPToolDefinition[];
+    /**
+     * Register CLI commands (optional)
+     * @returns Array of CLI command definitions
+     */
+    registerCLICommands?(): CLICommandDefinition[];
+    /**
+     * Register memory backends (optional)
+     * @returns Array of memory backend factories
+     */
+    registerMemoryBackends?(): MemoryBackendFactory[];
+    /**
+     * Optional health check
+     * @returns true if plugin is healthy, false otherwise
+     */
+    healthCheck?(): Promise<boolean>;
+    /**
+     * Optional plugin metadata
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Plugin lifecycle state
+ */
+export type PluginLifecycleState = 'uninitialized' | 'initializing' | 'initialized' | 'shutting-down' | 'shutdown' | 'error';
+/**
+ * Plugin info for registry tracking
+ */
+export interface PluginInfo {
+    /**
+     * Plugin instance
+     */
+    plugin: ClaudeFlowPlugin;
+    /**
+     * Current lifecycle state
+     */
+    state: PluginLifecycleState;
+    /**
+     * Initialization timestamp
+     */
+    initializedAt?: Date;
+    /**
+     * Shutdown timestamp
+     */
+    shutdownAt?: Date;
+    /**
+     * Plugin context
+     */
+    context?: PluginContext;
+    /**
+     * Error if state is 'error'
+     */
+    error?: Error;
+    /**
+     * Plugin metrics
+     */
+    metrics?: {
+        agentTypesRegistered: number;
+        taskTypesRegistered: number;
+        mcpToolsRegistered: number;
+        cliCommandsRegistered: number;
+        memoryBackendsRegistered: number;
+    };
+}
+/**
+ * Plugin error types
+ */
+export declare class PluginError extends Error {
+    readonly pluginName: string;
+    readonly code: PluginErrorCode;
+    readonly cause?: Error | undefined;
+    constructor(message: string, pluginName: string, code: PluginErrorCode, cause?: Error | undefined);
+}
+export type PluginErrorCode = 'INITIALIZATION_FAILED' | 'SHUTDOWN_FAILED' | 'DEPENDENCY_NOT_FOUND' | 'CIRCULAR_DEPENDENCY' | 'INVALID_PLUGIN' | 'DUPLICATE_PLUGIN' | 'HEALTH_CHECK_FAILED';
+//# sourceMappingURL=plugin-interface.d.ts.map

package/v3/@claude-flow/shared/dist/plugin-interface.js

@@ -0,0 +1,23 @@
+/**
+ * V3 Plugin Interface
+ * Domain-Driven Design - Plugin-Based Architecture (ADR-004)
+ *
+ * Microkernel pattern for extensible Claude-Flow V3
+ * Enables modular extension points for agents, tasks, MCP tools, CLI commands, and memory backends
+ */
+/**
+ * Plugin error types
+ */
+export class PluginError extends Error {
+    pluginName;
+    code;
+    cause;
+    constructor(message, pluginName, code, cause) {
+        super(message);
+        this.pluginName = pluginName;
+        this.code = code;
+        this.cause = cause;
+        this.name = 'PluginError';
+    }
+}
+//# sourceMappingURL=plugin-interface.js.map

package/v3/@claude-flow/shared/dist/plugin-loader.d.ts

@@ -0,0 +1,139 @@
+/**
+ * V3 Plugin Loader
+ * Domain-Driven Design - Plugin-Based Architecture (ADR-004)
+ *
+ * Handles plugin loading, dependency resolution, and lifecycle management
+ */
+import type { ClaudeFlowPlugin, PluginContext } from './plugin-interface.js';
+import type { PluginRegistry } from './plugin-registry.js';
+/**
+ * Plugin loader configuration
+ */
+export interface PluginLoaderConfig {
+    /**
+     * Maximum time to wait for plugin initialization (ms)
+     */
+    initializationTimeout?: number;
+    /**
+     * Maximum time to wait for plugin shutdown (ms)
+     */
+    shutdownTimeout?: number;
+    /**
+     * Enable parallel plugin initialization
+     */
+    parallelInitialization?: boolean;
+    /**
+     * Enable strict dependency checking
+     */
+    strictDependencies?: boolean;
+    /**
+     * Enable health checks
+     */
+    enableHealthChecks?: boolean;
+    /**
+     * Health check interval (ms)
+     */
+    healthCheckInterval?: number;
+}
+/**
+ * Plugin loader for managing plugin lifecycle
+ */
+export declare class PluginLoader {
+    private config;
+    private registry;
+    private initializationOrder;
+    private healthCheckIntervalId?;
+    constructor(registry: PluginRegistry, config?: PluginLoaderConfig);
+    /**
+     * Load a single plugin
+     */
+    loadPlugin(plugin: ClaudeFlowPlugin, context: PluginContext): Promise<void>;
+    /**
+     * Load multiple plugins with dependency resolution
+     */
+    loadPlugins(plugins: ClaudeFlowPlugin[], context: PluginContext): Promise<LoadPluginsResult>;
+    /**
+     * Unload a single plugin
+     */
+    unloadPlugin(pluginName: string): Promise<void>;
+    /**
+     * Unload all plugins in reverse initialization order
+     */
+    unloadAll(): Promise<void>;
+    /**
+     * Reload a plugin
+     */
+    reloadPlugin(pluginName: string, newPlugin: ClaudeFlowPlugin, context: PluginContext): Promise<void>;
+    /**
+     * Get plugin initialization order
+     */
+    getInitializationOrder(): string[];
+    /**
+     * Validate plugin interface
+     */
+    private validatePlugin;
+    /**
+     * Validate plugin dependencies
+     */
+    private validateDependencies;
+    /**
+     * Initialize a single plugin
+     */
+    private initializePlugin;
+    /**
+     * Shutdown a single plugin
+     */
+    private shutdownPlugin;
+    /**
+     * Initialize plugins sequentially
+     */
+    private initializePluginsSequential;
+    /**
+     * Initialize plugins in parallel (by dependency level)
+     */
+    private initializePluginsParallel;
+    /**
+     * Build dependency graph
+     */
+    private buildDependencyGraph;
+    /**
+     * Calculate depth of each node (for topological sorting)
+     */
+    private calculateDepths;
+    /**
+     * Topological sort (dependency order)
+     */
+    private topologicalSort;
+    /**
+     * Group plugins by dependency depth (for parallel initialization)
+     */
+    private groupByDepth;
+    /**
+     * Detect circular dependencies
+     */
+    private detectCircularDependencies;
+    /**
+     * Find plugins that depend on a given plugin
+     */
+    private findDependents;
+    /**
+     * Start periodic health checks
+     */
+    private startHealthChecks;
+    /**
+     * Utility: Run promise with timeout
+     */
+    private withTimeout;
+}
+/**
+ * Load plugins result
+ */
+export interface LoadPluginsResult {
+    successful: string[];
+    failed: Array<{
+        name: string;
+        error: Error;
+    }>;
+    totalDuration: number;
+}
+//# sourceMappingURL=plugin-loader.d.ts.map