@codemcp/workflows 5.0.1 → 5.1.1

package/src/plugin-system/commit-plugin.ts

@@ -1,252 +0,0 @@
-/**
- * CommitPlugin Implementation
- *
- * Plugin that handles automatic git commits based on COMMIT_BEHAVIOR environment variable.
- * Supports step, phase, and end commit modes with configurable message templates.
- */
-
-import type {
-  IPlugin,
-  PluginHooks,
-  PluginHookContext,
-  StartDevelopmentArgs,
-  StartDevelopmentResult,
-} from './plugin-interfaces.js';
-import { GitManager, createLogger } from '@codemcp/workflows-core';
-
-const logger = createLogger('CommitPlugin');
-
-/**
- * CommitPlugin class implementing the IPlugin interface
- *
- * Activation: Only when process.env.COMMIT_BEHAVIOR is set to valid value
- * Priority: Sequence 50 (before BeadsPlugin at 100)
- */
-export class CommitPlugin implements IPlugin {
-  private projectPath: string;
-  private initialCommitHash?: string;
-
-  constructor(options: { projectPath: string }) {
-    this.projectPath = options.projectPath;
-    logger.debug('CommitPlugin initialized', { projectPath: this.projectPath });
-  }
-
-  getName(): string {
-    return 'CommitPlugin';
-  }
-
-  getSequence(): number {
-    return 50; // Before BeadsPlugin (100)
-  }
-
-  isEnabled(): boolean {
-    const behavior = process.env.COMMIT_BEHAVIOR;
-    const enabled =
-      behavior && ['step', 'phase', 'end', 'none'].includes(behavior);
-    logger.debug('CommitPlugin enablement check', {
-      COMMIT_BEHAVIOR: behavior,
-      enabled: !!enabled,
-    });
-    return !!enabled;
-  }
-
-  getHooks(): PluginHooks {
-    return {
-      afterStartDevelopment: this.handleAfterStartDevelopment.bind(this),
-      beforePhaseTransition: this.handleBeforePhaseTransition.bind(this),
-      afterPlanFileCreated: this.handleAfterPlanFileCreated.bind(this),
-    };
-  }
-
-  /**
-   * Handle afterStartDevelopment hook
-   * Store initial commit hash for potential squashing later
-   */
-  private async handleAfterStartDevelopment(
-    context: PluginHookContext,
-    _args: StartDevelopmentArgs,
-    _result: StartDevelopmentResult
-  ): Promise<void> {
-    logger.info('CommitPlugin: Setting up commit behavior', {
-      conversationId: context.conversationId,
-      behavior: process.env.COMMIT_BEHAVIOR,
-      projectPath: context.projectPath,
-    });
-
-    try {
-      if (GitManager.isGitRepository(context.projectPath)) {
-        this.initialCommitHash =
-          GitManager.getCurrentCommitHash(context.projectPath) || undefined;
-        logger.debug('CommitPlugin: Stored initial commit hash', {
-          conversationId: context.conversationId,
-          initialCommitHash: this.initialCommitHash,
-        });
-      }
-    } catch (error) {
-      logger.warn('CommitPlugin: Failed to get initial commit hash', {
-        error: error instanceof Error ? error.message : String(error),
-        conversationId: context.conversationId,
-      });
-    }
-  }
-
-  /**
-   * Handle beforePhaseTransition hook
-   * Create WIP commits for phase and step modes
-   */
-  private async handleBeforePhaseTransition(
-    context: PluginHookContext,
-    currentPhase: string,
-    targetPhase: string
-  ): Promise<void> {
-    const behavior = process.env.COMMIT_BEHAVIOR;
-
-    if (behavior !== 'phase' && behavior !== 'step') {
-      return; // Only commit on phase transitions for these modes
-    }
-
-    logger.info('CommitPlugin: Creating WIP commit before phase transition', {
-      conversationId: context.conversationId,
-      currentPhase,
-      targetPhase,
-      behavior,
-    });
-
-    try {
-      if (!GitManager.isGitRepository(context.projectPath)) {
-        logger.debug('CommitPlugin: Not a git repository, skipping commit');
-        return;
-      }
-
-      if (!GitManager.hasUncommittedChanges(context.projectPath)) {
-        logger.debug('CommitPlugin: No uncommitted changes, skipping commit');
-        return;
-      }
-
-      const message = `WIP: transition to ${targetPhase}`;
-      const success = GitManager.createCommit(message, context.projectPath);
-
-      if (success) {
-        logger.info('CommitPlugin: Created WIP commit successfully', {
-          conversationId: context.conversationId,
-          message,
-        });
-      } else {
-        logger.warn('CommitPlugin: Failed to create WIP commit', {
-          conversationId: context.conversationId,
-          message,
-        });
-      }
-    } catch (error) {
-      logger.warn('CommitPlugin: Error during phase transition commit', {
-        error: error instanceof Error ? error.message : String(error),
-        conversationId: context.conversationId,
-      });
-    }
-  }
-
-  /**
-   * Handle afterPlanFileCreated hook
-   * Add final commit task for end mode or step/phase modes with squashing
-   */
-  private async handleAfterPlanFileCreated(
-    context: PluginHookContext,
-    planFilePath: string,
-    content: string
-  ): Promise<string> {
-    const behavior = process.env.COMMIT_BEHAVIOR;
-
-    if (!behavior || behavior === 'none') {
-      return content; // No commit behavior
-    }
-
-    logger.debug('CommitPlugin: Adding final commit task to plan file', {
-      conversationId: context.conversationId,
-      behavior,
-      planFilePath,
-    });
-
-    try {
-      // Find the final phase (usually "Commit" or last phase)
-      const lines = content.split('\n');
-      let finalPhaseIndex = -1;
-
-      // Look for "## Commit" section first
-      for (let i = 0; i < lines.length; i++) {
-        if (lines[i]?.trim() === '## Commit') {
-          finalPhaseIndex = i;
-          break;
-        }
-      }
-
-      // If no Commit section, find the last ## section
-      if (finalPhaseIndex === -1) {
-        for (let i = lines.length - 1; i >= 0; i--) {
-          const line = lines[i];
-          if (
-            line?.startsWith('## ') &&
-            !line.includes('Notes') &&
-            !line.includes('Key Decisions')
-          ) {
-            finalPhaseIndex = i;
-            break;
-          }
-        }
-      }
-
-      if (finalPhaseIndex === -1) {
-        logger.warn(
-          'CommitPlugin: Could not find final phase to add commit task'
-        );
-        return content;
-      }
-
-      // Generate commit task based on behavior
-      let commitTask: string;
-      const defaultMessage =
-        process.env.COMMIT_MESSAGE_TEMPLATE ||
-        'Create a conventional commit. In the message, first summarize the intentions and key decisions from the development plan. Then, add a brief summary of the key changes and their side effects and dependencies';
-
-      if (behavior === 'end') {
-        // End mode: simple final commit
-        commitTask = `- [ ] ${defaultMessage}`;
-      } else {
-        // Step/phase mode: squash WIP commits with instructions
-        const squashInstructions = `Squash WIP commits: \`git reset --soft <first commit of this branch>. Then, ${defaultMessage}`;
-        commitTask = `- [ ] ${squashInstructions}`;
-      }
-
-      // Find the Tasks section in the final phase and add the commit task
-      let tasksIndex = -1;
-      for (let i = finalPhaseIndex; i < lines.length; i++) {
-        if (lines[i]?.trim() === '### Tasks') {
-          tasksIndex = i;
-          break;
-        }
-      }
-
-      if (tasksIndex !== -1) {
-        // Insert after ### Tasks line
-        lines.splice(tasksIndex + 1, 0, commitTask);
-      } else {
-        // Add Tasks section if it doesn't exist
-        lines.splice(finalPhaseIndex + 1, 0, '', '### Tasks', commitTask);
-      }
-
-      const updatedContent = lines.join('\n');
-      logger.info('CommitPlugin: Added final commit task to plan file', {
-        conversationId: context.conversationId,
-        behavior,
-        commitTask,
-      });
-
-      return updatedContent;
-    } catch (error) {
-      logger.warn('CommitPlugin: Failed to add commit task to plan file', {
-        error: error instanceof Error ? error.message : String(error),
-        conversationId: context.conversationId,
-      });
-      return content; // Return original content on error
-    }
-  }
-}

