@codemcp/workflows-core 3.1.16

package/src/file-detection-manager.ts

@@ -0,0 +1,302 @@
+/**
+ * File Detection Manager
+ *
+ * Handles pattern-based file discovery and suggestions for existing documentation files.
+ * Supports auto-detection of common documentation patterns in projects.
+ */
+
+import { readdir, access } from 'node:fs/promises';
+import { join, basename } from 'node:path';
+import { createLogger } from './logger.js';
+import { PathValidationUtils } from './path-validation-utils.js';
+
+const logger = createLogger('FileDetectionManager');
+
+export interface DetectedFile {
+  path: string;
+  relativePath: string;
+  type: 'architecture' | 'requirements' | 'design';
+  confidence: 'high' | 'medium' | 'low';
+}
+
+export interface FileDetectionResult {
+  architecture: DetectedFile[];
+  requirements: DetectedFile[];
+  design: DetectedFile[];
+}
+
+export class FileDetectionManager {
+  private projectPath: string;
+
+  constructor(projectPath: string) {
+    this.projectPath = projectPath;
+  }
+
+  /**
+   * Detect existing documentation files in the project
+   */
+  async detectDocumentationFiles(): Promise<FileDetectionResult> {
+    logger.debug('Starting documentation file detection', {
+      projectPath: this.projectPath,
+    });
+
+    const searchLocations = this.getSearchLocations();
+    const patterns = PathValidationUtils.getCommonDocumentationPatterns();
+
+    const result: FileDetectionResult = {
+      architecture: [],
+      requirements: [],
+      design: [],
+    };
+
+    // Search in each location
+    for (const location of searchLocations) {
+      try {
+        await access(location);
+        const files = await this.scanLocation(location);
+
+        // Match files against patterns
+        for (const file of files) {
+          const matches = this.matchFileToPatterns(file, patterns);
+
+          for (const match of matches) {
+            result[match.type].push({
+              path: file.path,
+              relativePath: file.relativePath,
+              type: match.type,
+              confidence: match.confidence,
+            });
+          }
+        }
+      } catch (error) {
+        logger.debug('Search location not accessible', {
+          location,
+          error: error instanceof Error ? error.message : 'Unknown error',
+        });
+      }
+    }
+
+    // Sort by confidence and remove duplicates
+    result.architecture = this.sortAndDeduplicate(result.architecture);
+    result.requirements = this.sortAndDeduplicate(result.requirements);
+    result.design = this.sortAndDeduplicate(result.design);
+
+    logger.info('Documentation file detection completed', {
+      found: {
+        architecture: result.architecture.length,
+        requirements: result.requirements.length,
+        design: result.design.length,
+      },
+    });
+
+    return result;
+  }
+
+  /**
+   * Get search locations for documentation files
+   */
+  private getSearchLocations(): string[] {
+    return [
+      this.projectPath, // Project root
+      join(this.projectPath, 'docs'), // docs/ folder
+      join(this.projectPath, 'doc'), // doc/ folder
+      join(this.projectPath, '.vibe', 'docs'), // .vibe/docs/ folder
+      join(this.projectPath, 'documentation'), // documentation/ folder
+    ];
+  }
+
+  /**
+   * Scan a location for files
+   */
+  private async scanLocation(
+    location: string
+  ): Promise<Array<{ path: string; relativePath: string }>> {
+    try {
+      const entries = await readdir(location, { withFileTypes: true });
+      const files: Array<{ path: string; relativePath: string }> = [];
+
+      for (const entry of entries) {
+        if (entry.isFile()) {
+          const fullPath = join(location, entry.name);
+          const relativePath = fullPath.replace(this.projectPath + '/', '');
+
+          files.push({
+            path: fullPath,
+            relativePath,
+          });
+        }
+      }
+
+      return files;
+    } catch (error) {
+      logger.debug('Failed to scan location', {
+        location,
+        error: error instanceof Error ? error.message : 'Unknown error',
+      });
+      return [];
+    }
+  }
+
+  /**
+   * Match a file against documentation patterns
+   */
+  private matchFileToPatterns(
+    file: { path: string; relativePath: string },
+    patterns: ReturnType<
+      typeof PathValidationUtils.getCommonDocumentationPatterns
+    >
+  ): Array<{
+    type: 'architecture' | 'requirements' | 'design';
+    confidence: 'high' | 'medium' | 'low';
+  }> {
+    const fileName = basename(file.path).toLowerCase();
+    const relativePath = file.relativePath.toLowerCase();
+    const matches: Array<{
+      type: 'architecture' | 'requirements' | 'design';
+      confidence: 'high' | 'medium' | 'low';
+    }> = [];
+
+    // Check architecture patterns
+    if (this.matchesPatterns(fileName, relativePath, patterns.architecture)) {
+      const confidence = this.getConfidence(fileName, 'architecture');
+      matches.push({ type: 'architecture', confidence });
+    }
+
+    // Check requirements patterns
+    if (this.matchesPatterns(fileName, relativePath, patterns.requirements)) {
+      const confidence = this.getConfidence(fileName, 'requirements');
+      matches.push({ type: 'requirements', confidence });
+    }
+
+    // Check design patterns
+    if (this.matchesPatterns(fileName, relativePath, patterns.design)) {
+      const confidence = this.getConfidence(fileName, 'design');
+      matches.push({ type: 'design', confidence });
+    }
+
+    return matches;
+  }
+
+  /**
+   * Check if file matches any of the patterns
+   */
+  private matchesPatterns(
+    fileName: string,
+    relativePath: string,
+    patterns: string[]
+  ): boolean {
+    return patterns.some(pattern => {
+      const normalizedPattern = pattern.toLowerCase();
+
+      // Exact filename match
+      if (fileName === normalizedPattern) {
+        return true;
+      }
+
+      // Relative path match
+      if (relativePath === normalizedPattern) {
+        return true;
+      }
+
+      // Pattern matching with wildcards
+      if (normalizedPattern.includes('*')) {
+        const regex = new RegExp(normalizedPattern.replace(/\*/g, '.*'));
+        return regex.test(fileName) || regex.test(relativePath);
+      }
+
+      return false;
+    });
+  }
+
+  /**
+   * Determine confidence level for a match
+   */
+  private getConfidence(
+    fileName: string,
+    type: string
+  ): 'high' | 'medium' | 'low' {
+    // High confidence for exact type matches
+    if (fileName.includes(type.toLowerCase())) {
+      return 'high';
+    }
+
+    // Medium confidence for README files (could contain any type)
+    if (fileName.includes('readme')) {
+      return 'medium';
+    }
+
+    // Low confidence for other matches
+    return 'low';
+  }
+
+  /**
+   * Sort by confidence and remove duplicates
+   */
+  private sortAndDeduplicate(files: DetectedFile[]): DetectedFile[] {
+    // Remove duplicates by path
+    const unique = files.filter(
+      (file, index, array) =>
+        array.findIndex(f => f.path === file.path) === index
+    );
+
+    // Sort by confidence (high first) and then by path length (shorter first)
+    return unique.sort((a, b) => {
+      const confidenceOrder = { high: 0, medium: 1, low: 2 };
+      const confidenceDiff =
+        confidenceOrder[a.confidence] - confidenceOrder[b.confidence];
+
+      if (confidenceDiff !== 0) {
+        return confidenceDiff;
+      }
+
+      return a.relativePath.length - b.relativePath.length;
+    });
+  }
+
+  /**
+   * Format file suggestions for LLM responses
+   */
+  formatSuggestions(detectionResult: FileDetectionResult): string {
+    const suggestions: string[] = [];
+
+    if (detectionResult.architecture.length > 0) {
+      suggestions.push(`**Architecture files found:**`);
+      for (const file of detectionResult.architecture.slice(0, 3)) {
+        suggestions.push(
+          `  - ${file.relativePath} (${file.confidence} confidence)`
+        );
+      }
+    }
+
+    if (detectionResult.requirements.length > 0) {
+      suggestions.push(`**Requirements files found:**`);
+      for (const file of detectionResult.requirements.slice(0, 3)) {
+        suggestions.push(
+          `  - ${file.relativePath} (${file.confidence} confidence)`
+        );
+      }
+    }
+
+    if (detectionResult.design.length > 0) {
+      suggestions.push(`**Design files found:**`);
+      for (const file of detectionResult.design.slice(0, 3)) {
+        suggestions.push(
+          `  - ${file.relativePath} (${file.confidence} confidence)`
+        );
+      }
+    }
+
+    if (suggestions.length === 0) {
+      return 'No existing documentation files detected.';
+    }
+
+    return [
+      'Existing documentation files detected:',
+      '',
+      ...suggestions,
+      '',
+      'You can use these files with `setup_project_docs` by providing the file paths instead of template names.',
+      'Example: `setup_project_docs({ architecture: "README.md", requirements: "docs/requirements.md", design: "freestyle" })`',
+    ].join('\n');
+  }
+}

