@sparkleideas/shared 3.0.0-alpha.7

package/src/plugin-interface.ts

@@ -0,0 +1,663 @@
+/**
+ * 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 class PluginError extends Error {
+  constructor(
+    message: string,
+    public readonly pluginName: string,
+    public readonly code: PluginErrorCode,
+    public readonly cause?: Error
+  ) {
+    super(message);
+    this.name = 'PluginError';
+  }
+}
+
+export type PluginErrorCode =
+  | 'INITIALIZATION_FAILED'
+  | 'SHUTDOWN_FAILED'
+  | 'DEPENDENCY_NOT_FOUND'
+  | 'CIRCULAR_DEPENDENCY'
+  | 'INVALID_PLUGIN'
+  | 'DUPLICATE_PLUGIN'
+  | 'HEALTH_CHECK_FAILED';