@codemcp/workflows 5.0.1 → 5.1.1

package/src/tool-handlers/start-development.ts

@@ -1,746 +0,0 @@
-/**
- * StartDevelopment Tool Handler
- *
- * Handles initialization of development workflow and transition to the initial
- * development phase. Allows users to choose from predefined workflows or use a custom workflow.
- */
-
-import { BaseToolHandler } from './base-tool-handler.js';
-import {
-  validateRequiredArgs,
-  stripVibePathSuffix,
-} from '../server-helpers.js';
-import { basename } from 'node:path';
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
-import { readFile, writeFile } from 'node:fs/promises';
-import { resolve } from 'node:path';
-import type { YamlStateMachine } from '@codemcp/workflows-core';
-import { ProjectDocsManager, ProjectDocsInfo } from '@codemcp/workflows-core';
-import { TaskBackendManager } from '@codemcp/workflows-core';
-import { createLogger } from '@codemcp/workflows-core';
-import { ServerContext } from '../types.js';
-import type { PluginHookContext } from '../plugin-system/plugin-interfaces.js';
-
-const logger = createLogger('StartDevelopmentHandler');
-
-/**
- * Arguments for the start_development tool
- */
-export interface StartDevelopmentArgs {
-  workflow: string;
-  require_reviews?: boolean;
-  project_path?: string;
-}
-
-/**
- * Response from the start_development tool
- */
-export interface StartDevelopmentResult {
-  phase: string;
-  instructions: string;
-  plan_file_path: string;
-  workflowDocumentationUrl?: string;
-}
-
-/**
- * StartDevelopment tool handler implementation
- */
-export class StartDevelopmentHandler extends BaseToolHandler<
-  StartDevelopmentArgs,
-  StartDevelopmentResult
-> {
-  private projectDocsManager: ProjectDocsManager;
-
-  constructor() {
-    super();
-    this.projectDocsManager = new ProjectDocsManager();
-  }
-
-  protected async executeHandler(
-    args: StartDevelopmentArgs,
-    context: ServerContext
-  ): Promise<StartDevelopmentResult> {
-    // Validate required arguments
-    validateRequiredArgs(args, ['workflow']);
-
-    // Validate task backend configuration
-    const taskBackendConfig = TaskBackendManager.validateTaskBackend();
-
-    const selectedWorkflow = args.workflow;
-    const requireReviews = args.require_reviews ?? false;
-
-    // Normalize project path - strip /.vibe suffix if present
-    const projectPath = stripVibePathSuffix(
-      args.project_path,
-      context.projectPath
-    );
-
-    this.logger.debug('Processing start_development request', {
-      selectedWorkflow,
-      projectPath: projectPath,
-    });
-
-    // Validate workflow selection (ensure project workflows are loaded first)
-    context.workflowManager.loadProjectWorkflows(projectPath);
-    if (
-      !context.workflowManager.validateWorkflowName(
-        selectedWorkflow,
-        projectPath
-      )
-    ) {
-      const availableWorkflows = context.workflowManager.getWorkflowNames();
-      throw new Error(
-        `Invalid workflow: ${selectedWorkflow}. Available workflows: ${availableWorkflows.join(', ')}`
-      );
-    }
-
-    // Check for project documentation artifacts and guide setup if needed
-    const artifactGuidance = await this.checkProjectArtifacts(
-      projectPath,
-      selectedWorkflow,
-      context
-    );
-    if (artifactGuidance) {
-      return artifactGuidance;
-    }
-
-    // Check if user is on main/master branch and prompt for branch creation
-    const currentBranch = this.getCurrentGitBranch(projectPath);
-    if (currentBranch === 'main' || currentBranch === 'master') {
-      const suggestedBranchName = this.generateBranchSuggestion();
-      const branchPromptResponse: StartDevelopmentResult = {
-        phase: 'branch-prompt',
-        instructions: `You're currently on the ${currentBranch} branch. It's recommended to create a feature branch for development. Propose a branch creation by suggesting a branch command to the user call start_development again.\n\nSuggested command: \`git checkout -b ${suggestedBranchName}\`\n\nPlease create a new branch and then call start_development again to begin development.`,
-        plan_file_path: '',
-      };
-
-      this.logger.debug(
-        'User on main/master branch, prompting for branch creation',
-        {
-          currentBranch,
-          suggestedBranchName,
-        }
-      );
-
-      return branchPromptResponse;
-    }
-
-    // Create or get conversation context with the selected workflow
-    const conversationContext =
-      await context.conversationManager.createConversationContext(
-        selectedWorkflow,
-        args.project_path ? projectPath : undefined
-      );
-    const currentPhase = conversationContext.currentPhase;
-
-    // Load the selected workflow
-    const stateMachine = context.workflowManager.loadWorkflowForProject(
-      conversationContext.projectPath,
-      selectedWorkflow
-    );
-    const initialState = stateMachine.initial_state;
-
-    // Check if development is already started
-    if (currentPhase !== initialState) {
-      throw new Error(
-        `Development already started. Current phase is '${currentPhase}', not initial state '${initialState}'. Use whats_next() to continue development.`
-      );
-    }
-
-    // The initial state IS the first development phase - it's explicitly modeled
-    const targetPhase = initialState;
-
-    // Transition to the initial development phase
-    const transitionResult =
-      await context.transitionEngine.handleExplicitTransition(
-        currentPhase,
-        targetPhase,
-        projectPath,
-        'Development initialization',
-        selectedWorkflow
-      );
-
-    // Update conversation state with workflow and phase
-    await context.conversationManager.updateConversationState(
-      conversationContext.conversationId,
-      {
-        currentPhase: transitionResult.newPhase,
-        workflowName: selectedWorkflow,
-        requireReviewsBeforePhaseTransition: requireReviews,
-      }
-    );
-
-    // Set state machine on plan manager before creating plan file
-    context.planManager.setStateMachine(stateMachine);
-
-    // Set task backend configuration if supported (for backwards compatibility)
-    if (typeof context.planManager.setTaskBackend === 'function') {
-      context.planManager.setTaskBackend(taskBackendConfig);
-    }
-
-    // Ensure plan file exists
-    await context.planManager.ensurePlanFile(
-      conversationContext.planFilePath,
-      projectPath,
-      conversationContext.gitBranch
-    );
-
-    // Prepare plugin context for hooks
-    const pluginContext: PluginHookContext = {
-      conversationId: conversationContext.conversationId,
-      planFilePath: conversationContext.planFilePath,
-      currentPhase: conversationContext.currentPhase,
-      workflow: selectedWorkflow,
-      projectPath,
-      gitBranch: conversationContext.gitBranch,
-      stateMachine: {
-        name: stateMachine.name,
-        description: stateMachine.description,
-        initial_state: stateMachine.initial_state,
-        states: stateMachine.states,
-      },
-    };
-
-    // Execute afterPlanFileCreated hook to allow plugins to modify the plan file
-    if (context.pluginRegistry) {
-      try {
-        const originalContent = await readFile(
-          conversationContext.planFilePath,
-          'utf-8'
-        );
-        const modifiedContent = await context.pluginRegistry.executeHook(
-          'afterPlanFileCreated',
-          pluginContext,
-          conversationContext.planFilePath,
-          originalContent
-        );
-
-        // Write the modified content back to the file if it changed
-        if (modifiedContent && modifiedContent !== originalContent) {
-          await writeFile(
-            conversationContext.planFilePath,
-            modifiedContent as string,
-            'utf-8'
-          );
-        }
-      } catch (error) {
-        // Gracefully handle cases where plan file doesn't exist (e.g., in tests)
-        // This is not a critical error - plugins can still function without modifying the plan file
-        logger.debug('Could not execute afterPlanFileCreated hook', {
-          error: error instanceof Error ? error.message : String(error),
-          planFilePath: conversationContext.planFilePath,
-        });
-      }
-    }
-
-    // Execute afterStartDevelopment hook
-    if (context.pluginRegistry) {
-      await context.pluginRegistry.executeHook(
-        'afterStartDevelopment',
-        pluginContext,
-        {
-          workflow: selectedWorkflow,
-          require_reviews: args.require_reviews,
-          project_path: projectPath,
-        },
-        {
-          conversationId: conversationContext.conversationId,
-          planFilePath: conversationContext.planFilePath,
-          phase: conversationContext.currentPhase,
-          workflow: selectedWorkflow,
-        }
-      );
-    }
-
-    // Ensure .vibe/.gitignore exists to exclude SQLite files for git repositories
-    this.ensureGitignoreEntry(projectPath);
-
-    // Generate workflow documentation URL
-    const workflowDocumentationUrl =
-      this.generateWorkflowDocumentationUrl(selectedWorkflow);
-
-    // Generate instructions with simple i18n guidance
-    const baseInstructions = `Look at the plan file (${conversationContext.planFilePath}). Define entrance criteria for each phase of the workflow except the initial phase. Those criteria shall be based on the contents of the previous phase. \n      Example: \n      \`\`\`\n      ## Design\n\n      ### Phase Entrance Criteria:\n      - [ ] The requirements have been thoroughly defined.\n      - [ ] Alternatives have been evaluated and are documented. \n      - [ ] It's clear what's in scope and out of scope\n      \`\`\`\n      \n      IMPORTANT: Once you added reasonable entrance call the whats_next() tool to get guided instructions for the next current phase.`;
-
-    const i18nGuidance = `\n\nNOTE: If the user is communicating in a non-English language, please translate the plan file content to that language while keeping the structure intact, and continue all interactions in the user's language.`;
-
-    // Add workflow documentation information if available
-    const workflowDocumentationInfo = workflowDocumentationUrl
-      ? `\n\nInform the user about the chose workflow: He can visit: ${workflowDocumentationUrl} to get detailed information.`
-      : '';
-
-    const finalInstructions =
-      baseInstructions + workflowDocumentationInfo + i18nGuidance;
-
-    const response: StartDevelopmentResult = {
-      phase: transitionResult.newPhase,
-      instructions: finalInstructions,
-      plan_file_path: conversationContext.planFilePath,
-      workflowDocumentationUrl,
-    };
-
-    // Log interaction
-    await this.logInteraction(
-      context,
-      conversationContext.conversationId,
-      'start_development',
-      args,
-      response,
-      transitionResult.newPhase
-    );
-
-    return response;
-  }
-
-  /**
-   * Check if project documentation artifacts exist and provide setup guidance if needed
-   * Dynamically analyzes the selected workflow to determine which documents are referenced
-   * Blocks workflow start if the workflow requires documentation
-   */
-  private async checkProjectArtifacts(
-    projectPath: string,
-    workflowName: string,
-    context: ServerContext
-  ): Promise<StartDevelopmentResult | null> {
-    try {
-      // Load the workflow to analyze its content
-      const stateMachine = context.workflowManager.loadWorkflowForProject(
-        projectPath,
-        workflowName
-      );
-
-      // Check if this workflow requires documentation (defaults to false)
-      const requiresDocumentation =
-        stateMachine.metadata?.requiresDocumentation ?? false;
-
-      // If workflow doesn't require documentation, skip artifact check entirely
-      if (!requiresDocumentation) {
-        this.logger.debug(
-          'Workflow does not require documentation, skipping artifact check',
-          { workflowName, requiresDocumentation }
-        );
-        return null;
-      }
-
-      // Analyze workflow content to detect referenced document variables
-      const referencedVariables = this.analyzeWorkflowDocumentReferences(
-        stateMachine,
-        projectPath
-      );
-
-      // If no document variables are referenced, skip artifact check
-      if (referencedVariables.length === 0) {
-        this.logger.debug(
-          'No document variables found in workflow, skipping artifact check',
-          { workflowName }
-        );
-        return null;
-      }
-
-      // Check which referenced documents are missing
-      const docsInfo =
-        await this.projectDocsManager.getProjectDocsInfo(projectPath);
-      const missingDocs = this.getMissingReferencedDocuments(
-        referencedVariables,
-        docsInfo,
-        projectPath
-      );
-
-      // If all referenced documents exist, continue with normal flow
-      if (missingDocs.length === 0) {
-        this.logger.debug(
-          'All referenced project artifacts exist, continuing with development',
-          {
-            workflowName,
-            referencedVariables,
-          }
-        );
-        return null;
-      }
-
-      // Generate guidance for setting up missing artifacts
-      const setupGuidance = await this.generateArtifactSetupGuidance(
-        missingDocs,
-        workflowName,
-        docsInfo,
-        referencedVariables
-      );
-
-      this.logger.info(
-        'Missing required project artifacts detected for workflow that requires documentation',
-        {
-          workflowName,
-          requiresDocumentation,
-          referencedVariables,
-          missingDocs,
-          projectPath,
-        }
-      );
-
-      return {
-        phase: 'artifact-setup',
-        instructions: setupGuidance,
-        plan_file_path: '',
-      };
-    } catch (error) {
-      this.logger.warn(
-        'Failed to analyze workflow for document references, proceeding without artifact check',
-        {
-          workflowName,
-          error: error instanceof Error ? error.message : String(error),
-        }
-      );
-      return null;
-    }
-  }
-
-  /**
-   * Analyze workflow content to detect document variable references
-   */
-  private analyzeWorkflowDocumentReferences(
-    stateMachine: YamlStateMachine,
-    projectPath: string
-  ): string[] {
-    // Get available document variables from ProjectDocsManager
-    const variableSubstitutions =
-      this.projectDocsManager.getVariableSubstitutions(projectPath);
-    const documentVariables = Object.keys(variableSubstitutions);
-    const referencedVariables: Set<string> = new Set();
-
-    // Convert the entire state machine to a string for analysis
-    const workflowContent = JSON.stringify(stateMachine);
-
-    // Check for each document variable
-    for (const variable of documentVariables) {
-      if (workflowContent.includes(variable)) {
-        referencedVariables.add(variable);
-      }
-    }
-
-    this.logger.debug('Analyzed workflow for document references', {
-      workflowContent: workflowContent.length + ' characters',
-      availableVariables: documentVariables,
-      referencedVariables: Array.from(referencedVariables),
-    });
-
-    return Array.from(referencedVariables);
-  }
-
-  /**
-   * Determine which referenced documents are missing
-   */
-  private getMissingReferencedDocuments(
-    referencedVariables: string[],
-    docsInfo: ProjectDocsInfo,
-    projectPath: string
-  ): string[] {
-    const missingDocs: string[] = [];
-
-    // Get variable substitutions to derive the mapping
-    const variableSubstitutions =
-      this.projectDocsManager.getVariableSubstitutions(projectPath, undefined);
-
-    // Create reverse mapping from variable to document type
-    const variableToDocMap: { [key: string]: string } = {};
-    for (const [variable, path] of Object.entries(variableSubstitutions)) {
-      // Extract document type from path (e.g., 'architecture' from 'architecture.md')
-      const filename = path.split('/').pop() || '';
-      const docType = filename.replace('.md', '');
-      variableToDocMap[variable] = docType;
-    }
-
-    for (const variable of referencedVariables) {
-      const docType = variableToDocMap[variable];
-      if (docType && docType in docsInfo) {
-        const docInfo = docsInfo[docType as keyof ProjectDocsInfo];
-        if (docInfo && !docInfo.exists) {
-          missingDocs.push(`${docType}.md`);
-        }
-      }
-    }
-
-    return missingDocs;
-  }
-
-  /**
-   * Generate guidance for setting up missing project artifacts
-   */
-  private async generateArtifactSetupGuidance(
-    missingDocs: string[],
-    workflowName: string,
-    docsInfo: ProjectDocsInfo,
-    referencedVariables: string[]
-  ): Promise<string> {
-    const missingList = missingDocs.map(doc => `- ${doc}`).join('\n');
-    const existingDocs = [];
-
-    if (docsInfo.architecture.exists) {
-      const fileName = basename(docsInfo.architecture.path);
-      existingDocs.push(`✅ ${fileName}`);
-    }
-    if (docsInfo.requirements.exists) {
-      const fileName = basename(docsInfo.requirements.path);
-      existingDocs.push(`✅ ${fileName}`);
-    }
-    if (docsInfo.design.exists) {
-      const fileName = basename(docsInfo.design.path);
-      existingDocs.push(`✅ ${fileName}`);
-    }
-
-    const existingList =
-      existingDocs.length > 0
-        ? `\n\n**Existing Documents:**\n${existingDocs.join('\n')}`
-        : '';
-
-    const referencedVariablesList = referencedVariables
-      .map(v => `\`${v}\``)
-      .join(', ');
-
-    // Get available templates dynamically
-    const availableTemplates =
-      await this.projectDocsManager.templateManager.getAvailableTemplates();
-    const defaults =
-      await this.projectDocsManager.templateManager.getDefaults();
-
-    // Generate template options dynamically
-    const templateOptionsText =
-      this.generateTemplateOptionsText(availableTemplates);
-
-    return `## Project Documentation Setup Required
-
-The **${workflowName}** workflow references project documentation that doesn't exist yet.
-
-**Referenced Variables:** ${referencedVariablesList}
-
-**Missing Documents:**
-${missingList}${existingList}
-
-## 🚀 **Quick Setup**
-
-Use the \`setup_project_docs\` tool to create these documents with templates:
-
-\`\`\`
-setup_project_docs({
-  architecture: "${defaults.architecture}",        // or other available options
-  requirements: "${defaults.requirements}",         // or other available options
-  design: "${defaults.design}"       // or other available options
-})
-\`\`\`
-
-${templateOptionsText}
-
-## ⚡ **Next Steps**
-
-1. **Call \`setup_project_docs\`** with your preferred templates
-2. **Call \`start_development\`** again to begin the ${workflowName} workflow
-3. The workflow will reference these documents using the detected variables: ${referencedVariablesList}
-
-**Note:** You can also proceed without structured docs, but the workflow instructions will reference missing files.`;
-  }
-
-  /**
-   * Generate template options text dynamically
-   */
-  private generateTemplateOptionsText(availableTemplates: {
-    architecture: string[];
-    requirements: string[];
-    design: string[];
-  }): string {
-    const sections = [];
-
-    if (availableTemplates.architecture.length > 0) {
-      const archOptions = availableTemplates.architecture
-        .map(template => {
-          const description = this.getTemplateDescription(
-            template,
-            'architecture'
-          );
-          return `- **${template}**: ${description}`;
-        })
-        .join('\n');
-      sections.push(`**Architecture Templates:**\n${archOptions}`);
-    }
-
-    if (availableTemplates.requirements.length > 0) {
-      const reqOptions = availableTemplates.requirements
-        .map(template => {
-          const description = this.getTemplateDescription(
-            template,
-            'requirements'
-          );
-          return `- **${template}**: ${description}`;
-        })
-        .join('\n');
-      sections.push(`**Requirements Templates:**\n${reqOptions}`);
-    }
-
-    if (availableTemplates.design.length > 0) {
-      const designOptions = availableTemplates.design
-        .map(template => {
-          const description = this.getTemplateDescription(template, 'design');
-          return `- **${template}**: ${description}`;
-        })
-        .join('\n');
-      sections.push(`**Design Templates:**\n${designOptions}`);
-    }
-
-    return sections.length > 0
-      ? `## 📋 **Template Options**\n\n${sections.join('\n\n')}`
-      : '';
-  }
-
-  /**
-   * Get description for a template based on its name and type
-   */
-  private getTemplateDescription(template: string, type: string): string {
-    switch (template) {
-      case 'arc42':
-        return 'Comprehensive software architecture template with diagrams';
-      case 'ears':
-        return 'WHEN...THEN format for clear, testable requirements';
-      case 'comprehensive':
-        return 'Full implementation guide with testing strategy';
-      case 'freestyle':
-        return `Simple, flexible ${type} documentation`;
-      default:
-        return `${template} format for ${type} documentation`;
-    }
-  }
-
-  /**
-   * Generate workflow documentation URL for predefined workflows
-   * Returns undefined for custom 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}`;
-  }
-
-  /**
-   * Get the current git branch for a project
-   * Uses the same logic as ConversationManager but locally accessible
-   */
-  private getCurrentGitBranch(projectPath: string): string {
-    try {
-      const { execSync } = require('node:child_process');
-      const { existsSync } = require('node:fs');
-
-      // Check if this is a git repository
-      if (!existsSync(`${projectPath}/.git`)) {
-        this.logger.debug(
-          'Not a git repository, using "default" as branch name',
-          { projectPath }
-        );
-        return 'default';
-      }
-
-      // Get current branch name
-      // Use symbolic-ref which works even without commits (unlike rev-parse --abbrev-ref HEAD)
-      const branch = execSync('git symbolic-ref --short HEAD', {
-        cwd: projectPath,
-        encoding: 'utf-8',
-        stdio: ['ignore', 'pipe', 'ignore'], // Suppress stderr
-      }).trim();
-
-      this.logger.debug('Detected git branch', { projectPath, branch });
-
-      return branch;
-    } catch (_error) {
-      this.logger.debug(
-        'Failed to get git branch, using "default" as branch name',
-        { projectPath }
-      );
-      return 'default';
-    }
-  }
-
-  /**
-   * Generate a suggested branch name for feature development
-   */
-  private generateBranchSuggestion(): string {
-    const timestamp = new Date().toISOString().slice(0, 10).replace(/-/g, '');
-    return `feature/development-${timestamp}`;
-  }
-
-  /**
-   * Ensure .gitignore exists in .vibe folder to exclude SQLite files
-   * This function is idempotent and self-contained within the .vibe directory
-   */
-  private ensureGitignoreEntry(projectPath: string): void {
-    try {
-      // Check if this is a git repository
-      if (!existsSync(`${projectPath}/.git`)) {
-        this.logger.debug(
-          'Not a git repository, skipping .gitignore management',
-          { projectPath }
-        );
-        return;
-      }
-
-      const vibeDir = resolve(projectPath, '.vibe');
-      const gitignorePath = resolve(vibeDir, '.gitignore');
-
-      // Ensure .vibe directory exists
-      if (!existsSync(vibeDir)) {
-        mkdirSync(vibeDir, { recursive: true });
-      }
-
-      // Content for .vibe/.gitignore
-      const gitignoreContent = `# Exclude conversation state files
-conversations/
-# Legacy SQLite files (for migration compatibility)
-*.sqlite
-*.sqlite-*
-`;
-
-      // Check if .gitignore already exists and has the right content
-      if (existsSync(gitignorePath)) {
-        try {
-          const existingContent = readFileSync(gitignorePath, 'utf-8');
-          if (existingContent.includes('conversations/')) {
-            this.logger.debug(
-              '.vibe/.gitignore already exists with conversation exclusions',
-              { gitignorePath }
-            );
-            return;
-          }
-        } catch (error) {
-          this.logger.warn(
-            'Failed to read existing .vibe/.gitignore, will recreate',
-            {
-              gitignorePath,
-              error: error instanceof Error ? error.message : String(error),
-            }
-          );
-        }
-      }
-
-      // Write the .gitignore file
-      writeFileSync(gitignorePath, gitignoreContent, 'utf-8');
-
-      this.logger.info(
-        'Created .vibe/.gitignore to exclude conversation files',
-        {
-          projectPath,
-          gitignorePath,
-        }
-      );
-    } catch (error) {
-      // Log warning but don't fail development start
-      this.logger.warn(
-        'Failed to create .vibe/.gitignore, continuing with development start',
-        {
-          projectPath,
-          error: error instanceof Error ? error.message : String(error),
-        }
-      );
-    }
-  }
-}