@codemcp/workflows-core 3.1.22 → 3.2.1

package/src/template-manager.ts

@@ -1,328 +0,0 @@
-/**
- * Template Manager
- *
- * Handles loading and rendering of project document templates.
- * Supports different template formats for architecture, requirements, and design documents.
- */
-
-import { readFile, readdir, stat } from 'node:fs/promises';
-import { join, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { createRequire } from 'node:module';
-import { createLogger } from './logger.js';
-
-const logger = createLogger('TemplateManager');
-
-// Dynamic template types - will be populated from file system
-export type ArchitectureTemplate = string;
-export type RequirementsTemplate = string;
-export type DesignTemplate = string;
-
-export interface TemplateOptions {
-  architecture?: ArchitectureTemplate;
-  requirements?: RequirementsTemplate;
-  design?: DesignTemplate;
-}
-
-export interface TemplateResult {
-  content: string;
-  additionalFiles?: Array<{
-    relativePath: string;
-    content: Buffer;
-  }>;
-}
-
-export class TemplateManager {
-  private templatesPath: string;
-
-  constructor() {
-    this.templatesPath = this.resolveTemplatesPath();
-  }
-
-  /**
-   * Resolve templates path using similar strategy as WorkflowManager
-   */
-  private resolveTemplatesPath(): string {
-    const strategies: string[] = [];
-
-    // Strategy 1: Local resources directory (symlinked from root)
-    strategies.push(
-      join(dirname(fileURLToPath(import.meta.url)), '../resources/templates')
-    );
-
-    // Strategy 2: From compiled dist directory
-    const currentFileUrl = import.meta.url;
-    if (currentFileUrl.startsWith('file://')) {
-      const currentFilePath = fileURLToPath(currentFileUrl);
-      // From dist/template-manager.js -> ../resources/templates
-      strategies.push(join(dirname(currentFilePath), '../resources/templates'));
-    }
-
-    // Strategy 3: Current working directory (for development)
-    strategies.push(join(process.cwd(), 'resources/templates'));
-
-    // Strategy 4: From node_modules
-    strategies.push(
-      join(
-        process.cwd(),
-        'node_modules/@codemcp/workflows-core/resources/templates'
-      )
-    );
-
-    // Strategy 5: From package directory (for development)
-    try {
-      const require = createRequire(import.meta.url);
-      const packagePath = require.resolve(
-        '@codemcp/workflows-core/package.json'
-      );
-      const packageDir = dirname(packagePath);
-      strategies.push(join(packageDir, 'resources/templates'));
-    } catch (_error) {
-      // Ignore if package not found
-    }
-
-    // Find the first existing path
-    for (const strategy of strategies) {
-      try {
-        // This will throw if path doesn't exist
-        require('node:fs').accessSync(strategy);
-        logger.debug('Using templates path', { path: strategy });
-        return strategy;
-      } catch (_error) {
-        // Continue to next strategy
-      }
-    }
-
-    // Fallback to first strategy if none found
-    const fallback = strategies[0];
-    logger.warn('No templates directory found, using fallback', {
-      fallback,
-      strategies,
-    });
-    return fallback;
-  }
-
-  /**
-   * Get the default template options based on available templates
-   */
-  async getDefaults(): Promise<Required<TemplateOptions>> {
-    const availableTemplates = await this.getAvailableTemplates();
-
-    return {
-      architecture: this.getPreferredTemplate(availableTemplates.architecture, [
-        'arc42',
-        'freestyle',
-      ]),
-      requirements: this.getPreferredTemplate(availableTemplates.requirements, [
-        'ears',
-        'freestyle',
-      ]),
-      design: this.getPreferredTemplate(availableTemplates.design, [
-        'comprehensive',
-        'freestyle',
-      ]),
-    };
-  }
-
-  /**
-   * Get preferred template from available options, with fallback preferences
-   */
-  private getPreferredTemplate(
-    available: string[],
-    preferences: string[]
-  ): string {
-    // Try to find the first preference that's available
-    for (const preference of preferences) {
-      if (available.includes(preference)) {
-        return preference;
-      }
-    }
-
-    // If no preferences are available, return the first available template
-    return available[0] || preferences[0];
-  }
-
-  /**
-   * Load and render a template
-   */
-  async loadTemplate(
-    type: 'architecture' | 'requirements' | 'design',
-    template: string
-  ): Promise<TemplateResult> {
-    const templatePath = join(this.templatesPath, type, template);
-    const templateFilePath = `${templatePath}.md`;
-
-    try {
-      // First try to check if it's a directory (like arc42)
-      try {
-        const stats = await stat(templatePath);
-        if (stats.isDirectory()) {
-          return await this.loadDirectoryTemplate(templatePath);
-        }
-      } catch (_error) {
-        // Not a directory, continue to file check
-      }
-
-      // Try to load as a markdown file
-      const content = await readFile(templateFilePath, 'utf-8');
-      return { content };
-    } catch (error) {
-      logger.error(
-        `Failed to load template: ${type}/${template}`,
-        error as Error
-      );
-      throw new Error(
-        `Template not found: ${type}/${template}. Tried: ${templatePath} (directory) and ${templateFilePath} (file)`
-      );
-    }
-  }
-
-  /**
-   * Load a directory-based template (like arc42 with images)
-   */
-  private async loadDirectoryTemplate(
-    templatePath: string
-  ): Promise<TemplateResult> {
-    const additionalFiles: Array<{ relativePath: string; content: Buffer }> =
-      [];
-
-    // Find the main markdown file
-    const files = await readdir(templatePath);
-    const markdownFile = files.find(file => file.endsWith('.md'));
-
-    if (!markdownFile) {
-      throw new Error(
-        `No markdown file found in template directory: ${templatePath}`
-      );
-    }
-
-    const content = await readFile(join(templatePath, markdownFile), 'utf-8');
-
-    // Load additional files (like images)
-    await this.loadAdditionalFiles(templatePath, '', additionalFiles);
-
-    return {
-      content,
-      additionalFiles: additionalFiles.filter(
-        file => !file.relativePath.endsWith('.md')
-      ),
-    };
-  }
-
-  /**
-   * Recursively load additional files from template directory
-   */
-  private async loadAdditionalFiles(
-    basePath: string,
-    relativePath: string,
-    additionalFiles: Array<{ relativePath: string; content: Buffer }>
-  ): Promise<void> {
-    const currentPath = join(basePath, relativePath);
-    const items = await readdir(currentPath);
-
-    for (const item of items) {
-      const itemPath = join(currentPath, item);
-      const itemRelativePath = relativePath ? join(relativePath, item) : item;
-      const stats = await stat(itemPath);
-
-      if (stats.isDirectory()) {
-        // Recursively process subdirectories
-        await this.loadAdditionalFiles(
-          basePath,
-          itemRelativePath,
-          additionalFiles
-        );
-      } else if (!item.endsWith('.md')) {
-        // Load non-markdown files as additional files
-        const content = await readFile(itemPath);
-        additionalFiles.push({
-          relativePath: itemRelativePath,
-          content,
-        });
-      }
-    }
-  }
-
-  /**
-   * Validate template options against available templates
-   */
-  async validateOptions(options: TemplateOptions): Promise<void> {
-    const availableTemplates = await this.getAvailableTemplates();
-
-    if (
-      options.architecture &&
-      !availableTemplates.architecture.includes(options.architecture)
-    ) {
-      throw new Error(
-        `Invalid architecture template: ${options.architecture}. Valid options: ${availableTemplates.architecture.join(', ')}`
-      );
-    }
-
-    if (
-      options.requirements &&
-      !availableTemplates.requirements.includes(options.requirements)
-    ) {
-      throw new Error(
-        `Invalid requirements template: ${options.requirements}. Valid options: ${availableTemplates.requirements.join(', ')}`
-      );
-    }
-
-    if (options.design && !availableTemplates.design.includes(options.design)) {
-      throw new Error(
-        `Invalid design template: ${options.design}. Valid options: ${availableTemplates.design.join(', ')}`
-      );
-    }
-  }
-
-  /**
-   * Get available templates for each type by scanning the file system
-   */
-  async getAvailableTemplates(): Promise<{
-    architecture: string[];
-    requirements: string[];
-    design: string[];
-  }> {
-    const result = {
-      architecture: [] as string[],
-      requirements: [] as string[],
-      design: [] as string[],
-    };
-
-    try {
-      // Scan each template type directory
-      for (const [type, templates] of Object.entries(result)) {
-        const typePath = join(this.templatesPath, type);
-
-        try {
-          const entries = await readdir(typePath, { withFileTypes: true });
-
-          for (const entry of entries) {
-            if (entry.isDirectory()) {
-              // Directory-based template (like arc42)
-              templates.push(entry.name);
-            } else if (entry.isFile() && entry.name.endsWith('.md')) {
-              // File-based template (like freestyle.md)
-              const templateName = entry.name.replace('.md', '');
-              templates.push(templateName);
-            }
-          }
-
-          // Sort templates for consistent ordering
-          templates.sort();
-        } catch (error) {
-          logger.warn(`Failed to scan templates for type: ${type}`, {
-            typePath,
-            error: error instanceof Error ? error.message : String(error),
-          });
-        }
-      }
-
-      logger.debug('Discovered available templates', result);
-      return result;
-    } catch (error) {
-      logger.error('Failed to discover templates', error as Error);
-      // Return empty arrays if discovery fails
-      return result;
-    }
-  }
-}

package/src/transition-engine.ts

@@ -1,386 +0,0 @@
-/**
- * Transition Engine
- *
- * Manages the development state machine and determines appropriate phase transitions.
- * Analyzes conversation context and user input to make intelligent phase decisions.
- */
-
-import { createLogger } from './logger.js';
-import { StateMachineLoader } from './state-machine-loader.js';
-import { WorkflowManager } from './workflow-manager.js';
-import type { ConversationState } from './types.js';
-
-const logger = createLogger('TransitionEngine');
-
-export interface TransitionContext {
-  currentPhase: string;
-  projectPath: string;
-  conversationId: string;
-  userInput?: string;
-  context?: string;
-  conversationSummary?: string;
-  recentMessages?: Array<{ role: string; content: string }>;
-}
-
-export interface TransitionResult {
-  newPhase: string;
-  instructions: string;
-  transitionReason: string;
-  isModeled: boolean;
-}
-
-export class TransitionEngine {
-  private stateMachineLoader: StateMachineLoader;
-  private workflowManager: WorkflowManager;
-  private conversationManager?: {
-    hasInteractions: (conversationId: string) => Promise<boolean>;
-    getConversationState: (
-      conversationId: string
-    ) => Promise<ConversationState | null>;
-  };
-
-  constructor(projectPath: string) {
-    this.stateMachineLoader = new StateMachineLoader();
-    this.workflowManager = new WorkflowManager();
-
-    logger.info('TransitionEngine initialized', { projectPath });
-  }
-
-  /**
-   * Set the conversation manager (dependency injection)
-   */
-  setConversationManager(conversationManager: {
-    hasInteractions: (conversationId: string) => Promise<boolean>;
-    getConversationState: (
-      conversationId: string
-    ) => Promise<ConversationState | null>;
-  }) {
-    this.conversationManager = conversationManager;
-  }
-
-  /**
-   * Get the loaded state machine for the current project
-   */
-  getStateMachine(projectPath: string, workflowName?: string) {
-    // Use WorkflowManager to load the appropriate workflow
-    return this.workflowManager.loadWorkflowForProject(
-      projectPath,
-      workflowName
-    );
-  }
-
-  /**
-   * Check if this is the first call from initial state based on database interactions
-   */
-  private async isFirstCallFromInitialState(
-    context: TransitionContext
-  ): Promise<boolean> {
-    // Get workflow name from conversation state
-    const conversationState =
-      await this.conversationManager?.getConversationState(
-        context.conversationId
-      );
-    const workflowName = conversationState?.workflowName;
-
-    const stateMachine = this.workflowManager.loadWorkflowForProject(
-      context.projectPath,
-      workflowName
-    );
-    const isInitialState = context.currentPhase === stateMachine.initial_state;
-
-    if (!isInitialState) return false;
-
-    // Check database for any previous interactions in this conversation
-    if (!this.conversationManager) {
-      logger.warn('ConversationManager not set, assuming first call');
-      return true;
-    }
-
-    const hasInteractions = await this.conversationManager.hasInteractions(
-      context.conversationId
-    );
-
-    logger.debug('Checking first call from initial state', {
-      isInitialState,
-      hasInteractions,
-      conversationId: context.conversationId,
-      currentPhase: context.currentPhase,
-    });
-
-    return !hasInteractions;
-  }
-
-  /**
-   * Generate instructions for defining phase entrance criteria
-   */
-  private async generateCriteriaDefinitionInstructions(
-    projectPath: string,
-    conversationId: string
-  ): Promise<string> {
-    // Get workflow name from conversation state
-    const conversationState =
-      await this.conversationManager?.getConversationState(conversationId);
-    const workflowName = conversationState?.workflowName;
-
-    const stateMachine = this.workflowManager.loadWorkflowForProject(
-      projectPath,
-      workflowName
-    );
-    const phases = Object.keys(stateMachine.states);
-
-    let instructions = `Welcome to ${stateMachine.name}!
-
-Before we begin development, let's establish clear entrance criteria for each phase. This will help us make informed decisions about when to transition between phases throughout the development process.
-
-Please update the plan file with a "Phase Entrance Criteria" section that defines specific, measurable criteria for entering each phase:
-
-## Phase Entrance Criteria
-
-`;
-
-    // Generate criteria template for each phase (except initial state)
-    for (const phase of phases) {
-      if (phase === stateMachine.initial_state) continue; // Skip initial state
-
-      const phaseDefinition = stateMachine.states[phase];
-      const capitalizedPhase = this.capitalizePhase(phase);
-
-      instructions += `### ${capitalizedPhase} Phase
-*${phaseDefinition.description}*
-
-**Enter when:**
-- [ ] [Define specific criteria for entering ${phase} phase]
-- [ ] [Add measurable conditions that must be met]
-- [ ] [Include any deliverables or milestones required]
-
-`;
-    }
-
-    instructions += `
-Once you've defined these criteria, we can begin development. Throughout the process, consult these criteria when considering phase transitions.
-
-**Remember**: These criteria should be specific and measurable so we can clearly determine when each phase is ready to begin.`;
-
-    return instructions;
-  }
-
-  /**
-   * Get phase-specific instructions for continuing work in current phase
-   */
-  private async getContinuePhaseInstructions(
-    phase: string,
-    projectPath: string,
-    conversationId: string
-  ): Promise<string> {
-    // Get workflow name from conversation state
-    const conversationState =
-      await this.conversationManager?.getConversationState(conversationId);
-    const workflowName = conversationState?.workflowName;
-
-    const stateMachine = this.workflowManager.loadWorkflowForProject(
-      projectPath,
-      workflowName
-    );
-
-    const stateDefinition = stateMachine.states[phase];
-    if (!stateDefinition) {
-      logger.error('Unknown phase', new Error(`Unknown phase: ${phase}`));
-      throw new Error(`Unknown phase: ${phase}`);
-    }
-
-    const continueTransition = stateDefinition.transitions.find(
-      t => t.to === phase
-    );
-
-    if (continueTransition) {
-      // Use the transition instructions if available, otherwise use default + additional
-      if (continueTransition.instructions) {
-        return continueTransition.instructions;
-      } else {
-        let composedInstructions = stateDefinition.default_instructions;
-        if (continueTransition.additional_instructions) {
-          composedInstructions = `${composedInstructions}\n\n**Additional Context:**\n${continueTransition.additional_instructions}`;
-        }
-        return composedInstructions;
-      }
-    }
-
-    // Fall back to default instructions for the phase
-    return stateDefinition.default_instructions;
-  }
-  /**
-   * Get the first development phase from the state machine
-   */
-  private async getFirstDevelopmentPhase(
-    projectPath: string,
-    conversationId: string
-  ): Promise<string> {
-    // Get workflow name from conversation state
-    const conversationState =
-      await this.conversationManager?.getConversationState(conversationId);
-    const workflowName = conversationState?.workflowName;
-
-    const stateMachine = this.workflowManager.loadWorkflowForProject(
-      projectPath,
-      workflowName
-    );
-    const initialState = stateMachine.initial_state;
-
-    // The first development phase IS the initial state - we should stay there
-    // Don't automatically transition to the first transition target
-    return initialState;
-  }
-
-  /**
-   * Analyze context and determine appropriate phase transition
-   */
-  async analyzePhaseTransition(
-    context: TransitionContext
-  ): Promise<TransitionResult> {
-    const {
-      currentPhase,
-      projectPath,
-      conversationId,
-      userInput,
-      context: additionalContext,
-      conversationSummary,
-    } = context;
-
-    // Load the appropriate workflow for this project/conversation
-
-    logger.debug('Analyzing phase transition', {
-      currentPhase,
-      projectPath,
-      hasUserInput: !!userInput,
-      hasContext: !!additionalContext,
-      hasSummary: !!conversationSummary,
-      userInput: userInput
-        ? userInput.substring(0, 50) + (userInput.length > 50 ? '...' : '')
-        : undefined,
-    });
-
-    // Check if this is the first call from initial state - transition to first development phase
-    if (await this.isFirstCallFromInitialState(context)) {
-      const firstDevelopmentPhase = await this.getFirstDevelopmentPhase(
-        projectPath,
-        conversationId
-      );
-
-      logger.info(
-        'First call from initial state - transitioning to first development phase with criteria',
-        {
-          currentPhase,
-          firstDevelopmentPhase,
-          projectPath,
-        }
-      );
-
-      // Combine criteria definition with first phase instructions
-      const criteriaInstructions =
-        await this.generateCriteriaDefinitionInstructions(
-          projectPath,
-          conversationId
-        );
-      const phaseInstructions = await this.getContinuePhaseInstructions(
-        firstDevelopmentPhase,
-        projectPath,
-        conversationId
-      );
-
-      return {
-        newPhase: firstDevelopmentPhase, // Transition to first development phase
-        instructions: criteriaInstructions + '\n\n---\n\n' + phaseInstructions,
-        transitionReason:
-          'Starting development - defining criteria and beginning first phase',
-        isModeled: true,
-      };
-    }
-
-    // For all other cases, stay in current phase and let LLM decide based on plan file criteria
-    // The LLM will consult the entrance criteria in the plan file and use proceed_to_phase when ready
-    const continueInstructions = await this.getContinuePhaseInstructions(
-      currentPhase,
-      projectPath,
-      conversationId
-    );
-
-    logger.debug(
-      'Continuing in current phase - LLM will evaluate transition criteria',
-      {
-        currentPhase,
-        projectPath,
-      }
-    );
-
-    return {
-      newPhase: currentPhase,
-      instructions: continueInstructions,
-      transitionReason:
-        'Continue current phase - LLM will evaluate transition criteria from plan file',
-      isModeled: false,
-    };
-  }
-
-  /**
-   * Handle explicit phase transition request
-   */
-  handleExplicitTransition(
-    currentPhase: string,
-    targetPhase: string,
-    projectPath: string,
-    reason?: string,
-    workflowName?: string
-  ): TransitionResult {
-    // Load the appropriate state machine for this project/workflow
-    const stateMachine = this.getStateMachine(projectPath, workflowName);
-
-    logger.debug('Handling explicit phase transition', {
-      currentPhase,
-      targetPhase,
-      projectPath,
-      workflowName,
-      reason,
-    });
-
-    // Validate that the target phase exists in the state machine
-    if (!stateMachine.states[targetPhase]) {
-      const validPhases = Object.keys(stateMachine.states);
-      const errorMsg = `Invalid target phase: "${targetPhase}". Valid phases are: ${validPhases.join(', ')}`;
-      logger.error('Invalid target phase', new Error(errorMsg));
-      throw new Error(errorMsg);
-    }
-
-    // Get default instructions from the target state
-    const targetState = stateMachine.states[targetPhase];
-    const instructions = targetState.default_instructions;
-    const transitionInfo = {
-      instructions: instructions,
-      transitionReason: reason || `Moving to ${targetPhase}`,
-      isModeled: false, // Direct phase transitions are not modeled
-    };
-
-    logger.info('Explicit phase transition processed', {
-      fromPhase: currentPhase,
-      toPhase: targetPhase,
-      reason: transitionInfo.transitionReason,
-      isModeled: transitionInfo.isModeled,
-    });
-
-    return {
-      newPhase: targetPhase,
-      instructions: transitionInfo.instructions,
-      transitionReason: reason || transitionInfo.transitionReason,
-      isModeled: transitionInfo.isModeled,
-    };
-  }
-
-  /**
-   * Capitalize phase name for display
-   */
-  private capitalizePhase(phase: string): string {
-    return phase
-      .split('_')
-      .map(word => word.charAt(0).toUpperCase() + word.slice(1))
-      .join(' ');
-  }
-}