@codemcp/workflows 4.7.0 → 4.9.0

package/src/components/beads/beads-task-backend-client.ts

@@ -0,0 +1,232 @@
+/**
+ * Beads Task Backend Client
+ *
+ * Implementation of ITaskBackendClient for beads task management system.
+ * Handles CLI operations and task validation for beads backend.
+ */
+
+import {
+  type ITaskBackendClient,
+  type BackendTask,
+  type TaskValidationResult,
+} from '@codemcp/workflows-core';
+import { execSync } from 'node:child_process';
+import { createLogger } from '@codemcp/workflows-core';
+
+const logger = createLogger('BeadsTaskBackendClient');
+
+/**
+ * Beads-specific implementation of task backend client
+ */
+export class BeadsTaskBackendClient implements ITaskBackendClient {
+  private projectPath: string;
+
+  constructor(projectPath: string) {
+    this.projectPath = projectPath;
+  }
+
+  /**
+   * Execute a beads command safely
+   */
+  private async executeBeadsCommand(
+    args: string[]
+  ): Promise<{ success: boolean; stdout?: string; stderr?: string }> {
+    try {
+      const command = `bd ${args.join(' ')}`;
+      logger.debug('Executing beads command', {
+        command,
+        projectPath: this.projectPath,
+      });
+
+      const stdout = execSync(`bd ${args.join(' ')}`, {
+        cwd: this.projectPath,
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+
+      return { success: true, stdout };
+    } catch (error: unknown) {
+      const execError = error as {
+        stderr?: string;
+        stdout?: string;
+        status?: number;
+      };
+      logger.warn('Beads command failed', {
+        args,
+        error: error instanceof Error ? error.message : String(error),
+        stderr: execError.stderr,
+        stdout: execError.stdout,
+      });
+
+      return {
+        success: false,
+        stderr:
+          execError.stderr ||
+          (error instanceof Error ? error.message : String(error)),
+        stdout: execError.stdout,
+      };
+    }
+  }
+
+  /**
+   * Check if beads backend is available
+   */
+  async isAvailable(): Promise<boolean> {
+    try {
+      const result = await this.executeBeadsCommand(['--version']);
+      return result.success;
+    } catch (_error) {
+      return false;
+    }
+  }
+
+  /**
+   * Get all open tasks for a given parent task
+   */
+  async getOpenTasks(parentTaskId: string): Promise<BackendTask[]> {
+    try {
+      const result = await this.executeBeadsCommand([
+        'list',
+        '--parent',
+        parentTaskId,
+        '--status',
+        'open',
+      ]);
+
+      if (!result.success || !result.stdout) {
+        return [];
+      }
+
+      // Parse text output from beads CLI (since JSON format may not be available)
+      // This is a simplified parser - would need to be adjusted based on actual beads output format
+      const lines = result.stdout.trim().split('\n');
+      const tasks: BackendTask[] = [];
+
+      for (const line of lines) {
+        if (
+          line.trim() &&
+          !line.startsWith('○') &&
+          !line.startsWith('●') &&
+          !line.includes('Tip:')
+        ) {
+          // Extract task ID and title from beads output format
+          // This is based on observed beads CLI output format
+          const match = line.match(/^○?\s*([^\s]+)\s+.*?\s+-\s+(.+)$/);
+          if (match) {
+            tasks.push({
+              id: match[1] || '',
+              title: match[2] || '',
+              status: 'open',
+              priority: 2,
+              parent: parentTaskId,
+            });
+          }
+        }
+      }
+
+      return tasks;
+    } catch (_error) {
+      return [];
+    }
+  }
+
+  /**
+   * Validate that all tasks under a parent are completed
+   */
+  async validateTasksCompleted(
+    parentTaskId: string
+  ): Promise<TaskValidationResult> {
+    const openTasks = await this.getOpenTasks(parentTaskId);
+
+    return {
+      valid: openTasks.length === 0,
+      openTasks,
+      message:
+        openTasks.length > 0
+          ? `Found ${openTasks.length} incomplete task(s). All tasks must be completed before proceeding to the next phase.`
+          : 'All tasks completed.',
+    };
+  }
+
+  /**
+   * Create a new task under a parent
+   */
+  async createTask(
+    title: string,
+    parentTaskId: string,
+    priority = 2
+  ): Promise<string> {
+    const result = await this.executeBeadsCommand([
+      'create',
+      `"${title}"`,
+      '--parent',
+      parentTaskId,
+      '-p',
+      priority.toString(),
+    ]);
+
+    if (!result.success) {
+      throw new Error(
+        `Failed to create task: ${result.stderr || 'Unknown error'}`
+      );
+    }
+
+    // Extract task ID from beads output
+    // Based on beads CLI output format: "✓ Created issue: task-id"
+    const match =
+      result.stdout?.match(/✓ Created issue: ([\w\d.-]+)/) ||
+      result.stdout?.match(/Created issue: ([\w\d.-]+)/) ||
+      result.stdout?.match(/Created (bd-[\w\d.]+)/);
+
+    if (!match) {
+      throw new Error(
+        `Failed to extract task ID from beads output: ${result.stdout || 'No output'}`
+      );
+    }
+
+    return match[1] || '';
+  }
+
+  /**
+   * Update task status
+   */
+  async updateTaskStatus(
+    taskId: string,
+    status: 'open' | 'in_progress' | 'completed' | 'cancelled'
+  ): Promise<void> {
+    const beadsStatus = this.mapStatusToBeads(status);
+
+    const result = await this.executeBeadsCommand([
+      'update',
+      taskId,
+      '--status',
+      beadsStatus,
+    ]);
+
+    if (!result.success) {
+      throw new Error(
+        `Failed to update task status: ${result.stderr || 'Unknown error'}`
+      );
+    }
+  }
+
+  /**
+   * Map our status enum to beads CLI status values
+   */
+  private mapStatusToBeads(
+    status: 'open' | 'in_progress' | 'completed' | 'cancelled'
+  ): string {
+    switch (status) {
+      case 'open':
+        return 'open';
+      case 'in_progress':
+        return 'in_progress';
+      case 'completed':
+        return 'completed';
+      case 'cancelled':
+        return 'cancelled';
+      default:
+        return 'open';
+    }
+  }
+}

package/src/components/server-components-factory.ts

@@ -0,0 +1,86 @@
+/**
+ * Server Components Factory
+ *
+ * Factory for creating server components based on configuration.
+ * Implements strategy pattern to enable component substitution based on task backend.
+ */
+
+import {
+  TaskBackendManager,
+  PlanManager,
+  InstructionGenerator,
+  type TaskBackendConfig,
+} from '@codemcp/workflows-core';
+
+// Beads implementations
+import { BeadsPlanManager } from './beads/beads-plan-manager.js';
+import { BeadsInstructionGenerator } from './beads/beads-instruction-generator.js';
+import { BeadsTaskBackendClient } from './beads/beads-task-backend-client.js';
+
+export interface ComponentFactoryOptions {
+  taskBackend?: TaskBackendConfig;
+  projectPath?: string;
+}
+
+/**
+ * Factory class for creating server components with appropriate strategy implementations
+ */
+export class ServerComponentsFactory {
+  private taskBackend: TaskBackendConfig;
+  private projectPath?: string;
+
+  constructor(options: ComponentFactoryOptions = {}) {
+    this.taskBackend =
+      options.taskBackend || TaskBackendManager.detectTaskBackend();
+    this.projectPath = options.projectPath;
+  }
+
+  /**
+   * Create the appropriate plan manager implementation
+   */
+  createPlanManager(): PlanManager | BeadsPlanManager {
+    if (this.taskBackend.backend === 'beads' && this.taskBackend.isAvailable) {
+      return new BeadsPlanManager();
+    }
+
+    // Default markdown-based plan manager
+    return new PlanManager();
+  }
+
+  /**
+   * Create the appropriate instruction generator implementation
+   */
+  createInstructionGenerator():
+    | InstructionGenerator
+    | BeadsInstructionGenerator {
+    if (this.taskBackend.backend === 'beads' && this.taskBackend.isAvailable) {
+      return new BeadsInstructionGenerator();
+    }
+
+    // Default markdown-based instruction generator
+    return new InstructionGenerator(new PlanManager());
+  }
+
+  /**
+   * Create the appropriate task backend client implementation
+   */
+  createTaskBackendClient(): BeadsTaskBackendClient | null {
+    if (
+      this.taskBackend.backend === 'beads' &&
+      this.taskBackend.isAvailable &&
+      this.projectPath
+    ) {
+      return new BeadsTaskBackendClient(this.projectPath);
+    }
+
+    // No task backend client for markdown mode
+    return null;
+  }
+
+  /**
+   * Get the current task backend configuration
+   */
+  getTaskBackend(): TaskBackendConfig {
+    return this.taskBackend;
+  }
+}

package/src/server-config.ts

@@ -15,8 +15,6 @@ import { FileStorage } from '@codemcp/workflows-core';
 import type { IPersistence } from '@codemcp/workflows-core';
 import { ConversationManager } from '@codemcp/workflows-core';
 import { TransitionEngine } from '@codemcp/workflows-core';
-import { InstructionGenerator } from '@codemcp/workflows-core';
-import { PlanManager } from '@codemcp/workflows-core';
 import { InteractionLogger } from '@codemcp/workflows-core';
 import { WorkflowManager } from '@codemcp/workflows-core';
 import { GitManager } from '@codemcp/workflows-core';
@@ -36,6 +34,7 @@ import {
   generateWorkflowDescription,
 } from './server-helpers.js';
 import { notificationService } from './notification-service.js';
+import { ServerComponentsFactory } from './components/server-components-factory.js';
 
 const logger = createLogger('ServerConfig');
 
@@ -113,8 +112,14 @@ export async function initializeServerComponents(
   );
   const transitionEngine = new TransitionEngine(projectPath);
   transitionEngine.setConversationManager(conversationManager);
-  const planManager = new PlanManager();
-  const instructionGenerator = new InstructionGenerator(planManager);
+
+  // 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();
 
   // Always create interaction logger as it's critical for transition engine logic
   // (determining first call from initial state)

package/src/tool-handlers/get-tool-info.ts

@@ -9,6 +9,7 @@ import { z } from 'zod';
 import { BaseToolHandler } from './base-tool-handler.js';
 import { createLogger } from '@codemcp/workflows-core';
 import { ServerContext } from '../types.js';
+import { getFormattedVersion } from '../version-info.js';
 
 const logger = createLogger('GetToolInfoHandler');
 
@@ -207,7 +208,7 @@ export class GetToolInfoHandler extends BaseToolHandler<
     // Build the complete response
     const response: GetToolInfoResponse = {
       tool_name: 'Responsible Vibe MCP - Development Workflow Management',
-      version: '3.1.6-monorepo', // This should ideally come from package.json
+      version: getFormattedVersion(),
       purpose:
         'Structured development workflows with guided phase transitions and conversation state management',
       description:

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(