@codemcp/workflows 4.10.0 → 4.10.2

package/test/unit/plugin-error-handling.test.ts

@@ -0,0 +1,240 @@
+/**
+ * Tests for Plugin Error Handling and Graceful Degradation
+ *
+ * Verifies that the plugin system handles errors gracefully:
+ * - Plugin failures don't crash the core application
+ * - Non-critical plugin errors allow graceful degradation
+ * - Validation errors (beforePhaseTransition) are always re-thrown
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { PluginRegistry } from '../../src/plugin-system/plugin-registry.js';
+import type { IPlugin } from '../../src/plugin-system/plugin-interfaces.js';
+
+const createMockContext = () => ({
+  conversationId: 'test',
+  planFilePath: '/test/plan.md',
+  projectPath: '/test',
+  currentPhase: 'explore',
+  workflow: 'epcc',
+  gitBranch: 'main',
+});
+
+describe('Plugin Error Handling and Graceful Degradation', () => {
+  describe('Non-critical hook error handling', () => {
+    it('should continue execution when afterStartDevelopment hook fails', async () => {
+      const registry = new PluginRegistry();
+
+      // Register first plugin that throws
+      const failingPlugin: IPlugin = {
+        getName: () => 'FailingPlugin',
+        getSequence: () => 1,
+        isEnabled: () => true,
+        getHooks: () => ({
+          afterStartDevelopment: vi
+            .fn()
+            .mockRejectedValue(new Error('Beads backend unavailable')),
+        }),
+      };
+
+      // Register second plugin that succeeds
+      const successHookSpy = vi.fn().mockResolvedValue(undefined);
+      const successPlugin: IPlugin = {
+        getName: () => 'SuccessPlugin',
+        getSequence: () => 2,
+        isEnabled: () => true,
+        getHooks: () => ({
+          afterStartDevelopment: successHookSpy,
+        }),
+      };
+
+      registry.registerPlugin(failingPlugin);
+      registry.registerPlugin(successPlugin);
+
+      // Execute hook - should NOT throw despite first plugin failure
+      const result = await registry.executeHook(
+        'afterStartDevelopment',
+        createMockContext(),
+        { workflow: 'epcc', commit_behaviour: 'end' },
+        {
+          conversationId: 'test',
+          planFilePath: '/test/plan.md',
+          phase: 'explore',
+          workflow: 'epcc',
+        }
+      );
+
+      // Should reach here without throwing
+      expect(result).toBeUndefined();
+      expect(successHookSpy).toHaveBeenCalled();
+    });
+
+    it('should continue execution when afterPlanFileCreated hook fails', async () => {
+      const registry = new PluginRegistry();
+
+      const failingPlugin: IPlugin = {
+        getName: () => 'FailingPlugin',
+        getSequence: () => 1,
+        isEnabled: () => true,
+        getHooks: () => ({
+          afterPlanFileCreated: vi
+            .fn()
+            .mockRejectedValue(new Error('Plan file update failed')),
+        }),
+      };
+
+      registry.registerPlugin(failingPlugin);
+
+      // Should not throw despite plugin error
+      const result = await registry.executeHook(
+        'afterPlanFileCreated',
+        createMockContext(),
+        '/test/plan.md',
+        'initial content'
+      );
+
+      expect(result).toBeUndefined();
+    });
+  });
+
+  describe('Validation hook error handling', () => {
+    it('should re-throw validation errors from beforePhaseTransition', async () => {
+      const registry = new PluginRegistry();
+
+      const validationPlugin: IPlugin = {
+        getName: () => 'ValidationPlugin',
+        getSequence: () => 1,
+        isEnabled: () => true,
+        getHooks: () => ({
+          beforePhaseTransition: vi
+            .fn()
+            .mockRejectedValue(
+              new Error('Cannot proceed to code - incomplete tasks')
+            ),
+        }),
+      };
+
+      registry.registerPlugin(validationPlugin);
+
+      // Should re-throw validation errors
+      await expect(
+        registry.executeHook(
+          'beforePhaseTransition',
+          createMockContext(),
+          'plan',
+          'code'
+        )
+      ).rejects.toThrow('Cannot proceed to code - incomplete tasks');
+    });
+
+    it('should re-throw any beforePhaseTransition hook errors', async () => {
+      const registry = new PluginRegistry();
+
+      const validationPlugin: IPlugin = {
+        getName: () => 'ValidationPlugin',
+        getSequence: () => 1,
+        isEnabled: () => true,
+        getHooks: () => ({
+          beforePhaseTransition: vi
+            .fn()
+            .mockRejectedValue(new Error('Validation failed for any reason')),
+        }),
+      };
+
+      registry.registerPlugin(validationPlugin);
+
+      // Should re-throw validation errors (not just specific messages)
+      await expect(
+        registry.executeHook(
+          'beforePhaseTransition',
+          createMockContext(),
+          'plan',
+          'code'
+        )
+      ).rejects.toThrow('Validation failed for any reason');
+    });
+  });
+
+  describe('Multiple plugin execution', () => {
+    it('should execute all plugins even if some fail on non-critical hooks', async () => {
+      const registry = new PluginRegistry();
+
+      const plugin1Spy = vi
+        .fn()
+        .mockRejectedValue(new Error('Plugin 1 failed'));
+      const plugin2Spy = vi.fn().mockResolvedValue(undefined);
+      const plugin3Spy = vi.fn().mockResolvedValue(undefined);
+
+      registry.registerPlugin({
+        getName: () => 'Plugin1',
+        getSequence: () => 1,
+        isEnabled: () => true,
+        getHooks: () => ({ afterStartDevelopment: plugin1Spy }),
+      });
+
+      registry.registerPlugin({
+        getName: () => 'Plugin2',
+        getSequence: () => 2,
+        isEnabled: () => true,
+        getHooks: () => ({ afterStartDevelopment: plugin2Spy }),
+      });
+
+      registry.registerPlugin({
+        getName: () => 'Plugin3',
+        getSequence: () => 3,
+        isEnabled: () => true,
+        getHooks: () => ({ afterStartDevelopment: plugin3Spy }),
+      });
+
+      // Execute should not throw
+      const _result = await registry.executeHook(
+        'afterStartDevelopment',
+        createMockContext(),
+        { workflow: 'epcc', commit_behaviour: 'end' },
+        {
+          conversationId: 'test',
+          planFilePath: '/test/plan.md',
+          phase: 'explore',
+          workflow: 'epcc',
+        }
+      );
+
+      // All plugins should be called
+      expect(plugin1Spy).toHaveBeenCalled();
+      expect(plugin2Spy).toHaveBeenCalled();
+      expect(plugin3Spy).toHaveBeenCalled();
+    });
+  });
+
+  describe('Disabled plugin handling', () => {
+    it('should not execute hooks from disabled plugins', async () => {
+      const registry = new PluginRegistry();
+
+      const hookSpy = vi.fn();
+
+      const disabledPlugin: IPlugin = {
+        getName: () => 'DisabledPlugin',
+        getSequence: () => 1,
+        isEnabled: () => false, // Disabled
+        getHooks: () => ({ afterStartDevelopment: hookSpy }),
+      };
+
+      registry.registerPlugin(disabledPlugin);
+
+      await registry.executeHook(
+        'afterStartDevelopment',
+        createMockContext(),
+        { workflow: 'epcc', commit_behaviour: 'end' },
+        {
+          conversationId: 'test',
+          planFilePath: '/test/plan.md',
+          phase: 'explore',
+          workflow: 'epcc',
+        }
+      );
+
+      // Disabled plugin's hook should not be called
+      expect(hookSpy).not.toHaveBeenCalled();
+    });
+  });
+});

package/test/unit/proceed-to-phase-plugin-integration.test.ts

@@ -0,0 +1,150 @@
+/**
+ * Test plugin hook integration in proceed-to-phase
+ * Focus on testing that plugin hooks are called correctly
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { ProceedToPhaseHandler } from '../../src/tool-handlers/proceed-to-phase.js';
+import { PluginRegistry } from '../../src/plugin-system/plugin-registry.js';
+import type { ServerContext } from '../../src/types.js';
+import type { PluginHookContext } from '../../src/plugin-system/plugin-interfaces.js';
+
+// Mock dependencies
+vi.mock('@codemcp/workflows-core', () => ({
+  createLogger: vi.fn(() => ({
+    debug: vi.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+  })),
+}));
+
+describe('ProceedToPhase Plugin Integration', () => {
+  let handler: ProceedToPhaseHandler;
+  let mockPluginRegistry: PluginRegistry;
+  let mockContext: ServerContext;
+
+  beforeEach(() => {
+    mockPluginRegistry = new PluginRegistry();
+
+    mockContext = {
+      conversationManager: {
+        getConversationContext: vi.fn().mockResolvedValue({
+          conversationId: 'test-conversation',
+          planFilePath: '/test/plan.md',
+          currentPhase: 'plan',
+          workflowName: 'epcc',
+          projectPath: '/test/project',
+          gitBranch: 'main',
+        }),
+        updateConversationState: vi.fn().mockResolvedValue(undefined),
+      },
+      transitionEngine: {
+        handleExplicitTransition: vi.fn().mockReturnValue({
+          newPhase: 'code',
+          transitionReason: 'Test transition',
+          isModeled: true,
+          instructions: 'Test transition instructions',
+        }),
+      },
+      planManager: {
+        getPlanFileInfo: vi.fn().mockResolvedValue({ exists: true }),
+      },
+      instructionGenerator: {
+        generateInstructions: vi.fn().mockResolvedValue({
+          instructions: 'Test instructions',
+        }),
+      },
+      workflowManager: {
+        loadWorkflowForProject: vi.fn().mockReturnValue({
+          name: 'epcc',
+          states: { plan: {}, code: {} },
+        }),
+      },
+      interactionLogger: {
+        logInteraction: vi.fn().mockResolvedValue(undefined),
+      },
+      projectPath: '/test/project',
+      pluginRegistry: mockPluginRegistry,
+    } as unknown as ServerContext;
+
+    handler = new ProceedToPhaseHandler();
+  });
+
+  it('should call beforePhaseTransition plugin hook during phase transition', async () => {
+    const hookSpy = vi.fn().mockResolvedValue(undefined);
+
+    // Register a mock plugin with beforePhaseTransition hook
+    const mockPlugin = {
+      getName: () => 'TestPlugin',
+      getSequence: () => 100,
+      isEnabled: () => true,
+      getHooks: () => ({
+        beforePhaseTransition: hookSpy,
+      }),
+    };
+
+    mockPluginRegistry.registerPlugin(mockPlugin);
+
+    // Execute the proceed_to_phase handler
+    await handler.handle(
+      {
+        target_phase: 'code',
+        reason: 'Testing plugin integration',
+        review_state: 'not-required',
+      },
+      mockContext
+    );
+
+    // Verify the hook was called with correct parameters
+    expect(hookSpy).toHaveBeenCalledOnce();
+
+    const [pluginContext, currentPhase, targetPhase] = hookSpy.mock.calls[0];
+
+    // Verify plugin context structure
+    expect(pluginContext).toMatchObject<Partial<PluginHookContext>>({
+      conversationId: 'test-conversation',
+      planFilePath: '/test/plan.md',
+      currentPhase: 'plan',
+      workflow: 'epcc',
+      projectPath: '/test/project',
+      gitBranch: 'main',
+      targetPhase: 'code',
+    });
+
+    // Verify phase parameters
+    expect(currentPhase).toBe('plan');
+    expect(targetPhase).toBe('code');
+  });
+
+  it('should handle plugin hook errors by returning error result', async () => {
+    const hookError = new Error('Plugin validation failed');
+    const hookSpy = vi.fn().mockRejectedValue(hookError);
+
+    // Register a mock plugin that throws an error
+    const mockPlugin = {
+      getName: () => 'TestPlugin',
+      getSequence: () => 100,
+      isEnabled: () => true,
+      getHooks: () => ({
+        beforePhaseTransition: hookSpy,
+      }),
+    };
+
+    mockPluginRegistry.registerPlugin(mockPlugin);
+
+    // Execute the handler and expect it to return error result
+    const result = await handler.handle(
+      {
+        target_phase: 'code',
+        reason: 'Testing plugin error handling',
+        review_state: 'not-required',
+      },
+      mockContext
+    );
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('Plugin validation failed');
+    expect(hookSpy).toHaveBeenCalledOnce();
+  });
+});

package/test/unit/server-config-plugin-registry.test.ts

@@ -0,0 +1,81 @@
+/**
+ * Test plugin registration in server-config
+ */
+
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
+import { initializeServerComponents } from '../../src/server-config.js';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+describe('Server Config Plugin Registration', () => {
+  let tempDir: string;
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    tempDir = await mkdtemp(join(tmpdir(), 'server-config-test-'));
+  });
+
+  afterEach(async () => {
+    vi.clearAllMocks();
+    try {
+      await rm(tempDir, { recursive: true, force: true });
+    } catch {
+      // Ignore cleanup errors
+    }
+  });
+
+  it('should register BeadsPlugin when TASK_BACKEND is beads', async () => {
+    vi.stubEnv('TASK_BACKEND', 'beads');
+
+    const components = await initializeServerComponents({
+      projectPath: tempDir,
+    });
+
+    expect(components.context.pluginRegistry).toBeDefined();
+
+    // Check that BeadsPlugin was registered
+    const pluginNames = components.context.pluginRegistry.getPluginNames();
+    expect(pluginNames).toContain('BeadsPlugin');
+
+    // Check that it's enabled
+    const enabledPlugins =
+      components.context.pluginRegistry.getEnabledPlugins();
+    expect(enabledPlugins).toHaveLength(1);
+    expect(enabledPlugins[0].getName()).toBe('BeadsPlugin');
+  });
+
+  it('should not register BeadsPlugin when TASK_BACKEND is not beads', async () => {
+    vi.stubEnv('TASK_BACKEND', 'none');
+
+    const components = await initializeServerComponents({
+      projectPath: tempDir,
+    });
+
+    expect(components.context.pluginRegistry).toBeDefined();
+
+    // Check that no plugins are registered
+    const pluginNames = components.context.pluginRegistry.getPluginNames();
+    expect(pluginNames).toHaveLength(0);
+
+    // Check that no plugins are enabled
+    const enabledPlugins =
+      components.context.pluginRegistry.getEnabledPlugins();
+    expect(enabledPlugins).toHaveLength(0);
+  });
+
+  it('should initialize empty plugin registry by default', async () => {
+    // Don't set TASK_BACKEND environment variable
+    vi.unstubAllEnvs();
+
+    const components = await initializeServerComponents({
+      projectPath: tempDir,
+    });
+
+    expect(components.context.pluginRegistry).toBeDefined();
+    expect(components.context.pluginRegistry.getPluginNames()).toHaveLength(0);
+    expect(components.context.pluginRegistry.getEnabledPlugins()).toHaveLength(
+      0
+    );
+  });
+});

