@codemcp/workflows 4.7.0 → 4.8.0

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

@@ -8,6 +8,8 @@
 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';
 
 /**
@@ -78,6 +80,14 @@ export class ProceedToPhaseHandler extends ConversationRequiredToolHandler<
       context
     );
 
+    // Validate beads task completion if in beads mode
+    await this.validateBeadsTaskCompletion(
+      conversationId,
+      currentPhase,
+      target_phase,
+      conversationContext.projectPath
+    );
+
     // Ensure state machine is loaded for this project
     this.ensureStateMachineForProject(context, conversationContext.projectPath);
 
@@ -279,4 +289,134 @@ 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, please complete these tasks using:
+  bd close <task-id>
+
+Or check remaining work with:
+  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,
+        }
+      );
+    }
+  }
 }

package/src/tool-handlers/start-development.ts

@@ -17,7 +17,11 @@ import { GitCommitConfig } from '@codemcp/workflows-core';
 import { GitManager } from '@codemcp/workflows-core';
 import type { YamlStateMachine } from '@codemcp/workflows-core';
 import { ProjectDocsManager, ProjectDocsInfo } from '@codemcp/workflows-core';
-import { TaskBackendManager, BeadsIntegration } from '@codemcp/workflows-core';
+import {
+  TaskBackendManager,
+  BeadsIntegration,
+  BeadsStateManager,
+} from '@codemcp/workflows-core';
 import { ServerContext } from '../types.js';
 
 /**
@@ -215,7 +219,8 @@ export class StartDevelopmentHandler extends BaseToolHandler<
         projectPath,
         stateMachine,
         selectedWorkflow,
-        conversationContext.planFilePath
+        conversationContext.planFilePath,
+        conversationContext.conversationId
       );
     }
 
@@ -647,7 +652,8 @@ ${templateOptionsText}
     projectPath: string,
     stateMachine: YamlStateMachine,
     workflowName: string,
-    planFilePath: string
+    planFilePath: string,
+    conversationId: string
   ): Promise<void> {
     try {
       const beadsIntegration = new BeadsIntegration(projectPath);
@@ -673,11 +679,16 @@ ${templateOptionsText}
       // Update plan file with phase task IDs
       await this.updatePlanFileWithPhaseTaskIds(planFilePath, phaseTasks);
 
+      // Create beads state for this conversation
+      const beadsStateManager = new BeadsStateManager(projectPath);
+      await beadsStateManager.createState(conversationId, epicId, phaseTasks);
+
       this.logger.info('Beads integration setup complete', {
         projectPath,
         epicId,
         phaseCount: phaseTasks.length,
         planFilePath,
+        conversationId,
       });
     } catch (error) {
       this.logger.error(

package/src/tool-handlers/whats-next.ts

@@ -7,7 +7,7 @@
 
 import { ConversationRequiredToolHandler } from './base-tool-handler.js';
 import type { ConversationContext } from '@codemcp/workflows-core';
-import { TaskBackendManager, BeadsIntegration } from '@codemcp/workflows-core';
+// TaskBackendManager and BeadsIntegration functionality now handled by injected components
 import { ServerContext } from '../types.js';
 
 /**
@@ -181,14 +181,7 @@ export class WhatsNextHandler extends ConversationRequiredToolHandler<
       finalInstructions += `\n\n**Git Commit Required**: Create a commit for this step using:\n\`\`\`bash\ngit add . && git commit -m "${commitMessage}"\n\`\`\``;
     }
 
-    // Add beads instructions if beads backend is active
-    const beadsInstructions = await this.generateBeadsInstructions(
-      conversationContext,
-      transitionResult.newPhase
-    );
-    if (beadsInstructions) {
-      finalInstructions += '\n\n' + beadsInstructions;
-    }
+    // Note: Beads-specific instructions are now handled by BeadsInstructionGenerator via strategy pattern
 
     // Prepare response
     const response: WhatsNextResult = {
@@ -259,113 +252,7 @@ export class WhatsNextHandler extends ConversationRequiredToolHandler<
     return true;
   }
 
-  /**
-   * Generate beads-specific instructions if beads backend is active
-   */
-  private async generateBeadsInstructions(
-    conversationContext: ConversationContext,
-    currentPhase: string
-  ): Promise<string | null> {
-    // Check if beads backend is configured
-    const taskBackendConfig = TaskBackendManager.detectTaskBackend();
-    if (
-      taskBackendConfig.backend !== 'beads' ||
-      !taskBackendConfig.isAvailable
-    ) {
-      return null;
-    }
-
-    try {
-      // Read plan file to extract current phase task ID
-      const phaseTaskId = await this.extractPhaseTaskId(
-        conversationContext.planFilePath,
-        currentPhase
-      );
-      if (!phaseTaskId) {
-        this.logger.warn(
-          'Could not find beads phase task ID for current phase',
-          {
-            phase: currentPhase,
-            planFilePath: conversationContext.planFilePath,
-          }
-        );
-        return null;
-      }
-
-      // Generate beads instructions using BeadsIntegration utility
-      const beadsIntegration = new BeadsIntegration(
-        conversationContext.projectPath
-      );
-      const phaseName = this.capitalizePhase(currentPhase);
-      return beadsIntegration.generateBeadsInstructions(phaseTaskId, phaseName);
-    } catch (error) {
-      this.logger.warn('Failed to generate beads instructions', {
-        phase: currentPhase,
-        projectPath: conversationContext.projectPath,
-        error: error instanceof Error ? error.message : String(error),
-      });
-      return null;
-    }
-  }
-
-  /**
-   * Extract beads phase task ID from plan file for the given phase
-   */
-  private async extractPhaseTaskId(
-    planFilePath: string,
-    phase: string
-  ): Promise<string | null> {
-    try {
-      const { readFile } = await import('node:fs/promises');
-      const content = await readFile(planFilePath, 'utf-8');
-
-      const phaseName = this.capitalizePhase(phase);
-      const phaseHeader = `## ${phaseName}`;
-
-      // Look for the phase header followed by beads-phase-id comment
-      const phaseSection = content.split('\n');
-      let foundPhaseHeader = false;
+  // Beads-specific instruction logic has been moved to BeadsInstructionGenerator strategy
 
-      for (const line of phaseSection) {
-        if (line.trim() === phaseHeader) {
-          foundPhaseHeader = true;
-          continue;
-        }
-
-        if (foundPhaseHeader && line.includes('beads-phase-id:')) {
-          const match = line.match(/beads-phase-id:\s*([\w\d-]+)/);
-          if (match) {
-            return match[1] || null;
-          }
-        }
-
-        // Stop looking if we hit the next phase header
-        if (foundPhaseHeader && line.startsWith('##') && line !== phaseHeader) {
-          break;
-        }
-      }
-
-      return null;
-    } catch (error) {
-      this.logger.warn(
-        'Failed to read plan file for phase task ID extraction',
-        {
-          planFilePath,
-          phase,
-          error: error instanceof Error ? error.message : String(error),
-        }
-      );
-      return null;
-    }
-  }
-
-  /**
-   * Capitalize phase name for display
-   */
-  private capitalizePhase(phase: string): string {
-    return phase
-      .split('_')
-      .map(word => word.charAt(0).toUpperCase() + word.slice(1))
-      .join(' ');
-  }
+  // Utility methods moved to strategy implementations where needed
 }