package/src/plugin-system/index.ts

@@ -1,20 +0,0 @@
-/**
- * Plugin system exports
- *
- * This module provides the core plugin system for extending responsible-vibe-mcp
- * functionality without if-statements in the core application.
- */
-
-// Core plugin interfaces
-export type {
-  IPlugin,
-  IPluginRegistry,
-  PluginHooks,
-  PluginHookContext,
-  StartDevelopmentArgs,
-  StartDevelopmentResult,
-  GeneratedInstructions,
-} from './plugin-interfaces.js';
-
-// Plugin registry implementation
-export { PluginRegistry } from './plugin-registry.js';

package/src/plugin-system/plugin-interfaces.ts

@@ -1,153 +0,0 @@
-/**
- * Plugin system interfaces for extending the responsible-vibe-mcp server
- *
- * Core Principle: Plugins receive only read-only context data and cannot
- * directly manipulate core server components. They extend behavior through
- * semantic lifecycle hooks only.
- */
-
-import type { YamlState } from '@codemcp/workflows-core';
-
-/**
- * Plugin interface - all plugins must implement this
- */
-export interface IPlugin {
-  /** Unique plugin name */
-  getName(): string;
-
-  /** Execution sequence (lower numbers execute first) */
-  getSequence(): number;
-
-  /** Whether plugin is enabled (typically based on environment) */
-  isEnabled(): boolean;
-
-  /** Lifecycle hooks this plugin provides */
-  getHooks(): PluginHooks;
-}
-
-/**
- * Lifecycle hooks that plugins can implement
- * All hooks receive standardized PluginHookContext as first parameter
- */
-export interface PluginHooks {
-  /** Called before development workflow starts */
-  beforeStartDevelopment?: (
-    context: PluginHookContext,
-    args: StartDevelopmentArgs
-  ) => Promise<void>;
-
-  /** Called after development workflow has started */
-  afterStartDevelopment?: (
-    context: PluginHookContext,
-    args: StartDevelopmentArgs,
-    result: StartDevelopmentResult
-  ) => Promise<void>;
-
-  /** Called after plan file is created - can modify content */
-  afterPlanFileCreated?: (
-    context: PluginHookContext,
-    planFilePath: string,
-    content: string
-  ) => Promise<string>;
-
-  /** Called before phase transition (can block by throwing) */
-  beforePhaseTransition?: (
-    context: PluginHookContext,
-    currentPhase: string,
-    targetPhase: string
-  ) => Promise<void>;
-
-  /** Called after instructions are generated - can modify them */
-  afterInstructionsGenerated?: (
-    context: PluginHookContext,
-    instructions: GeneratedInstructions
-  ) => Promise<GeneratedInstructions>;
-}
-
-/**
- * Standardized context provided to all plugin hooks
- * Contains ONLY read-only data - no server components
- */
-export interface PluginHookContext {
-  /** Current conversation ID */
-  conversationId: string;
-
-  /** Path to the plan file */
-  planFilePath: string;
-
-  /** Current development phase */
-  currentPhase: string;
-
-  /** Active workflow name */
-  workflow: string;
-
-  /** Project directory path */
-  projectPath: string;
-
-  /** Git branch name */
-  gitBranch: string;
-
-  /** Target phase (only available in phase transitions) */
-  targetPhase?: string;
-
-  /** Workflow state machine definition (read-only) - available in afterStartDevelopment */
-  stateMachine?: {
-    readonly name: string;
-    readonly description: string;
-    readonly initial_state: string;
-    readonly states: Record<string, YamlState>;
-  };
-
-  // EXPLICITLY EXCLUDED: No access to core server components like:
-  // - conversationManager (could manipulate conversations)
-  // - transitionEngine (could force transitions)
-  // - planManager (could bypass hook system)
-  // - instructionGenerator (could generate instructions outside flow)
-}
-
-/**
- * Plugin registry interface for managing and executing plugins
- */
-export interface IPluginRegistry {
-  /** Register a plugin */
-  registerPlugin(plugin: IPlugin): void;
-
-  /** Get all enabled plugins sorted by sequence */
-  getEnabledPlugins(): IPlugin[];
-
-  /** Execute a specific hook on all plugins that implement it */
-  executeHook<T extends keyof PluginHooks>(
-    hookName: T,
-    ...args: Parameters<NonNullable<PluginHooks[T]>>
-  ): Promise<unknown>;
-
-  /** Check if any plugin has a specific hook */
-  hasHook(hookName: keyof PluginHooks): boolean;
-
-  /** Get names of all registered plugins */
-  getPluginNames(): string[];
-
-  /** Clear all plugins (mainly for testing) */
-  clear(): void;
-}
-
-// Supporting interfaces for hook parameters
-
-export interface StartDevelopmentArgs {
-  workflow: string;
-  require_reviews?: boolean;
-  project_path?: string;
-}
-
-export interface StartDevelopmentResult {
-  conversationId: string;
-  planFilePath: string;
-  phase: string;
-  workflow: string;
-}
-
-export interface GeneratedInstructions {
-  instructions: string;
-  planFilePath: string;
-  phase: string;
-}