package/test/unit/start-development-goal-extraction.test.ts

@@ -1,19 +1,25 @@
 /**
- * Unit tests for StartDevelopmentHandler Goal extraction functionality
+ * Unit tests for BeadsPlugin Goal extraction functionality
  *
  * Tests the extractGoalFromPlan method that extracts meaningful goal content
  * from development plan files for use in beads integration
  */
 
-import { describe, it, expect, beforeEach } from 'vitest';
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
 import { TestAccess } from '../utils/test-access.js';
-import { StartDevelopmentHandler } from '../../src/tool-handlers/start-development.js';
+import { BeadsPlugin } from '../../src/plugin-system/beads-plugin.js';
 
-describe('StartDevelopmentHandler - Goal Extraction', () => {
-  let handler: StartDevelopmentHandler;
+describe('BeadsPlugin - Goal Extraction', () => {
+  let plugin: BeadsPlugin;
 
   beforeEach(() => {
-    handler = new StartDevelopmentHandler();
+    // Mock environment variable for plugin enablement
+    vi.stubEnv('TASK_BACKEND', 'beads');
+    plugin = new BeadsPlugin({ projectPath: '/test/project' });
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
   });
 
   describe('extractGoalFromPlan', () => {
@@ -29,7 +35,7 @@ Build a user authentication system with JWT tokens and password reset functional
 `;
 
       const result = TestAccess.callMethod(
-        handler,
+        plugin,
         'extractGoalFromPlan',
         planContent
       );
@@ -51,7 +57,7 @@ Build a user authentication system with JWT tokens and password reset functional
 `;
 
       const result = TestAccess.callMethod(
-        handler,
+        plugin,
         'extractGoalFromPlan',
         planContent
       );
@@ -71,7 +77,7 @@ To be defined during exploration
 `;
 
       const result = TestAccess.callMethod(
-        handler,
+        plugin,
         'extractGoalFromPlan',
         planContent
       );
@@ -91,7 +97,7 @@ Fix bug
 `;
 
       const result = TestAccess.callMethod(
-        handler,
+        plugin,
         'extractGoalFromPlan',
         planContent
       );
@@ -117,7 +123,7 @@ The system should support different log levels and output formats.
 `;
 
       const result = TestAccess.callMethod(
-        handler,
+        plugin,
         'extractGoalFromPlan',
         planContent
       );
@@ -141,7 +147,7 @@ The system should support different log levels and output formats.`);
 `;
 
       const result = TestAccess.callMethod(
-        handler,
+        plugin,
         'extractGoalFromPlan',
         planContent
       );
@@ -151,15 +157,15 @@ The system should support different log levels and output formats.`);
 
     it('should return undefined for empty or null input', () => {
       expect(
-        TestAccess.callMethod(handler, 'extractGoalFromPlan', '')
+        TestAccess.callMethod(plugin, 'extractGoalFromPlan', '')
       ).toBeUndefined();
 
       expect(
-        TestAccess.callMethod(handler, 'extractGoalFromPlan', null)
+        TestAccess.callMethod(plugin, 'extractGoalFromPlan', null)
       ).toBeUndefined();
 
       expect(
-        TestAccess.callMethod(handler, 'extractGoalFromPlan', undefined)
+        TestAccess.callMethod(plugin, 'extractGoalFromPlan', undefined)
       ).toBeUndefined();
     });
 
@@ -175,7 +181,7 @@ Build a user authentication system with secure login and registration.
 `;
 
       const result = TestAccess.callMethod(
-        handler,
+        plugin,
         'extractGoalFromPlan',
         planContent
       );

package/test/utils/test-helpers.ts

@@ -11,10 +11,11 @@ import { vi, expect } from 'vitest';
 import {
   ResponsibleVibeMCPServer,
   createResponsibleVibeMCPServer,
-  StartDevelopmentResult,
 } from '../../src/server.js';
 import type { ServerContext } from '../../src/types';
+import type { StartDevelopmentResult } from '../../src/tool-handlers/start-development.js';
 import { TempProject } from './temp-files.js';
+import { PluginRegistry } from '../../src/plugin-system/plugin-registry.js';
 
 /**
  * Mock project documents content
@@ -114,6 +115,7 @@ export class MockContextFactory {
   ) {
     return {
       projectPath,
+      pluginRegistry: new PluginRegistry(),
       workflowManager: {
         validateWorkflowName: vi.fn().mockReturnValue(true),
         getWorkflowNames: vi