@codemcp/workflows 3.1.21

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

@@ -0,0 +1,235 @@
+/**
+ * WhatsNext Tool Handler
+ *
+ * Handles the whats_next tool which analyzes conversation context and
+ * determines the next development phase with specific instructions for the LLM.
+ */
+
+import { ConversationRequiredToolHandler } from './base-tool-handler.js';
+import type { ConversationContext } from '@codemcp/workflows-core';
+import { ServerContext } from '../types.js';
+
+/**
+ * Arguments for the whats_next tool
+ */
+export interface WhatsNextArgs {
+  context?: string;
+  user_input?: string;
+  conversation_summary?: string;
+  recent_messages?: Array<{
+    role: 'user' | 'assistant';
+    content: string;
+  }>;
+}
+
+/**
+ * Response from the whats_next tool
+ */
+export interface WhatsNextResult {
+  phase: string;
+  instructions: string;
+  plan_file_path: string;
+  is_modeled_transition: boolean;
+  conversation_id: string;
+}
+
+/**
+ * WhatsNext tool handler implementation
+ */
+export class WhatsNextHandler extends ConversationRequiredToolHandler<
+  WhatsNextArgs,
+  WhatsNextResult
+> {
+  protected async executeWithConversation(
+    args: WhatsNextArgs,
+    context: ServerContext,
+    conversationContext: ConversationContext
+  ): Promise<WhatsNextResult> {
+    const {
+      context: requestContext = '',
+      user_input = '',
+      conversation_summary = '',
+      recent_messages = [],
+    } = args;
+
+    const conversationId = conversationContext.conversationId;
+    const currentPhase = conversationContext.currentPhase;
+
+    this.logger.debug('Processing whats_next request', {
+      conversationId,
+      currentPhase,
+      hasContext: !!requestContext,
+      hasUserInput: !!user_input,
+    });
+
+    // Ensure state machine is loaded for this project
+    this.ensureStateMachineForProject(
+      context,
+      conversationContext.projectPath,
+      conversationContext.workflowName
+    );
+
+    // Ensure plan file exists
+    await context.planManager.ensurePlanFile(
+      conversationContext.planFilePath,
+      conversationContext.projectPath,
+      conversationContext.gitBranch
+    );
+
+    // Analyze phase transition
+    const transitionResult =
+      await context.transitionEngine.analyzePhaseTransition({
+        currentPhase,
+        projectPath: conversationContext.projectPath,
+        userInput: user_input,
+        context: requestContext,
+        conversationSummary: conversation_summary,
+        recentMessages: recent_messages,
+        conversationId: conversationContext.conversationId,
+      });
+
+    // Update conversation state if phase changed
+    if (transitionResult.newPhase !== currentPhase) {
+      const shouldUpdateState = await this.shouldUpdateConversationState(
+        currentPhase,
+        transitionResult.newPhase,
+        conversationContext,
+        context
+      );
+
+      if (shouldUpdateState) {
+        await context.conversationManager.updateConversationState(
+          conversationId,
+          { currentPhase: transitionResult.newPhase }
+        );
+      }
+
+      // If this was a first-call auto-transition, regenerate the plan file
+      if (
+        transitionResult.transitionReason.includes(
+          'Starting development - defining criteria'
+        )
+      ) {
+        this.logger.info(
+          'Regenerating plan file after first-call auto-transition',
+          {
+            from: currentPhase,
+            to: transitionResult.newPhase,
+            planFilePath: conversationContext.planFilePath,
+          }
+        );
+
+        await context.planManager.ensurePlanFile(
+          conversationContext.planFilePath,
+          conversationContext.projectPath,
+          conversationContext.gitBranch
+        );
+      }
+
+      this.logger.info('Phase transition completed', {
+        from: currentPhase,
+        to: transitionResult.newPhase,
+        reason: transitionResult.transitionReason,
+      });
+    }
+
+    // Check if plan file exists
+    const planInfo = await context.planManager.getPlanFileInfo(
+      conversationContext.planFilePath
+    );
+
+    // Generate enhanced instructions
+    const instructions =
+      await context.instructionGenerator.generateInstructions(
+        transitionResult.instructions,
+        {
+          phase: transitionResult.newPhase,
+          conversationContext: {
+            ...conversationContext,
+            currentPhase: transitionResult.newPhase,
+          },
+          transitionReason: transitionResult.transitionReason,
+          isModeled: transitionResult.isModeled,
+          planFileExists: planInfo.exists,
+        }
+      );
+
+    // Add commit instructions if configured
+    let finalInstructions = instructions.instructions;
+    if (
+      conversationContext.gitCommitConfig?.enabled &&
+      conversationContext.gitCommitConfig.commitOnStep
+    ) {
+      const commitMessage = requestContext || 'Step completion';
+      finalInstructions += `\n\n**Git Commit Required**: Create a commit for this step using:\n\`\`\`bash\ngit add . && git commit -m "${commitMessage}"\n\`\`\``;
+    }
+
+    // Prepare response
+    const response: WhatsNextResult = {
+      phase: transitionResult.newPhase,
+      instructions: finalInstructions,
+      plan_file_path: conversationContext.planFilePath,
+      is_modeled_transition: transitionResult.isModeled,
+      conversation_id: conversationContext.conversationId,
+    };
+
+    // Log interaction
+    await this.logInteraction(
+      context,
+      conversationId,
+      'whats_next',
+      args,
+      response,
+      transitionResult.newPhase
+    );
+
+    return response;
+  }
+
+  /**
+   * Determines whether conversation state should be updated for a phase transition
+   */
+  private async shouldUpdateConversationState(
+    currentPhase: string,
+    newPhase: string,
+    conversationContext: ConversationContext,
+    context: ServerContext
+  ): Promise<boolean> {
+    if (!conversationContext.requireReviewsBeforePhaseTransition) {
+      return true;
+    }
+
+    const stateMachine = context.workflowManager.loadWorkflowForProject(
+      conversationContext.projectPath,
+      conversationContext.workflowName
+    );
+
+    const currentState = stateMachine.states[currentPhase];
+    if (!currentState) {
+      return true;
+    }
+
+    const transition = currentState.transitions.find(t => t.to === newPhase);
+    if (!transition) {
+      return true;
+    }
+
+    const hasReviewPerspectives =
+      transition.review_perspectives &&
+      transition.review_perspectives.length > 0;
+
+    if (hasReviewPerspectives) {
+      this.logger.debug(
+        'Preventing state update - review required for transition',
+        {
+          from: currentPhase,
+          to: newPhase,
+          reviewPerspectives: transition.review_perspectives?.length || 0,
+        }
+      );
+      return false;
+    }
+
+    return true;
+  }
+}

