@codemcp/workflows 4.10.0 → 4.10.2

package/src/plugin-system/plugin-interfaces.ts

@@ -0,0 +1,154 @@
+/**
+ * Plugin system interfaces for extending the responsible-vibe-mcp server
+ *
+ * Core Principle: Plugins receive only read-only context data and cannot
+ * directly manipulate core server components. They extend behavior through
+ * semantic lifecycle hooks only.
+ */
+
+import type { YamlState } from '@codemcp/workflows-core';
+
+/**
+ * Plugin interface - all plugins must implement this
+ */
+export interface IPlugin {
+  /** Unique plugin name */
+  getName(): string;
+
+  /** Execution sequence (lower numbers execute first) */
+  getSequence(): number;
+
+  /** Whether plugin is enabled (typically based on environment) */
+  isEnabled(): boolean;
+
+  /** Lifecycle hooks this plugin provides */
+  getHooks(): PluginHooks;
+}
+
+/**
+ * Lifecycle hooks that plugins can implement
+ * All hooks receive standardized PluginHookContext as first parameter
+ */
+export interface PluginHooks {
+  /** Called before development workflow starts */
+  beforeStartDevelopment?: (
+    context: PluginHookContext,
+    args: StartDevelopmentArgs
+  ) => Promise<void>;
+
+  /** Called after development workflow has started */
+  afterStartDevelopment?: (
+    context: PluginHookContext,
+    args: StartDevelopmentArgs,
+    result: StartDevelopmentResult
+  ) => Promise<void>;
+
+  /** Called after plan file is created - can modify content */
+  afterPlanFileCreated?: (
+    context: PluginHookContext,
+    planFilePath: string,
+    content: string
+  ) => Promise<string>;
+
+  /** Called before phase transition (can block by throwing) */
+  beforePhaseTransition?: (
+    context: PluginHookContext,
+    currentPhase: string,
+    targetPhase: string
+  ) => Promise<void>;
+
+  /** Called after instructions are generated - can modify them */
+  afterInstructionsGenerated?: (
+    context: PluginHookContext,
+    instructions: GeneratedInstructions
+  ) => Promise<GeneratedInstructions>;
+}
+
+/**
+ * Standardized context provided to all plugin hooks
+ * Contains ONLY read-only data - no server components
+ */
+export interface PluginHookContext {
+  /** Current conversation ID */
+  conversationId: string;
+
+  /** Path to the plan file */
+  planFilePath: string;
+
+  /** Current development phase */
+  currentPhase: string;
+
+  /** Active workflow name */
+  workflow: string;
+
+  /** Project directory path */
+  projectPath: string;
+
+  /** Git branch name */
+  gitBranch: string;
+
+  /** Target phase (only available in phase transitions) */
+  targetPhase?: string;
+
+  /** Workflow state machine definition (read-only) - available in afterStartDevelopment */
+  stateMachine?: {
+    readonly name: string;
+    readonly description: string;
+    readonly initial_state: string;
+    readonly states: Record<string, YamlState>;
+  };
+
+  // EXPLICITLY EXCLUDED: No access to core server components like:
+  // - conversationManager (could manipulate conversations)
+  // - transitionEngine (could force transitions)
+  // - planManager (could bypass hook system)
+  // - instructionGenerator (could generate instructions outside flow)
+}
+
+/**
+ * Plugin registry interface for managing and executing plugins
+ */
+export interface IPluginRegistry {
+  /** Register a plugin */
+  registerPlugin(plugin: IPlugin): void;
+
+  /** Get all enabled plugins sorted by sequence */
+  getEnabledPlugins(): IPlugin[];
+
+  /** Execute a specific hook on all plugins that implement it */
+  executeHook<T extends keyof PluginHooks>(
+    hookName: T,
+    ...args: Parameters<NonNullable<PluginHooks[T]>>
+  ): Promise<unknown>;
+
+  /** Check if any plugin has a specific hook */
+  hasHook(hookName: keyof PluginHooks): boolean;
+
+  /** Get names of all registered plugins */
+  getPluginNames(): string[];
+
+  /** Clear all plugins (mainly for testing) */
+  clear(): void;
+}
+
+// Supporting interfaces for hook parameters
+
+export interface StartDevelopmentArgs {
+  workflow: string;
+  commit_behaviour: string;
+  require_reviews?: boolean;
+  project_path?: string;
+}
+
+export interface StartDevelopmentResult {
+  conversationId: string;
+  planFilePath: string;
+  phase: string;
+  workflow: string;
+}
+
+export interface GeneratedInstructions {
+  instructions: string;
+  planFilePath: string;
+  phase: string;
+}

