@codemcp/workflows 5.0.1 → 5.1.1

package/src/server-helpers.ts

@@ -1,245 +0,0 @@
-/**
- * Server Helper Functions
- *
- * Common utility functions used across the server implementation.
- * These are pure functions that don't depend on server state.
- */
-
-import { homedir } from 'node:os';
-import { createLogger } from '@codemcp/workflows-core';
-import { HandlerResult } from './types.js';
-
-const logger = createLogger('ServerHelpers');
-
-/**
- * Normalize and validate project path
- * Ensures we have a valid project path, defaulting to home directory if needed
- */
-export function normalizeProjectPath(projectPath?: string): string {
-  const path = projectPath || process.cwd();
-
-  if (path === '/' || path === '') {
-    const homePath = homedir();
-    logger.info('Invalid project path detected, using home directory', {
-      originalPath: path,
-      normalizedPath: homePath,
-    });
-    return homePath;
-  }
-
-  return path;
-}
-
-/**
- * Create a standardized success result
- */
-export function createSuccessResult<T>(
-  data: T,
-  metadata?: Record<string, unknown>
-): HandlerResult<T> {
-  return {
-    success: true,
-    data,
-    metadata,
-  };
-}
-
-/**
- * Create a standardized error result
- */
-export function createErrorResult(
-  error: string | Error,
-  metadata?: Record<string, unknown>
-): HandlerResult<never> {
-  const errorMessage = error instanceof Error ? error.message : error;
-
-  return {
-    success: false,
-    error: errorMessage,
-    metadata,
-  };
-}
-
-/**
- * Safely execute an async operation and return a HandlerResult
- * This provides consistent error handling across all handlers
- */
-export async function safeExecute<T>(
-  operation: () => Promise<T>,
-  errorContext?: string
-): Promise<HandlerResult<T>> {
-  try {
-    const result = await operation();
-    return createSuccessResult(result);
-  } catch (error) {
-    const errorMessage =
-      error instanceof Error ? error.message : 'Unknown error';
-    const contextualError = errorContext
-      ? `${errorContext}: ${errorMessage}`
-      : errorMessage;
-
-    logger.error('Operation failed', error as Error, { errorContext });
-    return createErrorResult(contextualError);
-  }
-}
-
-/**
- * Validate required arguments for tool handlers
- * Throws an error if any required arguments are missing
- */
-export function validateRequiredArgs(
-  args: unknown,
-  requiredFields: string[]
-): void {
-  const missingFields = requiredFields.filter(
-    field =>
-      (args as Record<string, unknown>)[field] === undefined ||
-      (args as Record<string, unknown>)[field] === null
-  );
-
-  if (missingFields.length > 0) {
-    throw new Error(`Missing required arguments: ${missingFields.join(', ')}`);
-  }
-}
-
-/**
- * Check if a conversation exists and provide helpful error if not
- */
-export function createConversationNotFoundResult(
-  availableWorkflows: string[] = []
-): HandlerResult<never> {
-  if (availableWorkflows.length === 0) {
-    return createErrorResult(
-      'No development conversation has been started for this project. Please call start_development() to begin. First, set up workflows by adjusting the VIBE_WORKFLOW_DOMAINS environment variable or copying a workflow to .vibe/workflows/ directory.',
-      {
-        suggestion:
-          'Set VIBE_WORKFLOW_DOMAINS=code,architecture,office or copy a workflow file to .vibe/workflows/',
-        availableWorkflows: [],
-      }
-    );
-  }
-
-  return createErrorResult(
-    'No development conversation has been started for this project. Please call start_development() with a workflow parameter to begin development.',
-    {
-      suggestion: 'Call start_development() to begin',
-      availableWorkflows,
-    }
-  );
-}
-
-/**
- * Extract workflow names for enum generation
- * Used by server configuration to build Zod schemas
- */
-export function buildWorkflowEnum(
-  workflowNames: string[]
-): [string, ...string[]] {
-  const allWorkflows = [...workflowNames, 'custom'];
-
-  // Ensure we have at least one element for TypeScript
-  if (allWorkflows.length === 0) {
-    return ['waterfall'];
-  }
-
-  return allWorkflows as [string, ...string[]];
-}
-
-/**
- * Generate workflow description for tool schemas
- */
-export function generateWorkflowDescription(
-  workflows: Array<{
-    name: string;
-    displayName: string;
-    description: string;
-    metadata?: {
-      complexity?: 'low' | 'medium' | 'high';
-      bestFor?: string[];
-      useCases?: string[];
-      examples?: string[];
-    };
-  }>
-): string {
-  let description = 'Choose your development workflow:\n\n';
-
-  for (const workflow of workflows) {
-    description += `• **${workflow.name}**: ${workflow.displayName} - ${workflow.description}`;
-
-    // Add enhanced metadata if available
-    if (workflow.metadata) {
-      const meta = workflow.metadata;
-
-      // Add complexity
-      if (meta.complexity) {
-        description += `\n  Complexity: ${meta.complexity}`;
-      }
-
-      // Add best for information
-      if (meta.bestFor && meta.bestFor.length > 0) {
-        description += `\n  Best for: ${meta.bestFor.join(', ')}`;
-      }
-
-      // Add examples
-      if (meta.examples && meta.examples.length > 0) {
-        description += `\n  Examples: ${meta.examples.slice(0, 2).join(', ')}`;
-        if (meta.examples.length > 2) {
-          description += `, and ${meta.examples.length - 2} more`;
-        }
-      }
-    }
-
-    description += '\n';
-  }
-
-  description +=
-    '• **custom**: Use custom workflow from .vibe/workflows in your project\n\n';
-
-  return description;
-}
-
-/**
- * Log handler execution for debugging
- */
-export function logHandlerExecution(handlerName: string, args: unknown): void {
-  logger.debug(`Executing ${handlerName} handler`, {
-    handlerName,
-    argsKeys: Object.keys(args || {}),
-  });
-}
-
-/**
- * Log handler completion for debugging
- */
-export function logHandlerCompletion(
-  handlerName: string,
-  result: HandlerResult<unknown>
-): void {
-  logger.debug(`Completed ${handlerName} handler`, {
-    handlerName,
-    success: result.success,
-    hasData: !!result.data,
-    hasError: !!result.error,
-  });
-}
-
-/**
- * Strip /.vibe suffix from project path if present
- *
- * @param providedPath - Optional project path provided by user
- * @param defaultPath - Default project path from context
- * @returns Normalized project root path
- */
-export function stripVibePathSuffix(
-  providedPath: string | undefined,
-  defaultPath: string
-): string {
-  if (!providedPath) {
-    return defaultPath;
-  }
-
-  // Strip /.vibe suffix if present to get project root
-  return providedPath.endsWith('/.vibe')
-    ? providedPath.slice(0, -6) // Remove '/.vibe'
-    : providedPath;
-}

