@codemcp/workflows 4.7.0 → 4.9.0

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/src/version-info.ts

@@ -0,0 +1,213 @@
+/**
+ * Version Information Utility
+ *
+ * Provides version information for the MCP server, supporting both
+ * build-time injection and runtime determination for local development.
+ */
+
+import { execSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createLogger } from '@codemcp/workflows-core';
+
+const logger = createLogger('VersionInfo');
+
+/**
+ * Structure for version information
+ */
+export interface VersionInfo {
+  /** The semantic version (e.g., "4.8.0") */
+  version: string;
+  /** Git commit hash (short form, e.g., "bbb06ba") */
+  commit?: string;
+  /** Whether working directory has uncommitted changes */
+  isDirty?: boolean;
+  /** Full git describe output (e.g., "v4.8.0-1-gbbb06ba-dirty") */
+  gitDescribe?: string;
+  /** Source of version information */
+  source: 'package.json' | 'git' | 'build-time' | 'fallback';
+}
+
+/**
+ * Build-time version information (injected during build process)
+ * This will be replaced by the build system with actual values
+ */
+// @ts-ignore - This is replaced at build time
+const BUILD_TIME_VERSION: VersionInfo | null = null;
+
+/**
+ * Gets version information from package.json
+ */
+function getVersionFromPackageJson(): VersionInfo | null {
+  try {
+    // Get the directory of this module
+    const currentDir = dirname(fileURLToPath(import.meta.url));
+
+    // Try to find package.json - first in the mcp-server package, then root
+    const packageJsonPaths = [
+      join(currentDir, '..', 'package.json'),
+      join(currentDir, '..', '..', '..', 'package.json'),
+    ];
+
+    for (const packageJsonPath of packageJsonPaths) {
+      try {
+        const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+        if (packageJson.version) {
+          logger.debug('Found version in package.json', {
+            path: packageJsonPath,
+            version: packageJson.version,
+          });
+
+          return {
+            version: packageJson.version,
+            source: 'package.json',
+          };
+        }
+      } catch (error) {
+        logger.debug('Could not read package.json', {
+          path: packageJsonPath,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+    }
+
+    return null;
+  } catch (error) {
+    logger.debug('Error getting version from package.json', { error });
+    return null;
+  }
+}
+
+/**
+ * Gets version information from git
+ */
+function getVersionFromGit(): VersionInfo | null {
+  try {
+    // Get git describe output
+    const gitDescribe = execSync('git describe --tags --always --dirty', {
+      encoding: 'utf-8',
+      stdio: 'pipe',
+    }).trim();
+
+    logger.debug('Git describe output', { gitDescribe });
+
+    // Parse git describe output (e.g., "v4.8.0-1-gbbb06ba-dirty")
+    const isDirty = gitDescribe.endsWith('-dirty');
+    const cleanDescribe = isDirty ? gitDescribe.slice(0, -6) : gitDescribe;
+
+    // Try to extract version and commit
+    const parts = cleanDescribe.split('-');
+    let version: string;
+    let commit: string | undefined;
+
+    if (parts.length >= 3 && parts[0]?.startsWith('v')) {
+      // Format: v4.8.0-1-gbbb06ba
+      version = parts[0].slice(1); // Remove 'v' prefix
+      commit = parts[2]?.startsWith('g') ? parts[2].slice(1) : parts[2];
+    } else if (parts.length === 1 && parts[0]?.startsWith('v')) {
+      // Format: v4.8.0 (exact tag)
+      version = parts[0].slice(1);
+    } else if (parts.length === 1) {
+      // Format: commit hash only
+      version = 'unknown';
+      commit = parts[0];
+    } else {
+      // Fallback
+      version = 'unknown';
+    }
+
+    return {
+      version,
+      commit,
+      isDirty,
+      gitDescribe,
+      source: 'git',
+    };
+  } catch (error) {
+    logger.debug('Error getting version from git', {
+      error: error instanceof Error ? error.message : String(error),
+    });
+    return null;
+  }
+}
+
+/**
+ * Gets comprehensive version information, trying multiple sources
+ */
+export function getVersionInfo(): VersionInfo {
+  logger.debug('Determining version information');
+
+  // Try build-time version first (will be null in development)
+  if (BUILD_TIME_VERSION) {
+    logger.info('Using build-time version information', {
+      version: BUILD_TIME_VERSION.version,
+      source: BUILD_TIME_VERSION.source,
+    });
+    return BUILD_TIME_VERSION;
+  }
+
+  // Try git version info (best for development)
+  const gitVersion = getVersionFromGit();
+  if (gitVersion) {
+    // If we have git info, try to enhance with package.json version
+    const packageVersion = getVersionFromPackageJson();
+    if (packageVersion && gitVersion.version === 'unknown') {
+      logger.info('Using package.json version with git commit info', {
+        version: packageVersion.version,
+        commit: gitVersion.commit || 'unknown',
+        isDirty: String(gitVersion.isDirty || false),
+      });
+
+      return {
+        ...gitVersion,
+        version: packageVersion.version,
+        source: 'git' as const,
+      };
+    }
+
+    logger.info('Using git version information', {
+      version: gitVersion.version,
+      source: gitVersion.source,
+      commit: gitVersion.commit || 'none',
+      isDirty: String(gitVersion.isDirty || false),
+    });
+    return gitVersion;
+  }
+
+  // Fallback to package.json only
+  const packageVersion = getVersionFromPackageJson();
+  if (packageVersion) {
+    logger.info('Using package.json version information', {
+      version: packageVersion.version,
+      source: packageVersion.source,
+    });
+    return packageVersion;
+  }
+
+  // Final fallback
+  logger.warn('Could not determine version information, using fallback');
+  return {
+    version: 'unknown',
+    source: 'fallback',
+  };
+}
+
+/**
+ * Gets a formatted version string suitable for display
+ */
+export function getFormattedVersion(): string {
+  const versionInfo = getVersionInfo();
+
+  let formatted = versionInfo.version;
+
+  if (versionInfo.commit) {
+    formatted += `+${versionInfo.commit}`;
+  }
+
+  if (versionInfo.isDirty) {
+    formatted += '.dirty';
+  }
+
+  return formatted;
+}

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$/);
+    });
+  });
+});