@codemcp/workflows 4.7.0 → 4.8.0

package/src/components/beads/beads-plan-manager.ts

@@ -0,0 +1,358 @@
+/**
+ * Beads Plan Manager
+ *
+ * Beads-specific implementation of IPlanManager.
+ * Manages plan files optimized for beads task management workflow.
+ */
+
+import {
+  type IPlanManager,
+  type PlanFileInfo,
+  type YamlStateMachine,
+  type TaskBackendConfig,
+  createLogger,
+} from '@codemcp/workflows-core';
+import { writeFile, readFile, access } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { mkdir } from 'node:fs/promises';
+
+const logger = createLogger('BeadsPlanManager');
+
+/**
+ * Beads-specific plan manager implementation
+ */
+export class BeadsPlanManager implements IPlanManager {
+  private stateMachine: YamlStateMachine | null = null;
+
+  /**
+   * Set the state machine definition for dynamic plan generation
+   */
+  setStateMachine(stateMachine: YamlStateMachine): void {
+    this.stateMachine = stateMachine;
+    logger.debug('State machine set for beads plan manager', {
+      name: stateMachine.name,
+      phases: Object.keys(stateMachine.states),
+    });
+  }
+
+  /**
+   * Set the task backend configuration
+   */
+  setTaskBackend(taskBackend: TaskBackendConfig): void {
+    // Task backend is implicit for beads plan manager (always beads)
+    logger.debug('Task backend set for beads plan manager', {
+      backend: taskBackend.backend,
+      available: taskBackend.isAvailable,
+    });
+  }
+
+  /**
+   * Get plan file information
+   */
+  async getPlanFileInfo(planFilePath: string): Promise<PlanFileInfo> {
+    try {
+      await access(planFilePath);
+      const content = await readFile(planFilePath, 'utf-8');
+      return {
+        path: planFilePath,
+        exists: true,
+        content,
+      };
+    } catch (_error) {
+      return {
+        path: planFilePath,
+        exists: false,
+      };
+    }
+  }
+
+  /**
+   * Create initial plan file if it doesn't exist
+   */
+  async ensurePlanFile(
+    planFilePath: string,
+    projectPath: string,
+    gitBranch: string
+  ): Promise<void> {
+    logger.debug('Ensuring beads plan file exists', {
+      planFilePath,
+      projectPath,
+      gitBranch,
+    });
+
+    const planInfo = await this.getPlanFileInfo(planFilePath);
+
+    if (!planInfo.exists) {
+      logger.info('Plan file not found, creating beads-optimized plan', {
+        planFilePath,
+      });
+      await this.createInitialBeadsPlanFile(
+        planFilePath,
+        projectPath,
+        gitBranch
+      );
+      logger.info('Beads plan file created successfully', { planFilePath });
+    } else {
+      logger.debug('Plan file already exists', { planFilePath });
+    }
+  }
+
+  /**
+   * Create initial plan file optimized for beads workflow
+   */
+  private async createInitialBeadsPlanFile(
+    planFilePath: string,
+    projectPath: string,
+    gitBranch: string
+  ): Promise<void> {
+    logger.debug('Creating beads-optimized plan file', { planFilePath });
+
+    try {
+      // Ensure directory exists
+      await mkdir(dirname(planFilePath), { recursive: true });
+      logger.debug('Plan file directory ensured', {
+        directory: dirname(planFilePath),
+      });
+
+      const projectName = projectPath.split('/').pop() || 'Unknown Project';
+      const branchInfo = gitBranch !== 'no-git' ? ` (${gitBranch} branch)` : '';
+
+      const initialContent = this.generateBeadsInitialPlanContent(
+        projectName,
+        branchInfo
+      );
+
+      await writeFile(planFilePath, initialContent, 'utf-8');
+      logger.info('Beads plan file written successfully', {
+        planFilePath,
+        contentLength: initialContent.length,
+        projectName,
+      });
+    } catch (error) {
+      logger.error('Failed to create beads plan file', error as Error, {
+        planFilePath,
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Generate initial plan file content optimized for beads workflow
+   */
+  private generateBeadsInitialPlanContent(
+    projectName: string,
+    branchInfo: string
+  ): string {
+    const timestamp = new Date().toISOString().split('T')[0];
+
+    if (!this.stateMachine) {
+      throw new Error(
+        'State machine not set. This should not happen as state machine is always loaded.'
+      );
+    }
+
+    const phases = Object.keys(this.stateMachine.states);
+    const initialPhase = this.stateMachine.initial_state;
+
+    const documentationUrl = this.generateWorkflowDocumentationUrl(
+      this.stateMachine.name
+    );
+
+    let content = `# Development Plan: ${projectName}${branchInfo}
+
+*Generated on ${timestamp} by Vibe Feature MCP*
+*Workflow: ${
+      documentationUrl
+        ? '[' + this.stateMachine.name + ']' + '(' + documentationUrl + ')'
+        : this.stateMachine.name
+    }*
+*Task Management: Beads Issue Tracker*
+
+## Goal
+*Define what you're building or fixing - this will be updated as requirements are gathered*
+
+## ${this.capitalizePhase(initialPhase)}
+<!-- beads-phase-id: TBD -->
+### Tasks
+
+**🔧 TASK MANAGEMENT VIA CLI TOOL bd**
+
+Tasks are managed via bd CLI tool. Use bd commands to create and manage tasks with proper hierarchy:
+
+- \`bd list --parent <phase-task-id> --status open\`
+- \`bd create "Task title" --parent <phase-task-id> -p 2\`
+- \`bd close <task-id>\`
+
+**Never use [ ] or [x] checkboxes - use bd commands only!**
+
+### Completed
+- [x] Created development plan file
+
+`;
+
+    // Generate sections for each phase with beads-specific guidance
+    for (const phase of phases) {
+      if (phase !== initialPhase) {
+        content += `## ${this.capitalizePhase(phase)}
+<!-- beads-phase-id: TBD -->
+### Tasks
+
+**🔧 TASK MANAGEMENT VIA CLI TOOL bd**
+
+Tasks are managed via bd CLI tool. Use bd commands to create and manage tasks with proper hierarchy:
+
+- \`bd list --parent <phase-task-id> --status open\`
+- \`bd create "Task title" --parent <phase-task-id> -p 2\`
+- \`bd close <task-id>\`
+
+**Never use [ ] or [x] checkboxes - use bd commands only!**
+
+### Completed
+*None yet*
+
+`;
+      }
+    }
+
+    content += `## Key Decisions
+*Important decisions will be documented here as they are made*
+
+## Notes
+*Additional context and observations*
+
+---
+*This plan is maintained by the LLM and uses beads CLI for task management. Tool responses provide guidance on which bd commands to use for task management.*
+`;
+
+    return content;
+  }
+
+  /**
+   * Update plan file with new content
+   */
+  async updatePlanFile(planFilePath: string, content: string): Promise<void> {
+    // Ensure directory exists
+    await mkdir(dirname(planFilePath), { recursive: true });
+
+    await writeFile(planFilePath, content, 'utf-8');
+  }
+
+  /**
+   * Get plan file content for LLM context
+   */
+  async getPlanFileContent(planFilePath: string): Promise<string> {
+    const planInfo = await this.getPlanFileInfo(planFilePath);
+
+    if (!planInfo.exists) {
+      return 'Plan file does not exist yet. It will be created when the LLM updates it.';
+    }
+
+    return planInfo.content || '';
+  }
+
+  /**
+   * Generate phase-specific plan file guidance optimized for beads
+   */
+  generatePlanFileGuidance(phase: string): string {
+    if (!this.stateMachine) {
+      throw new Error(
+        'State machine not set. This should not happen as state machine is always loaded.'
+      );
+    }
+
+    const phaseDefinition = this.stateMachine.states[phase];
+    if (!phaseDefinition) {
+      logger.warn('Unknown phase for beads plan file guidance', { phase });
+      return `Update the ${this.capitalizePhase(phase)} section with current progress. Use bd CLI for all task management.`;
+    }
+
+    const capitalizedPhase = this.capitalizePhase(phase);
+
+    return `Update the ${capitalizedPhase} section with progress. Use bd CLI exclusively for task management - never use checkboxes. Document important decisions in the Key Decisions section.`;
+  }
+
+  /**
+   * Delete plan file
+   */
+  async deletePlanFile(planFilePath: string): Promise<boolean> {
+    logger.debug('Deleting beads plan file', { planFilePath });
+
+    try {
+      // Check if file exists first
+      await access(planFilePath);
+
+      // Import unlink dynamically to avoid issues
+      const { unlink } = await import('node:fs/promises');
+      await unlink(planFilePath);
+
+      logger.info('Beads plan file deleted successfully', { planFilePath });
+      return true;
+    } catch (error: unknown) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+        logger.debug('Beads plan file does not exist, nothing to delete', {
+          planFilePath,
+        });
+        return true; // Consider it successful if file doesn't exist
+      }
+
+      logger.error('Failed to delete beads plan file', error as Error, {
+        planFilePath,
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Ensure plan file is deleted (verify deletion)
+   */
+  async ensurePlanFileDeleted(planFilePath: string): Promise<boolean> {
+    logger.debug('Ensuring beads plan file is deleted', { planFilePath });
+
+    try {
+      await access(planFilePath);
+      // If we reach here, file still exists
+      logger.warn('Beads plan file still exists after deletion attempt', {
+        planFilePath,
+      });
+      return false;
+    } catch (error: unknown) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+        logger.debug('Beads plan file successfully deleted (does not exist)', {
+          planFilePath,
+        });
+        return true;
+      }
+
+      // Some other error occurred
+      logger.error('Error checking beads plan file deletion', error as Error, {
+        planFilePath,
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Capitalize phase name for display
+   */
+  private capitalizePhase(phase: string): string {
+    return phase
+      .split('_')
+      .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+      .join(' ');
+  }
+
+  /**
+   * Generate workflow documentation URL for predefined workflows
+   */
+  private generateWorkflowDocumentationUrl(
+    workflowName: string
+  ): string | undefined {
+    // Don't generate URL for custom workflows
+    if (workflowName === 'custom') {
+      return undefined;
+    }
+
+    // Generate URL for predefined workflows
+    return `https://mrsimpson.github.io/responsible-vibe-mcp/workflows/${workflowName}`;
+  }
+}

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)