package/src/server-implementation.ts

@@ -1,277 +0,0 @@
-/**
- * Refactored Vibe Feature MCP Server
- *
- * Main server orchestrator that brings together all the modular components.
- * This replaces the monolithic server.ts with a clean, modular architecture.
- */
-
-import { setMcpServerForLogging, createLogger } from '@codemcp/workflows-core';
-import { ServerConfig } from './types.js';
-import {
-  initializeServerComponents,
-  registerMcpTools,
-  registerMcpResources,
-  ServerComponents,
-} from './server-config.js';
-import { createToolRegistry } from './tool-handlers/index.js';
-import { createResourceRegistry } from './resource-handlers/index.js';
-import { createResponseRenderer } from './response-renderer.js';
-import type {
-  ProceedToPhaseArgs,
-  ProceedToPhaseResult,
-  StartDevelopmentArgs,
-  StartDevelopmentResult,
-  ResumeWorkflowArgs,
-  ResumeWorkflowResult,
-  ResetDevelopmentArgs,
-  ResetDevelopmentResult,
-} from './tool-handlers/index.js';
-
-const logger = createLogger('ResponsibleVibeMCPServer');
-
-/**
- * Factory function to create a server with real components
- */
-export async function createResponsibleVibeMCPServer(
-  config: ServerConfig = {}
-): Promise<ResponsibleVibeMCPServer> {
-  const components = await initializeServerComponents(config);
-  return new ResponsibleVibeMCPServer(config, components);
-}
-
-/**
- * Main server class that orchestrates all components
- * Can be used both as a standalone process and in-process for testing
- */
-export class ResponsibleVibeMCPServer {
-  private components: ServerComponents | null = null;
-
-  constructor(
-    private config: ServerConfig,
-    private serverComponents: ServerComponents
-  ) {
-    logger.debug('ResponsibleVibeMCPServer created', {
-      config: JSON.stringify(this.config),
-    });
-  }
-
-  /**
-   * Initialize the server and all its components
-   */
-  async initialize(): Promise<void> {
-    logger.debug('Initializing ResponsibleVibeMCPServer');
-
-    try {
-      // Use injected components
-      this.components = this.serverComponents;
-
-      // Create registries and renderer
-      const toolRegistry = createToolRegistry();
-      const resourceRegistry = createResourceRegistry();
-      const responseRenderer = createResponseRenderer();
-
-      // Update components with registries and renderer
-      this.components.toolRegistry = toolRegistry;
-      this.components.resourceRegistry = resourceRegistry;
-      this.components.responseRenderer = responseRenderer;
-
-      // Register MCP server for logging notifications
-      setMcpServerForLogging(this.components.mcpServer);
-
-      // Register tools and resources with MCP server
-      await registerMcpTools(
-        this.components.mcpServer,
-        toolRegistry,
-        responseRenderer,
-        this.components.context
-      );
-
-      registerMcpResources(
-        this.components.mcpServer,
-        resourceRegistry,
-        responseRenderer,
-        this.components.context
-      );
-    } catch (error) {
-      logger.error(
-        'Failed to initialize ResponsibleVibeMCPServer',
-        error as Error
-      );
-      throw error;
-    }
-  }
-
-  /**
-   * Get the underlying MCP server instance
-   * This allows for both transport-based and direct testing
-   */
-  public getMcpServer() {
-    if (!this.components) {
-      throw new Error('Server not initialized. Call initialize() first.');
-    }
-    return this.components.mcpServer;
-  }
-
-  /**
-   * Get project path
-   */
-  public getProjectPath(): string {
-    if (!this.components) {
-      throw new Error('Server not initialized. Call initialize() first.');
-    }
-    return this.components.context.projectPath;
-  }
-
-  /**
-   * Get conversation manager (for testing)
-   */
-  public getConversationManager() {
-    if (!this.components) {
-      throw new Error('Server not initialized. Call initialize() first.');
-    }
-    return this.components.context.conversationManager;
-  }
-
-  /**
-   * Get plan manager (for testing)
-   */
-  public getPlanManager() {
-    if (!this.components) {
-      throw new Error('Server not initialized. Call initialize() first.');
-    }
-    return this.components.context.planManager;
-  }
-
-  /**
-   * Direct access to tool handlers for testing
-   */
-  public async handleWhatsNext(args: unknown): Promise<unknown> {
-    if (!this.components) {
-      throw new Error('Server not initialized. Call initialize() first.');
-    }
-
-    const handler = this.components.toolRegistry.get('whats_next');
-    if (!handler) {
-      throw new Error('whats_next handler not found');
-    }
-
-    const result = await handler.handle(args, this.components.context);
-    if (!result.success) {
-      throw new Error(result.error || 'Handler execution failed');
-    }
-
-    return result.data;
-  }
-
-  /**
-   * Direct access to tool handlers for testing
-   */
-  public async handleProceedToPhase(
-    args: ProceedToPhaseArgs
-  ): Promise<ProceedToPhaseResult> {
-    if (!this.components) {
-      throw new Error('Server not initialized. Call initialize() first.');
-    }
-
-    const handler = this.components.toolRegistry.get('proceed_to_phase');
-    if (!handler) {
-      throw new Error('proceed_to_phase handler not found');
-    }
-
-    const result = await handler.handle(args, this.components.context);
-    if (!result.success) {
-      throw new Error(result.error || 'Handler execution failed');
-    }
-
-    return result.data as ProceedToPhaseResult;
-  }
-
-  /**
-   * Direct access to tool handlers for testing
-   */
-  public async handleStartDevelopment(
-    args: StartDevelopmentArgs
-  ): Promise<StartDevelopmentResult> {
-    if (!this.components) {
-      throw new Error('Server not initialized. Call initialize() first.');
-    }
-
-    const handler = this.components.toolRegistry.get('start_development');
-    if (!handler) {
-      throw new Error('start_development handler not found');
-    }
-
-    const result = await handler.handle(args, this.components.context);
-    if (!result.success) {
-      throw new Error(result.error || 'Handler execution failed');
-    }
-
-    return result.data as StartDevelopmentResult;
-  }
-
-  /**
-   * Direct access to tool handlers for testing
-   */
-  public async handleResumeWorkflow(
-    args: ResumeWorkflowArgs
-  ): Promise<ResumeWorkflowResult> {
-    if (!this.components) {
-      throw new Error('Server not initialized. Call initialize() first.');
-    }
-
-    const handler = this.components.toolRegistry.get('resume_workflow');
-    if (!handler) {
-      throw new Error('resume_workflow handler not found');
-    }
-
-    const result = await handler.handle(args, this.components.context);
-    if (!result.success) {
-      throw new Error(result.error || 'Handler execution failed');
-    }
-
-    return result.data as ResumeWorkflowResult;
-  }
-
-  /**
-   * Direct access to tool handlers for testing
-   */
-  public async handleResetDevelopment(
-    args: ResetDevelopmentArgs
-  ): Promise<ResetDevelopmentResult> {
-    if (!this.components) {
-      throw new Error('Server not initialized. Call initialize() first.');
-    }
-
-    const handler = this.components.toolRegistry.get('reset_development');
-    if (!handler) {
-      throw new Error('reset_development handler not found');
-    }
-
-    const result = await handler.handle(args, this.components.context);
-    if (!result.success) {
-      throw new Error(result.error || 'Handler execution failed');
-    }
-
-    return result.data as ResetDevelopmentResult;
-  }
-
-  /**
-   * Cleanup server resources
-   */
-  public async cleanup(): Promise<void> {
-    logger.debug('Cleaning up server resources');
-
-    if (this.components?.database) {
-      await this.components.database.close();
-    }
-
-    logger.info('Server cleanup completed');
-  }
-}
-
-// Export all types and utilities for external use
-export * from './types.js';
-export * from './server-helpers.js';
-export * from './response-renderer.js';
-export * from './tool-handlers/index.js';
-export * from './resource-handlers/index.js';