package/src/types.ts

@@ -0,0 +1,130 @@
+/**
+ * Core types and interfaces for the refactored server architecture
+ */
+
+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 { WorkflowManager } from '@codemcp/workflows-core';
+import { InteractionLogger } from '@codemcp/workflows-core';
+
+/**
+ * Server context shared across all handlers
+ * Contains all the core dependencies needed by tool and resource handlers
+ */
+export interface ServerContext {
+  conversationManager: ConversationManager;
+  transitionEngine: TransitionEngine;
+  planManager: PlanManager;
+  instructionGenerator: InstructionGenerator;
+  workflowManager: WorkflowManager;
+  interactionLogger?: InteractionLogger;
+  projectPath: string;
+}
+
+/**
+ * Standard result format for all handler operations
+ * Separates business logic results from MCP protocol concerns
+ */
+export interface HandlerResult<T = unknown> {
+  success: boolean;
+  data?: T;
+  error?: string;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Resource content structure
+ */
+export interface ResourceContent {
+  uri: string;
+  text: string;
+  mimeType: string;
+}
+
+/**
+ * MCP Tool Response format (compatible with MCP SDK)
+ */
+export interface McpToolResponse {
+  [x: string]: unknown;
+  content: Array<{
+    type: 'text';
+    text: string;
+  }>;
+  isError?: boolean;
+}
+
+/**
+ * MCP Resource Response format (compatible with MCP SDK)
+ */
+export interface McpResourceResponse {
+  [x: string]: unknown;
+  contents: Array<{
+    uri: string;
+    text: string;
+    mimeType: string;
+  }>;
+}
+
+/**
+ * Tool handler interface
+ * All tool handlers must implement this interface
+ */
+export interface ToolHandler<TArgs = unknown, TResult = unknown> {
+  handle(args: TArgs, context: ServerContext): Promise<HandlerResult<TResult>>;
+}
+
+/**
+ * Resource handler interface
+ * All resource handlers must implement this interface
+ */
+export interface ResourceHandler {
+  handle(
+    uri: URL,
+    context: ServerContext
+  ): Promise<HandlerResult<ResourceContent>>;
+}
+
+/**
+ * Response renderer interface
+ * Handles translation between domain results and MCP protocol responses
+ */
+export interface ResponseRenderer {
+  renderToolResponse<T>(result: HandlerResult<T>): McpToolResponse;
+  renderResourceResponse(
+    result: HandlerResult<ResourceContent>
+  ): McpResourceResponse;
+  renderError(error: Error | string): McpToolResponse;
+}
+
+/**
+ * Tool registry interface
+ * Manages registration and lookup of tool handlers
+ */
+export interface ToolRegistry {
+  register<T extends ToolHandler>(name: string, handler: T): void;
+  get(name: string): ToolHandler | undefined;
+  list(): string[];
+}
+
+/**
+ * Resource registry interface
+ * Manages registration and lookup of resource handlers
+ */
+export interface ResourceRegistry {
+  register(pattern: string, handler: ResourceHandler): void;
+  resolve(uri: string): ResourceHandler | undefined;
+}
+
+/**
+ * Server configuration options
+ */
+export interface ServerConfig {
+  /** Project path to operate on (defaults to process.cwd()) */
+  projectPath?: string;
+  /** Database path override */
+  databasePath?: string;
+  /** Enable interaction logging */
+  enableLogging?: boolean;
+}

package/test/e2e/core-functionality.test.ts

@@ -0,0 +1,176 @@
+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');
+
+/**
+ * Core Functionality Tests
+ *
+ * Tests the essential server operations including:
+ * - Server initialization and basic tool operations
+ * - Resource access (plan and state resources)
+ * - Basic conversation management
+ * - Error handling and graceful failures
+ */
+describe('Core Functionality', () => {
+  let client: DirectServerInterface;
+  let cleanup: () => Promise<void>;
+
+  beforeEach(async () => {
+    const scenario = await createSuiteIsolatedE2EScenario({
+      suiteName: 'core-functionality',
+      tempProjectFactory: createTempProjectWithDefaultStateMachine,
+    });
+    client = scenario.client;
+    cleanup = scenario.cleanup;
+
+    // Initialize development with default workflow before each test
+    await initializeDevelopment(client);
+  });
+
+  afterEach(async () => {
+    if (cleanup) {
+      await cleanup();
+    }
+  });
+
+  describe('Server Initialization', () => {
+    it('should initialize server and provide tools', async () => {
+      const tools = await client.listTools();
+      expect(tools.tools).toBeTruthy();
+      expect(tools.tools).toHaveLength(2);
+      expect(tools.tools.map(t => t.name)).toContain('whats_next');
+      expect(tools.tools.map(t => t.name)).toContain('proceed_to_phase');
+    });
+
+    it('should provide resources', async () => {
+      const resources = await client.listResources();
+      expect(resources.resources).toBeTruthy();
+      expect(resources.resources).toHaveLength(3);
+      expect(resources.resources.map(r => r.uri)).toContain('plan://current');
+      expect(resources.resources.map(r => r.uri)).toContain('state://current');
+      expect(resources.resources.map(r => r.uri)).toContain('system-prompt://');
+    });
+  });
+
+  describe('Basic Tool Operations', () => {
+    it('should handle whats_next tool calls', async () => {
+      const result = await client.callTool('whats_next', {
+        user_input: 'implement authentication',
+      });
+      const response = assertToolSuccess(result);
+
+      expect(response.phase).toBeTruthy();
+      expect(response.instructions).toBeTruthy();
+      expect(response.conversation_id).toBeTruthy();
+      expect(response.plan_file_path).toBeTruthy();
+    });
+
+    it('should handle proceed_to_phase tool calls', async () => {
+      // First establish a 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('Resource Access', () => {
+    it('should provide plan resource as markdown', async () => {
+      // Initialize conversation to create plan file
+      await client.callTool('whats_next', { user_input: 'test project' });
+
+      const planResource = await client.readResource('plan://current');
+      expect(planResource.contents).toHaveLength(1);
+      expect(planResource.contents[0].mimeType).toBe('text/markdown');
+      expect(planResource.contents[0].text).toContain('# Development Plan');
+    });
+
+    it('should provide state resource as JSON', async () => {
+      // Initialize conversation
+      await client.callTool('whats_next', { user_input: 'test project' });
+
+      const stateResource = await client.readResource('state://current');
+      expect(stateResource.contents).toHaveLength(1);
+      expect(stateResource.contents[0].mimeType).toBe('application/json');
+
+      const stateData = JSON.parse(stateResource.contents[0].text);
+      expect(stateData.conversationId).toBeTruthy();
+      expect(stateData.currentPhase).toBeTruthy();
+    });
+  });
+
+  describe('Error Handling', () => {
+    it('should handle invalid tool parameters gracefully', async () => {
+      const result = await client.callTool('proceed_to_phase', {
+        target_phase: 'invalid_phase',
+        reason: 'test',
+        review_state: 'not-required',
+      });
+
+      // Should not throw, but may return error or fallback behavior
+      expect(result).toBeTruthy();
+    });
+
+    it('should handle missing parameters gracefully', async () => {
+      const result = await client.callTool('whats_next', {});
+      const response = assertToolSuccess(result);
+
+      // Should still work with empty parameters
+      expect(response.phase).toBeTruthy();
+      expect(response.instructions).toBeTruthy();
+    });
+
+    it('should handle database errors gracefully', async () => {
+      // This test would require mocking database failures
+      // For now, verify basic resilience
+      const result = await client.callTool('whats_next', {
+        user_input: 'test resilience',
+      });
+
+      expect(assertToolSuccess(result)).toBeTruthy();
+    });
+  });
+
+  describe('Basic Conversation Management', () => {
+    it('should create new conversations', async () => {
+      const result = await client.callTool('whats_next', {
+        user_input: 'new feature request',
+      });
+      const response = assertToolSuccess(result);
+
+      expect(response.conversation_id).toBeTruthy();
+      expect(response.conversation_id).toMatch(/^default-sm-/);
+    });
+
+    it('should maintain conversation state across calls', async () => {
+      const first = await client.callTool('whats_next', {
+        user_input: 'start project',
+      });
+      const firstResponse = assertToolSuccess(first);
+
+      const second = await client.callTool('whats_next', {
+        user_input: 'continue project',
+      });
+      const secondResponse = assertToolSuccess(second);
+
+      expect(firstResponse.conversation_id).toBe(
+        secondResponse.conversation_id
+      );
+    });
+  });
+});