package/src/plugin-system/plugin-registry.ts

@@ -0,0 +1,190 @@
+/**
+ * Core PluginRegistry implementation for managing plugins and executing lifecycle hooks
+ */
+
+import type {
+  IPlugin,
+  IPluginRegistry,
+  PluginHooks,
+} from './plugin-interfaces.js';
+
+export class PluginRegistry implements IPluginRegistry {
+  private plugins: Map<string, IPlugin> = new Map();
+
+  /**
+   * Register a plugin if it's enabled
+   */
+  registerPlugin(plugin: IPlugin): void {
+    if (!plugin.isEnabled()) {
+      return;
+    }
+
+    const name = plugin.getName();
+    if (this.plugins.has(name)) {
+      throw new Error(`Plugin with name '${name}' is already registered`);
+    }
+
+    this.plugins.set(name, plugin);
+  }
+
+  /**
+   * Get all enabled plugins sorted by execution sequence
+   */
+  getEnabledPlugins(): IPlugin[] {
+    return Array.from(this.plugins.values())
+      .filter(plugin => plugin.isEnabled())
+      .sort((a, b) => a.getSequence() - b.getSequence());
+  }
+
+  /**
+   * Execute a specific hook on all plugins that implement it
+   * Plugins are executed in sequence order
+   *
+   * Error Handling Strategy:
+   * - Validation hooks (beforePhaseTransition): Always re-throw to block invalid transitions
+   * - Critical startup hooks: Re-throw to fail fast and show critical errors
+   * - Non-critical hooks: Log error and continue execution to enable graceful degradation
+   * - Multiple plugins: If one plugin fails on non-critical hook, continue with next plugin
+   */
+  async executeHook<T extends keyof PluginHooks>(
+    hookName: T,
+    ...args: Parameters<NonNullable<PluginHooks[T]>>
+  ): Promise<unknown> {
+    const enabledPlugins = this.getEnabledPlugins();
+    let result: unknown = undefined;
+
+    for (const plugin of enabledPlugins) {
+      const hooks = plugin.getHooks();
+      const hook = hooks[hookName];
+
+      if (hook) {
+        try {
+          // Type-safe hook execution using dispatch pattern
+          result = await this.executeTypedHook(hookName, hook, args, result);
+        } catch (error) {
+          const pluginName = plugin.getName();
+          const errorMessage =
+            error instanceof Error ? error.message : String(error);
+
+          // Validation hooks (beforePhaseTransition) should ALWAYS re-throw
+          // These are intentional blocking errors, not graceful degradation
+          if (hookName === 'beforePhaseTransition') {
+            console.error(
+              `Plugin '${pluginName}' validation failed for hook '${hookName}':`,
+              errorMessage
+            );
+            throw error;
+          }
+
+          // For non-critical hooks, log the error but continue execution
+          // This enables graceful degradation: the app continues even if a plugin hook fails
+          console.warn(
+            `Plugin '${pluginName}' hook '${hookName}' failed with non-critical error:`,
+            errorMessage
+          );
+          console.warn(
+            `Continuing with remaining plugins for hook '${hookName}' (graceful degradation enabled)`
+          );
+
+          // Continue to next plugin for non-critical errors
+          // This allows multiple plugins to execute even if one fails
+        }
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Type-safe hook execution dispatcher
+   * Handles the differences in hook signatures without type coercion
+   */
+  private async executeTypedHook<T extends keyof PluginHooks>(
+    hookName: T,
+    hook: NonNullable<PluginHooks[T]>,
+    args: Parameters<NonNullable<PluginHooks[T]>>,
+    previousResult: unknown
+  ): Promise<unknown> {
+    if (hookName === 'afterPlanFileCreated') {
+      // Content-chaining hook: replaces the content parameter with previous result
+      const typedHook = hook as NonNullable<
+        PluginHooks['afterPlanFileCreated']
+      >;
+      const [context, planFilePath, content] = args as Parameters<
+        typeof typedHook
+      >;
+      const contentToUse = ((previousResult as string | undefined) ??
+        content) as string;
+      return typedHook(context, planFilePath, contentToUse);
+    }
+
+    if (hookName === 'afterInstructionsGenerated') {
+      // Content-chaining hook: replaces the instructions parameter with previous result
+      const typedHook = hook as NonNullable<
+        PluginHooks['afterInstructionsGenerated']
+      >;
+      const [context, instructions] = args as Parameters<typeof typedHook>;
+      const instructionsToUse = (
+        previousResult !== undefined
+          ? (previousResult as Parameters<typeof typedHook>[1])
+          : instructions
+      ) as Parameters<typeof typedHook>[1];
+      return typedHook(context, instructionsToUse);
+    }
+
+    if (hookName === 'beforeStartDevelopment') {
+      const typedHook = hook as NonNullable<
+        PluginHooks['beforeStartDevelopment']
+      >;
+      const [context, startArgs] = args as Parameters<typeof typedHook>;
+      return typedHook(context, startArgs);
+    }
+
+    if (hookName === 'afterStartDevelopment') {
+      const typedHook = hook as NonNullable<
+        PluginHooks['afterStartDevelopment']
+      >;
+      const [context, startArgs, result] = args as Parameters<typeof typedHook>;
+      return typedHook(context, startArgs, result);
+    }
+
+    if (hookName === 'beforePhaseTransition') {
+      const typedHook = hook as NonNullable<
+        PluginHooks['beforePhaseTransition']
+      >;
+      const [context, currentPhase, targetPhase] = args as Parameters<
+        typeof typedHook
+      >;
+      return typedHook(context, currentPhase, targetPhase);
+    }
+
+    // This should never be reached due to type system, but ensures exhaustiveness
+    const exhaustiveCheck: never = hookName;
+    throw new Error(`Unknown hook: ${exhaustiveCheck}`);
+  }
+
+  /**
+   * Check if any enabled plugin implements a specific hook
+   */
+  hasHook(hookName: keyof PluginHooks): boolean {
+    const enabledPlugins = this.getEnabledPlugins();
+    return enabledPlugins.some(plugin => {
+      const hooks = plugin.getHooks();
+      return hooks[hookName] !== undefined;
+    });
+  }
+
+  /**
+   * Get names of all registered plugins (for debugging)
+   */
+  getPluginNames(): string[] {
+    return Array.from(this.plugins.keys());
+  }
+
+  /**
+   * Clear all plugins (mainly for testing)
+   */
+  clear(): void {
+    this.plugins.clear();
+  }
+}

package/src/server-config.ts

@@ -34,7 +34,11 @@ import {
   generateWorkflowDescription,
 } from './server-helpers.js';
 import { notificationService } from './notification-service.js';
-import { ServerComponentsFactory } from './components/server-components-factory.js';
+import { PlanManager, InstructionGenerator } from '@codemcp/workflows-core';
+import { PluginRegistry } from './plugin-system/plugin-registry.js';
+import { BeadsPlugin } from './plugin-system/beads-plugin.js';
+import { BeadsPlanManager } from './components/beads/beads-plan-manager.js';
+import { BeadsInstructionGenerator } from './components/beads/beads-instruction-generator.js';
 
 const logger = createLogger('ServerConfig');
 
@@ -113,18 +117,35 @@ export async function initializeServerComponents(
   const transitionEngine = new TransitionEngine(projectPath);
   transitionEngine.setConversationManager(conversationManager);
 
-  // Use factory pattern for strategy-based component creation
-  const componentsFactory = new ServerComponentsFactory({
-    projectPath,
-    taskBackend: config.taskBackend, // Pass through task backend config if provided
-  });
-  const planManager = componentsFactory.createPlanManager();
-  const instructionGenerator = componentsFactory.createInstructionGenerator();
+  // Use beads components if TASK_BACKEND=beads, otherwise use defaults
+  // This enables beads features like plan file markers and beads CLI instructions
+  const isBeadsBackend = process.env.TASK_BACKEND === 'beads';
+  const planManager = isBeadsBackend
+    ? new BeadsPlanManager()
+    : new PlanManager();
+  const instructionGenerator = isBeadsBackend
+    ? new BeadsInstructionGenerator()
+    : new InstructionGenerator(planManager as InstanceType<typeof PlanManager>);
 
   // Always create interaction logger as it's critical for transition engine logic
   // (determining first call from initial state)
   const interactionLogger = new InteractionLogger(database);
 
+  // Initialize plugin registry and register plugins
+  const pluginRegistry = new PluginRegistry();
+
+  // Register BeadsPlugin if beads backend is configured
+  if (process.env.TASK_BACKEND === 'beads') {
+    const beadsPlugin = new BeadsPlugin({ projectPath });
+    if (beadsPlugin.isEnabled()) {
+      pluginRegistry.registerPlugin(beadsPlugin);
+      logger.info('BeadsPlugin registered successfully', {
+        enabled: beadsPlugin.isEnabled(),
+        sequence: beadsPlugin.getSequence(),
+      });
+    }
+  }
+
   // Create server context
   const context: ServerContext = {
     conversationManager,
@@ -134,6 +155,7 @@ export async function initializeServerComponents(
     workflowManager,
     interactionLogger,
     projectPath,
+    pluginRegistry,
   };
 
   // Initialize database

package/src/tool-handlers/conduct-review.ts

@@ -143,8 +143,7 @@ export class ConductReviewHandler extends ConversationRequiredToolHandler<
     perspectives: Array<{ perspective: string; prompt: string }>,
     conversationContext: ConversationContext
   ): Promise<ConductReviewResult> {
-    // TODO: Implement automated review when sampling tools are available
-    // For now, fall back to guided instructions
+    // Falls back to guided instructions until automated review is implemented
     return this.generateReviewInstructions(
       perspectives,
       conversationContext.currentPhase,

package/src/tool-handlers/proceed-to-phase.ts

@@ -8,8 +8,6 @@
 import { ConversationRequiredToolHandler } from './base-tool-handler.js';
 import { validateRequiredArgs } from '../server-helpers.js';
 import type { ConversationContext } from '@codemcp/workflows-core';
-import { BeadsStateManager } from '@codemcp/workflows-core';
-import { ServerComponentsFactory } from '../components/server-components-factory.js';
 import { ServerContext } from '../types.js';
 
 /**
@@ -80,13 +78,26 @@ export class ProceedToPhaseHandler extends ConversationRequiredToolHandler<
       context
     );
 
-    // Validate beads task completion if in beads mode
-    await this.validateBeadsTaskCompletion(
+    // Execute plugin hooks before phase transition (replaces if-statement pattern)
+    const pluginContext = {
       conversationId,
+      planFilePath: conversationContext.planFilePath,
       currentPhase,
-      target_phase,
-      conversationContext.projectPath
-    );
+      workflow: conversationContext.workflowName,
+      projectPath: conversationContext.projectPath,
+      gitBranch: conversationContext.gitBranch,
+      targetPhase: target_phase,
+    };
+
+    // Execute plugin hooks safely - guard against missing plugin registry
+    if (context.pluginRegistry) {
+      await context.pluginRegistry.executeHook(
+        'beforePhaseTransition',
+        pluginContext,
+        currentPhase,
+        target_phase
+      );
+    }
 
     // Ensure state machine is loaded for this project
     this.ensureStateMachineForProject(context, conversationContext.projectPath);
@@ -136,6 +147,7 @@ export class ProceedToPhaseHandler extends ConversationRequiredToolHandler<
           transitionReason: transitionResult.transitionReason,
           isModeled: transitionResult.isModeled,
           planFileExists: planInfo.exists,
+          instructionSource: 'proceed_to_phase',
         }
       );
 
@@ -295,132 +307,4 @@ export class ProceedToPhaseHandler extends ConversationRequiredToolHandler<
       }
     }
   }
-
-  /**
-   * Validate that all beads tasks in the current phase are completed
-   * before proceeding to the next phase. Only applies when beads mode is active.
-   */
-  private async validateBeadsTaskCompletion(
-    conversationId: string,
-    currentPhase: string,
-    targetPhase: string,
-    projectPath: string
-  ): Promise<void> {
-    try {
-      // Use factory to create task backend client (strategy pattern)
-      const factory = new ServerComponentsFactory({ projectPath });
-      const taskBackendClient = factory.createTaskBackendClient();
-
-      if (!taskBackendClient) {
-        // Not in beads mode or beads not available, skip validation
-        this.logger.debug(
-          'Skipping beads task validation - no task backend client available',
-          {
-            conversationId,
-            currentPhase,
-            targetPhase,
-          }
-        );
-        return;
-      }
-
-      // Get beads state for this conversation
-      const beadsStateManager = new BeadsStateManager(projectPath);
-      const currentPhaseTaskId = await beadsStateManager.getPhaseTaskId(
-        conversationId,
-        currentPhase
-      );
-
-      if (!currentPhaseTaskId) {
-        // No beads state found for this conversation - fallback to graceful handling
-        this.logger.debug('No beads phase task ID found for current phase', {
-          conversationId,
-          currentPhase,
-          targetPhase,
-          projectPath,
-        });
-        return;
-      }
-
-      this.logger.debug(
-        'Checking for incomplete beads tasks using task backend client',
-        {
-          conversationId,
-          currentPhase,
-          currentPhaseTaskId,
-        }
-      );
-
-      // Use task backend client to validate task completion (strategy pattern)
-      const validationResult =
-        await taskBackendClient.validateTasksCompleted(currentPhaseTaskId);
-
-      if (!validationResult.valid) {
-        // Get the incomplete tasks from the validation result
-        const incompleteTasks = validationResult.openTasks;
-
-        // Create detailed error message with incomplete tasks
-        const taskDetails = incompleteTasks
-          .map(task => `  • ${task.id} - ${task.title || 'Untitled task'}`)
-          .join('\n');
-
-        const errorMessage = `Cannot proceed to ${targetPhase} - ${incompleteTasks.length} incomplete task(s) in current phase "${currentPhase}":
-
-${taskDetails}
-
-To proceed, check the in-progress-tasks using:
-
-  bd list --parent ${currentPhaseTaskId} --status open
-
-You can also defer tasks if they're no longer needed:
-  bd defer <task-id> --until tomorrow`;
-
-        this.logger.info(
-          'Blocking phase transition due to incomplete beads tasks',
-          {
-            conversationId,
-            currentPhase,
-            targetPhase,
-            currentPhaseTaskId,
-            incompleteTaskCount: incompleteTasks.length,
-            incompleteTaskIds: incompleteTasks.map(t => t.id),
-          }
-        );
-
-        throw new Error(errorMessage);
-      }
-
-      this.logger.info(
-        'All beads tasks completed in current phase, allowing transition',
-        {
-          conversationId,
-          currentPhase,
-          targetPhase,
-          currentPhaseTaskId,
-        }
-      );
-    } catch (error) {
-      // Re-throw validation errors (incomplete tasks)
-      if (
-        error instanceof Error &&
-        error.message.includes('Cannot proceed to')
-      ) {
-        throw error;
-      }
-
-      // Log other errors but allow transition (graceful degradation)
-      const errorMessage =
-        error instanceof Error ? error.message : String(error);
-      this.logger.warn(
-        'Beads task validation failed, allowing transition to proceed',
-        {
-          error: errorMessage,
-          conversationId,
-          currentPhase,
-          targetPhase,
-          projectPath,
-        }
-      );
-    }
-  }
 }