package/src/plugin-system/plugin-registry.ts

@@ -1,190 +0,0 @@
-/**
- * Core PluginRegistry implementation for managing plugins and executing lifecycle hooks
- */
-
-import type {
-  IPlugin,
-  IPluginRegistry,
-  PluginHooks,
-} from './plugin-interfaces.js';
-
-export class PluginRegistry implements IPluginRegistry {
-  private plugins: Map<string, IPlugin> = new Map();
-
-  /**
-   * Register a plugin if it's enabled
-   */
-  registerPlugin(plugin: IPlugin): void {
-    if (!plugin.isEnabled()) {
-      return;
-    }
-
-    const name = plugin.getName();
-    if (this.plugins.has(name)) {
-      throw new Error(`Plugin with name '${name}' is already registered`);
-    }
-
-    this.plugins.set(name, plugin);
-  }
-
-  /**
-   * Get all enabled plugins sorted by execution sequence
-   */
-  getEnabledPlugins(): IPlugin[] {
-    return Array.from(this.plugins.values())
-      .filter(plugin => plugin.isEnabled())
-      .sort((a, b) => a.getSequence() - b.getSequence());
-  }
-
-  /**
-   * Execute a specific hook on all plugins that implement it
-   * Plugins are executed in sequence order
-   *
-   * Error Handling Strategy:
-   * - Validation hooks (beforePhaseTransition): Always re-throw to block invalid transitions
-   * - Critical startup hooks: Re-throw to fail fast and show critical errors
-   * - Non-critical hooks: Log error and continue execution to enable graceful degradation
-   * - Multiple plugins: If one plugin fails on non-critical hook, continue with next plugin
-   */
-  async executeHook<T extends keyof PluginHooks>(
-    hookName: T,
-    ...args: Parameters<NonNullable<PluginHooks[T]>>
-  ): Promise<unknown> {
-    const enabledPlugins = this.getEnabledPlugins();
-    let result: unknown = undefined;
-
-    for (const plugin of enabledPlugins) {
-      const hooks = plugin.getHooks();
-      const hook = hooks[hookName];
-
-      if (hook) {
-        try {
-          // Type-safe hook execution using dispatch pattern
-          result = await this.executeTypedHook(hookName, hook, args, result);
-        } catch (error) {
-          const pluginName = plugin.getName();
-          const errorMessage =
-            error instanceof Error ? error.message : String(error);
-
-          // Validation hooks (beforePhaseTransition) should ALWAYS re-throw
-          // These are intentional blocking errors, not graceful degradation
-          if (hookName === 'beforePhaseTransition') {
-            console.error(
-              `Plugin '${pluginName}' validation failed for hook '${hookName}':`,
-              errorMessage
-            );
-            throw error;
-          }
-
-          // For non-critical hooks, log the error but continue execution
-          // This enables graceful degradation: the app continues even if a plugin hook fails
-          console.warn(
-            `Plugin '${pluginName}' hook '${hookName}' failed with non-critical error:`,
-            errorMessage
-          );
-          console.warn(
-            `Continuing with remaining plugins for hook '${hookName}' (graceful degradation enabled)`
-          );
-
-          // Continue to next plugin for non-critical errors
-          // This allows multiple plugins to execute even if one fails
-        }
-      }
-    }
-
-    return result;
-  }
-
-  /**
-   * Type-safe hook execution dispatcher
-   * Handles the differences in hook signatures without type coercion
-   */
-  private async executeTypedHook<T extends keyof PluginHooks>(
-    hookName: T,
-    hook: NonNullable<PluginHooks[T]>,
-    args: Parameters<NonNullable<PluginHooks[T]>>,
-    previousResult: unknown
-  ): Promise<unknown> {
-    if (hookName === 'afterPlanFileCreated') {
-      // Content-chaining hook: replaces the content parameter with previous result
-      const typedHook = hook as NonNullable<
-        PluginHooks['afterPlanFileCreated']
-      >;
-      const [context, planFilePath, content] = args as Parameters<
-        typeof typedHook
-      >;
-      const contentToUse = ((previousResult as string | undefined) ??
-        content) as string;
-      return typedHook(context, planFilePath, contentToUse);
-    }
-
-    if (hookName === 'afterInstructionsGenerated') {
-      // Content-chaining hook: replaces the instructions parameter with previous result
-      const typedHook = hook as NonNullable<
-        PluginHooks['afterInstructionsGenerated']
-      >;
-      const [context, instructions] = args as Parameters<typeof typedHook>;
-      const instructionsToUse = (
-        previousResult !== undefined
-          ? (previousResult as Parameters<typeof typedHook>[1])
-          : instructions
-      ) as Parameters<typeof typedHook>[1];
-      return typedHook(context, instructionsToUse);
-    }
-
-    if (hookName === 'beforeStartDevelopment') {
-      const typedHook = hook as NonNullable<
-        PluginHooks['beforeStartDevelopment']
-      >;
-      const [context, startArgs] = args as Parameters<typeof typedHook>;
-      return typedHook(context, startArgs);
-    }
-
-    if (hookName === 'afterStartDevelopment') {
-      const typedHook = hook as NonNullable<
-        PluginHooks['afterStartDevelopment']
-      >;
-      const [context, startArgs, result] = args as Parameters<typeof typedHook>;
-      return typedHook(context, startArgs, result);
-    }
-
-    if (hookName === 'beforePhaseTransition') {
-      const typedHook = hook as NonNullable<
-        PluginHooks['beforePhaseTransition']
-      >;
-      const [context, currentPhase, targetPhase] = args as Parameters<
-        typeof typedHook
-      >;
-      return typedHook(context, currentPhase, targetPhase);
-    }
-
-    // This should never be reached due to type system, but ensures exhaustiveness
-    const exhaustiveCheck: never = hookName;
-    throw new Error(`Unknown hook: ${exhaustiveCheck}`);
-  }
-
-  /**
-   * Check if any enabled plugin implements a specific hook
-   */
-  hasHook(hookName: keyof PluginHooks): boolean {
-    const enabledPlugins = this.getEnabledPlugins();
-    return enabledPlugins.some(plugin => {
-      const hooks = plugin.getHooks();
-      return hooks[hookName] !== undefined;
-    });
-  }
-
-  /**
-   * Get names of all registered plugins (for debugging)
-   */
-  getPluginNames(): string[] {
-    return Array.from(this.plugins.keys());
-  }
-
-  /**
-   * Clear all plugins (mainly for testing)
-   */
-  clear(): void {
-    this.plugins.clear();
-  }
-}