package/src/types.ts

@@ -4,10 +4,11 @@
 
 import { ConversationManager } from '@codemcp/workflows-core';
 import { TransitionEngine } from '@codemcp/workflows-core';
-import { PlanManager } from '@codemcp/workflows-core';
-import { InstructionGenerator } from '@codemcp/workflows-core';
+import { IPlanManager } from '@codemcp/workflows-core';
+import { IInstructionGenerator } from '@codemcp/workflows-core';
 import { WorkflowManager } from '@codemcp/workflows-core';
 import { InteractionLogger } from '@codemcp/workflows-core';
+import type { TaskBackendConfig } from '@codemcp/workflows-core';
 
 /**
  * Server context shared across all handlers
@@ -16,8 +17,8 @@ import { InteractionLogger } from '@codemcp/workflows-core';
 export interface ServerContext {
   conversationManager: ConversationManager;
   transitionEngine: TransitionEngine;
-  planManager: PlanManager;
-  instructionGenerator: InstructionGenerator;
+  planManager: IPlanManager;
+  instructionGenerator: IInstructionGenerator;
   workflowManager: WorkflowManager;
   interactionLogger?: InteractionLogger;
   projectPath: string;
@@ -127,4 +128,6 @@ export interface ServerConfig {
   databasePath?: string;
   /** Enable interaction logging */
   enableLogging?: boolean;