package/src/server.ts

@@ -1,9 +0,0 @@
-/**
- * Vibe Feature MCP Server Core
- */
-
-export {
-  ResponsibleVibeMCPServer,
-  createResponsibleVibeMCPServer,
-} from './server-implementation.js';
-export type { ServerConfig } from './types.js';

package/src/tool-handlers/base-tool-handler.ts

@@ -1,151 +0,0 @@
-/**
- * Base Tool Handler
- *
- * Provides common functionality for all tool handlers including
- * error handling, logging, and conversation state management.
- */
-
-import { createLogger } from '@codemcp/workflows-core';
-import { ToolHandler, ServerContext, HandlerResult } from '../types.js';
-import type { ConversationContext } from '@codemcp/workflows-core';
-import {
-  safeExecute,
-  logHandlerExecution,
-  logHandlerCompletion,
-  createConversationNotFoundResult,
-} from '../server-helpers.js';
-
-/**
- * Abstract base class for tool handlers
- * Provides common functionality and enforces consistent patterns
- */
-export abstract class BaseToolHandler<
-  TArgs = unknown,
-  TResult = unknown,
-> implements ToolHandler<TArgs, TResult> {
-  protected readonly logger: ReturnType<typeof createLogger>;
-
-  constructor() {
-    this.logger = createLogger(this.constructor.name);
-  }
-
-  /**
-   * Main handler method - implements consistent error handling and logging
-   */
-  async handle(
-    args: TArgs,
-    context: ServerContext
-  ): Promise<HandlerResult<TResult>> {
-    const handlerName = this.constructor.name;
-    logHandlerExecution(handlerName, args);
-
-    const result = await safeExecute(
-      () => this.executeHandler(args, context),
-      `${handlerName} execution failed`
-    );
-
-    // Check if this is a CONVERSATION_NOT_FOUND error and provide helpful guidance
-    if (!result.success && result.error?.includes('CONVERSATION_NOT_FOUND')) {
-      const availableWorkflows = context.workflowManager.getWorkflowNames();
-      const helpfulError = createConversationNotFoundResult(availableWorkflows);
-      logHandlerCompletion(handlerName, helpfulError);
-      return helpfulError as HandlerResult<TResult>;
-    }
-
-    logHandlerCompletion(handlerName, result);
-    return result;
-  }
-
-  /**
-   * Abstract method that subclasses must implement
-   * Contains the actual business logic for the tool
-   */
-  protected abstract executeHandler(
-    args: TArgs,
-    context: ServerContext
-  ): Promise<TResult>;
-
-  /**
-   * Helper method to get conversation context with proper error handling
-   */
-  protected async getConversationContext(context: ServerContext) {
-    try {
-      return await context.conversationManager.getConversationContext();
-    } catch (error) {
-      this.logger.info('Conversation not found', { error });
-      throw new Error('CONVERSATION_NOT_FOUND');
-    }
-  }
-
-  /**
-   * Helper method to ensure state machine is loaded for a project
-   */
-  protected ensureStateMachineForProject(
-    context: ServerContext,
-    projectPath: string,
-    workflowName?: string
-  ): void {
-    const stateMachine = context.transitionEngine.getStateMachine(
-      projectPath,
-      workflowName
-    );
-    context.planManager.setStateMachine(stateMachine);
-    context.instructionGenerator.setStateMachine(stateMachine);
-  }
-
-  /**
-   * Helper method to log interactions if logger is available
-   */
-  protected async logInteraction(
-    context: ServerContext,
-    conversationId: string,
-    toolName: string,
-    args: unknown,
-    response: unknown,
-    phase: string
-  ): Promise<void> {
-    if (context.interactionLogger) {
-      await context.interactionLogger.logInteraction(
-        conversationId,
-        toolName,
-        args,
-        response,
-        phase
-      );
-    }
-  }
-}
-
-/**
- * Base class for tool handlers that require an existing conversation
- * Automatically handles the conversation-not-found case
- */
-export abstract class ConversationRequiredToolHandler<
-  TArgs = unknown,
-  TResult = unknown,
-> extends BaseToolHandler<TArgs, TResult> {
-  protected async executeHandler(
-    args: TArgs,
-    context: ServerContext
-  ): Promise<TResult> {
-    let conversationContext;
-
-    try {
-      conversationContext = await this.getConversationContext(context);
-    } catch (_error) {
-      // Return a special error result that the response renderer can handle
-      throw new Error('CONVERSATION_NOT_FOUND');
-    }
-
-    return this.executeWithConversation(args, context, conversationContext);
-  }
-
-  /**
-   * Abstract method for handlers that need conversation context
-   */
-  protected abstract executeWithConversation(
-    args: TArgs,
-    context: ServerContext,
-    conversationContext: ConversationContext
-  ): Promise<TResult>;
-}