package/src/git-manager.ts

@@ -0,0 +1,64 @@
+import { execSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { createLogger } from './logger.js';
+
+const logger = createLogger('GitManager');
+
+export class GitManager {
+  /**
+   * Check if a directory is a git repository
+   */
+  static isGitRepository(projectPath: string): boolean {
+    return existsSync(`${projectPath}/.git`);
+  }
+
+  /**
+   * Get the current git branch for a project
+   */
+  static getCurrentBranch(projectPath: string): string {
+    try {
+      if (!this.isGitRepository(projectPath)) {
+        logger.debug('Not a git repository, using "default" as branch name', {
+          projectPath,
+        });
+        return 'default';
+      }
+
+      const branch = execSync('git rev-parse --abbrev-ref HEAD', {
+        cwd: projectPath,
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+      }).trim();
+
+      logger.debug('Detected git branch', { projectPath, branch });
+      return branch;
+    } catch (_error) {
+      logger.debug('Failed to get git branch, using "default" as branch name', {
+        projectPath,
+      });
+      return 'default';
+    }
+  }
+
+  /**
+   * Get the current HEAD commit hash (for tracking start of development)
+   */
+  static getCurrentCommitHash(projectPath: string): string | null {
+    try {
+      if (!this.isGitRepository(projectPath)) {
+        return null;
+      }
+
+      const hash = execSync('git rev-parse HEAD', {
+        cwd: projectPath,
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+      }).trim();
+
+      return hash;
+    } catch (error) {
+      logger.debug('Failed to get current commit hash', { projectPath, error });
+      return null;
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+// Core types and interfaces
+export * from './types.js';
+export * from './state-machine-types.js';
+
+// State machine and workflow management
+export * from './state-machine.js';
+export * from './state-machine-loader.js';
+export * from './workflow-manager.js';
+export * from './transition-engine.js';
+
+// Data management
+export * from './database.js';
+export * from './conversation-manager.js';
+
+// Project and plan management
+export * from './plan-manager.js';
+export * from './template-manager.js';
+export * from './project-docs-manager.js';
+export * from './file-detection-manager.js';
+export * from './config-manager.js';
+export * from './git-manager.js';
+
+// Utilities and generators
+export * from './logger.js';
+export * from './interaction-logger.js';
+export * from './instruction-generator.js';
+export * from './system-prompt-generator.js';
+export * from './path-validation-utils.js';

package/src/instruction-generator.ts

@@ -0,0 +1,210 @@
+/**
+ * Instruction Generator
+ *
+ * Creates phase-specific guidance for the LLM based on current conversation state.
+ * Customizes instructions based on project context and development phase.
+ * Supports custom state machine definitions for dynamic instruction generation.
+ * Handles variable substitution for project artifact references.
+ */
+
+import type { ConversationContext } from './types.js';
+import { PlanManager } from './plan-manager.js';
+import { ProjectDocsManager } from './project-docs-manager.js';
+import type { YamlStateMachine } from './state-machine-types.js';
+
+export interface InstructionContext {
+  phase: string;
+  conversationContext: ConversationContext;
+  transitionReason: string;
+  isModeled: boolean;
+  planFileExists: boolean;
+}
+
+export interface GeneratedInstructions {
+  instructions: string;
+  planFileGuidance: string;
+  metadata: {
+    phase: string;
+    planFilePath: string;
+    transitionReason: string;
+    isModeled: boolean;
+  };
+}
+
+export class InstructionGenerator {
+  private planManager: PlanManager;
+  private projectDocsManager: ProjectDocsManager;
+  private stateMachine: YamlStateMachine | null = null;
+
+  constructor(planManager: PlanManager) {
+    this.planManager = planManager;
+    this.projectDocsManager = new ProjectDocsManager();
+  }
+
+  /**
+   * Set the state machine definition for dynamic instruction generation
+   */
+  setStateMachine(stateMachine: YamlStateMachine): void {
+    this.stateMachine = stateMachine;
+  }
+
+  /**
+   * Generate comprehensive instructions for the LLM
+   */
+  async generateInstructions(
+    baseInstructions: string,
+    context: InstructionContext
+  ): Promise<GeneratedInstructions> {
+    // Apply variable substitution to base instructions
+    const substitutedInstructions = this.applyVariableSubstitution(
+      baseInstructions,
+      context.conversationContext.projectPath
+    );
+
+    // Get plan file guidance
+    const planFileGuidance = this.planManager.generatePlanFileGuidance(
+      context.phase
+    );
+
+    // Enhance base instructions with context-specific guidance
+    const enhancedInstructions = await this.enhanceInstructions(
+      substitutedInstructions,
+      context,
+      planFileGuidance
+    );
+
+    return {
+      instructions: enhancedInstructions,
+      planFileGuidance,
+      metadata: {
+        phase: context.phase,
+        planFilePath: context.conversationContext.planFilePath,
+        transitionReason: context.transitionReason,
+        isModeled: context.isModeled,
+      },
+    };
+  }
+
+  /**
+   * Apply variable substitution to instructions
+   * Replaces project artifact variables with actual file paths
+   */
+  private applyVariableSubstitution(
+    instructions: string,
+    projectPath: string
+  ): string {
+    const substitutions =
+      this.projectDocsManager.getVariableSubstitutions(projectPath);
+
+    let result = instructions;
+    for (const [variable, value] of Object.entries(substitutions)) {
+      // Use global replace to handle multiple occurrences
+      result = result.replace(
+        new RegExp(this.escapeRegExp(variable), 'g'),
+        value
+      );
+    }
+
+    return result;
+  }
+
+  /**
+   * Escape special regex characters in variable names
+   */
+  private escapeRegExp(string: string): string {
+    return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  }
+
+  /**
+   * Enhance base instructions with context-specific information
+   */
+  private async enhanceInstructions(
+    baseInstructions: string,
+    context: InstructionContext,
+    _planFileGuidance: string
+  ): Promise<string> {
+    const {
+      phase,
+      conversationContext,
+      transitionReason,
+      isModeled,
+      planFileExists,
+    } = context;
+
+    // Build plan-file-referential instructions
+    let enhanced = `Check your plan file at \`${conversationContext.planFilePath}\` and focus on the "${this.capitalizePhase(phase)}" section.
+
+${baseInstructions}
+
+**Plan File Guidance:**
+- Work on the tasks listed in the ${this.capitalizePhase(phase)} section
+- Mark completed tasks with [x] as you finish them
+- Add new tasks as they are identified during your work with the user
+- Update the "Key Decisions" section with important choices made
+- Add relevant notes to help maintain context`;
+
+    // Add project context
+    enhanced += `\n\n**Project Context:**
+- Project: ${conversationContext.projectPath}
+- Branch: ${conversationContext.gitBranch}
+- Current Phase: ${phase}`;
+
+    // Add transition context if this is a modeled transition
+    if (isModeled && transitionReason) {
+      enhanced += `\n\n**Phase Context:**
+- ${transitionReason}`;
+    }
+
+    // Add plan file creation note if needed
+    if (!planFileExists) {
+      enhanced +=
+        '\n\n**Note**: Plan file will be created when you first update it.';
+    }
+
+    return enhanced;
+  }
+
+  /**
+   * Get phase-specific contextual information based on state machine
+   */
+  private getPhaseSpecificContext(phase: string): string {
+    if (this.stateMachine) {
+      const phaseDefinition = this.stateMachine.states[phase];
+      if (phaseDefinition) {
+        return `**Context**: ${phaseDefinition.description}`;
+      }
+    }
+
+    throw new Error(
+      `State machine not set or unknown phase: ${phase}. This should not happen as state machine is always loaded.`
+    );
+  }
+
+  /**
+   * Get default phase context for standard phases
+  /**
+   * Get phase-specific reminders and best practices based on state machine
+   */
+  private getPhaseReminders(phase: string): string {
+    if (this.stateMachine) {
+      const phaseDefinition = this.stateMachine.states[phase];
+      if (phaseDefinition) {
+        return `**Remember**: \n- Focus on: ${phaseDefinition.description}\n- Update plan file with ${phase} progress\n- Mark completed tasks with [x]\n- Stay focused on current phase objectives`;
+      }
+    }
+
+    throw new Error(
+      `State machine not set or unknown phase: ${phase}. This should not happen as state machine is always loaded.`
+    );
+  }
+
+  /**
+   * Capitalize phase name for display
+   */
+  private capitalizePhase(phase: string): string {
+    return phase
+      .split('_')
+      .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+      .join(' ');
+  }
+}

package/src/interaction-logger.ts

@@ -0,0 +1,109 @@
+/**
+ * Interaction Logger module
+ *
+ * Handles logging of tool interactions to the database for auditing and debugging.
+ */
+
+import { Database } from './database.js';
+import { createLogger } from './logger.js';
+
+import type { InteractionLog } from './types.js';
+
+const logger = createLogger('InteractionLogger');
+
+/**
+ * Handles logging of tool interactions to the database
+ */
+export class InteractionLogger {
+  private database: Database;
+
+  /**
+   * Create a new InteractionLogger
+   *
+   * @param database - Database instance to use for logging
+   */
+  constructor(database: Database) {
+    this.database = database;
+    logger.debug('InteractionLogger initialized');
+  }
+
+  /**
+   * Log an interaction with a tool
+   *
+   * @param conversationId - ID of the conversation
+   * @param toolName - Name of the tool that was called
+   * @param inputParams - Input parameters to the tool (will be stringified)
+   * @param responseData - Response data from the tool (will be stringified)
+   * @param currentPhase - Current development phase
+   * @returns Promise that resolves when the log is saved
+   */
+  async logInteraction(
+    conversationId: string,
+    toolName: string,
+    inputParams: unknown,
+    responseData: unknown,
+    currentPhase: string
+  ): Promise<void> {
+    logger.debug('Logging interaction', {
+      conversationId,
+      toolName,
+      currentPhase,
+    });
+
+    try {
+      const timestamp = new Date().toISOString();
+
+      const log: InteractionLog = {
+        conversationId,
+        toolName,
+        inputParams: JSON.stringify(inputParams),
+        responseData: JSON.stringify(responseData),
+        currentPhase,
+        timestamp,
+      };
+
+      await this.database.logInteraction(log);
+
+      logger.info('Interaction logged successfully', {
+        conversationId,
+        toolName,
+        timestamp,
+      });
+    } catch (error) {
+      logger.error('Failed to log interaction', error as Error, {
+        conversationId,
+        toolName,
+      });
+      // Don't throw the error - logging should not break the main flow
+    }
+  }
+
+  /**
+   * Get all interactions for a specific conversation
+   *
+   * @param conversationId - ID of the conversation to get logs for
+   * @returns Promise that resolves to an array of interaction logs
+   */
+  async getInteractionsByConversationId(
+    conversationId: string
+  ): Promise<InteractionLog[]> {
+    logger.debug('Getting interactions by conversation ID', { conversationId });
+
+    try {
+      const logs =
+        await this.database.getInteractionsByConversationId(conversationId);
+
+      logger.info('Retrieved interaction logs', {
+        conversationId,
+        count: logs.length,
+      });
+
+      return logs;
+    } catch (error) {
+      logger.error('Failed to get interaction logs', error as Error, {
+        conversationId,
+      });
+      throw error;
+    }
+  }
+}