+  /** Task backend configuration override (for testing) */
+  taskBackend?: TaskBackendConfig;
 }

package/test/e2e/component-substitution.test.ts

@@ -0,0 +1,208 @@
+/**
+ * Component Substitution E2E Tests
+ *
+ * Tests that the strategy pattern component substitution works correctly
+ * in different task backend configurations.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { createTempProjectWithDefaultStateMachine } from '../utils/temp-files';
+import {
+  DirectServerInterface,
+  createSuiteIsolatedE2EScenario,
+  assertToolSuccess,
+  initializeDevelopment,
+} from '../utils/e2e-test-setup';
+
+vi.unmock('fs');
+vi.unmock('fs/promises');
+
+describe('Component Substitution', () => {
+  let client: DirectServerInterface;
+  let cleanup: () => Promise<void>;
+
+  describe('Markdown Backend Strategy', () => {
+    beforeEach(async () => {
+      // Ensure markdown backend is detected
+      process.env.TASK_BACKEND = 'markdown';
+
+      const scenario = await createSuiteIsolatedE2EScenario({
+        suiteName: 'component-substitution-markdown',
+        tempProjectFactory: createTempProjectWithDefaultStateMachine,
+      });
+      client = scenario.client;
+      cleanup = scenario.cleanup;
+
+      await initializeDevelopment(client);
+    });
+
+    afterEach(async () => {
+      delete process.env.TASK_BACKEND;
+      if (cleanup) {
+        await cleanup();
+      }
+    });
+
+    it('should use markdown-based components for plan management', async () => {
+      const result = await client.callTool('whats_next', {
+        user_input: 'test markdown component substitution',
+      });
+      const response = assertToolSuccess(result);
+
+      expect(response.phase).toBeTruthy();
+      expect(response.instructions).toBeTruthy();
+      expect(response.plan_file_path).toBeTruthy();
+
+      // Verify plan file operations work with markdown backend
+      expect(response.plan_file_path).toContain('.vibe');
+      expect(response.plan_file_path).toMatch(/\.md$/);
+    });
+
+    it('should generate markdown-compatible instructions', async () => {
+      const result = await client.callTool('whats_next', {
+        user_input: 'create feature with markdown backend',
+      });
+      const response = assertToolSuccess(result);
+
+      // Instructions should be generated using markdown-based strategy
+      expect(response.instructions).toContain('Plan File Guidance');
+      expect(response.instructions).toContain('Project Context');
+      expect(typeof response.instructions).toBe('string');
+    });
+
+    it('should handle phase transitions with markdown backend', async () => {
+      // Initialize conversation
+      await client.callTool('whats_next', { user_input: 'start project' });
+
+      const result = await client.callTool('proceed_to_phase', {
+        target_phase: 'design',
+        reason: 'requirements complete',
+        review_state: 'not-required',
+      });
+      const response = assertToolSuccess(result);
+
+      expect(response.phase).toBe('design');
+      expect(response.instructions).toBeTruthy();
+    });
+  });
+
+  describe('Backend Strategy Configuration', () => {
+    // Note: Actual beads fallback testing requires specific environment setup
+    // These tests document the expected behavior when backend fallback occurs
+
+    it.todo('should fallback to default components when beads unavailable');
+    it.todo('should generate compatible instructions with fallback strategy');
+
+    // For now, focus on testing the factory pattern mechanism itself
+    // rather than specific backend availability scenarios
+  });
+
+  describe('Component Factory Integration', () => {
+    beforeEach(async () => {
+      const scenario = await createSuiteIsolatedE2EScenario({
+        suiteName: 'component-substitution-factory',
+        tempProjectFactory: createTempProjectWithDefaultStateMachine,
+      });
+      client = scenario.client;
+      cleanup = scenario.cleanup;
+
+      await initializeDevelopment(client);
+    });
+
+    afterEach(async () => {
+      if (cleanup) {
+        await cleanup();
+      }
+    });
+
+    it('should maintain consistent behavior across component substitutions', async () => {
+      // Test multiple operations to ensure consistent component behavior
+      const first = await client.callTool('whats_next', {
+        user_input: 'first operation',
+      });
+      const firstResponse = assertToolSuccess(first);
+
+      const second = await client.callTool('proceed_to_phase', {
+        target_phase: 'design',
+        reason: 'ready to design',
+        review_state: 'not-required',
+      });
+      const secondResponse = assertToolSuccess(second);
+
+      const third = await client.callTool('whats_next', {
+        user_input: 'continue after transition',
+      });
+      const thirdResponse = assertToolSuccess(third);
+
+      // All responses should be consistent and functional
+      expect(firstResponse.conversation_id).toBe(
+        secondResponse.conversation_id
+      );
+      expect(secondResponse.conversation_id).toBe(
+        thirdResponse.conversation_id
+      );
+      expect(thirdResponse.phase).toBe('design');
+    });
+
+    it('should properly inject dependencies through factory pattern', async () => {
+      const result = await client.callTool('whats_next', {
+        user_input: 'test dependency injection',
+      });
+      const response = assertToolSuccess(result);
+
+      // Verify that components work together properly (dependency injection successful)
+      expect(response.instructions).toBeTruthy();
+      expect(response.plan_file_path).toBeTruthy();
+
+      // Components should be working together to produce complete responses
+      expect(response.phase).toBeTruthy();
+      expect(response.conversation_id).toBeTruthy();
+    });
+
+    it('should handle component errors gracefully', async () => {
+      // Test that factory-created components handle edge cases
+      const result = await client.callTool('whats_next', {
+        user_input: '', // Empty input to test robustness
+      });
+      const response = assertToolSuccess(result);
+
+      // Should still work with empty input
+      expect(response.phase).toBeTruthy();
+      expect(response.instructions).toBeTruthy();
+    });
+  });
+
+  describe('Backend Detection Integration', () => {
+    beforeEach(async () => {
+      const scenario = await createSuiteIsolatedE2EScenario({
+        suiteName: 'component-substitution-detection',
+        tempProjectFactory: createTempProjectWithDefaultStateMachine,
+      });
+      client = scenario.client;
+      cleanup = scenario.cleanup;
+
+      await initializeDevelopment(client);
+    });
+
+    afterEach(async () => {
+      if (cleanup) {
+        await cleanup();
+      }
+    });
+
+    it('should detect task backend and create appropriate components', async () => {
+      const result = await client.callTool('whats_next', {
+        user_input: 'test backend detection',
+      });
+      const response = assertToolSuccess(result);
+
+      // Verify the factory correctly detected and created appropriate components
+      expect(response.phase).toBeTruthy();
+      expect(response.instructions).toBeTruthy();
+
+      // The response should indicate which components are being used
+      // (in practice, this would be markdown components since beads isn't available in tests)
+      expect(response.plan_file_path).toMatch(/\.md$/);
+    });
+  });
+});