package/src/resource-handlers/conversation-state.ts

@@ -1,55 +0,0 @@
-/**
- * Conversation State Resource Handler
- *
- * Handles the conversation-state resource which provides access to current
- * conversation state and phase information including conversation ID, project context,
- * current development phase, and plan file location.
- */
-
-import { createLogger } from '@codemcp/workflows-core';
-import {
-  ResourceHandler,
-  ServerContext,
-  HandlerResult,
-  ResourceContent,
-} from '../types.js';
-import { safeExecute } from '../server-helpers.js';
-
-const logger = createLogger('ConversationStateResourceHandler');
-
-/**
- * Conversation State resource handler implementation
- */
-export class ConversationStateResourceHandler implements ResourceHandler {
-  async handle(
-    uri: URL,
-    context: ServerContext
-  ): Promise<HandlerResult<ResourceContent>> {
-    logger.debug('Processing conversation state resource request', {
-      uri: uri.href,
-    });
-
-    return safeExecute(async () => {
-      // Get conversation context
-      const conversationContext =
-        await context.conversationManager.getConversationContext();
-
-      // Build state information
-      const stateInfo = {
-        conversationId: conversationContext.conversationId,
-        projectPath: conversationContext.projectPath,
-        gitBranch: conversationContext.gitBranch,
-        currentPhase: conversationContext.currentPhase,
-        planFilePath: conversationContext.planFilePath,
-        timestamp: new Date().toISOString(),
-        description: 'Current state of the development workflow conversation',
-      };
-
-      return {
-        uri: uri.href,
-        text: JSON.stringify(stateInfo, null, 2),
-        mimeType: 'application/json',
-      };
-    }, 'Failed to retrieve conversation state resource');
-  }
-}