@codemcp/workflows 3.1.21

package/src/tool-handlers/install-workflow.ts

@@ -0,0 +1,185 @@
+/**
+ * Install Workflow Tool Handler
+ *
+ * Installs workflows to .vibe/workflows/ directory from various sources
+ */
+
+import { z } from 'zod';
+import { BaseToolHandler } from './base-tool-handler.js';
+import { createLogger } from '@codemcp/workflows-core';
+import { notificationService } from '../notification-service.js';
+import fs from 'node:fs';
+import path from 'node:path';
+import { ServerContext } from '../types.js';
+
+const logger = createLogger('InstallWorkflowHandler');
+
+/**
+ * Schema for install_workflow tool arguments
+ */
+const InstallWorkflowArgsSchema = z.object({
+  source: z
+    .string()
+    .describe(
+      'Source workflow name (from unloaded workflows) or URL to workflow file'
+    ),
+  name: z
+    .string()
+    .optional()
+    .describe('Custom name for installed workflow (defaults to source name)'),
+});
+
+type InstallWorkflowArgs = z.infer<typeof InstallWorkflowArgsSchema>;
+
+interface InstallWorkflowResponse {
+  success: boolean;
+  message: string;
+  installedPath?: string;
+}
+
+/**
+ * Tool handler for installing workflows
+ */
+export class InstallWorkflowHandler extends BaseToolHandler<
+  InstallWorkflowArgs,
+  InstallWorkflowResponse
+> {
+  protected readonly argsSchema = InstallWorkflowArgsSchema;
+
+  async executeHandler(
+    args: InstallWorkflowArgs,
+    context: ServerContext
+  ): Promise<InstallWorkflowResponse> {
+    logger.info('Installing workflow', {
+      source: args.source,
+      name: args.name,
+      projectPath: context.projectPath,
+    });
+
+    try {
+      // Create .vibe/workflows directory if it doesn't exist
+      const workflowsDir = path.join(context.projectPath, '.vibe', 'workflows');
+      fs.mkdirSync(workflowsDir, { recursive: true });
+
+      // Determine if source is a workflow name or URL
+      const isUrl =
+        args.source.startsWith('http://') || args.source.startsWith('https://');
+
+      if (isUrl) {
+        return await this.installFromUrl(args.source, args.name, workflowsDir);
+      } else {
+        return await this.installFromPredefined(
+          args.source,
+          args.name,
+          workflowsDir,
+          context
+        );
+      }
+    } catch (error) {
+      const errorMessage = `Failed to install workflow: ${error instanceof Error ? error.message : 'Unknown error'}`;
+      logger.error('Workflow installation failed', error as Error, {
+        source: args.source,
+        name: args.name,
+      });
+
+      return {
+        success: false,
+        message: errorMessage,
+      };
+    }
+  }
+
+  private async installFromUrl(
+    _url: string,
+    _customName: string | undefined,
+    _workflowsDir: string
+  ): Promise<InstallWorkflowResponse> {
+    // For now, return not implemented for URLs
+    return {
+      success: false,
+      message:
+        'URL-based workflow installation not yet implemented. Use predefined workflow names.',
+    };
+  }
+
+  private async installFromPredefined(
+    workflowName: string,
+    customName: string | undefined,
+    workflowsDir: string,
+    context: ServerContext
+  ): Promise<InstallWorkflowResponse> {
+    // Get all available workflows (including unloaded ones)
+    const allWorkflows = context.workflowManager.getAllAvailableWorkflows();
+    const sourceWorkflow = allWorkflows.find(w => w.name === workflowName);
+
+    if (!sourceWorkflow) {
+      return {
+        success: false,
+        message: `Workflow '${workflowName}' not found. Use list_workflows({include_unloaded: true}) to see available workflows.`,
+      };
+    }
+
+    // Find the source workflow file
+    const workflowsSourceDir = this.findWorkflowsDirectory();
+    const sourceFile = path.join(workflowsSourceDir, `${workflowName}.yaml`);
+
+    if (!fs.existsSync(sourceFile)) {
+      return {
+        success: false,
+        message: `Source workflow file not found: ${sourceFile}`,
+      };
+    }
+
+    // Determine target filename
+    const targetName = customName || workflowName;
+    const targetFile = path.join(workflowsDir, `${targetName}.yaml`);
+
+    // Check if target already exists
+    if (fs.existsSync(targetFile)) {
+      return {
+        success: false,
+        message: `Workflow '${targetName}' already exists in .vibe/workflows/. Remove it first or use a different name.`,
+      };
+    }
+
+    // Copy the workflow file
+    fs.copyFileSync(sourceFile, targetFile);
+
+    // Reload project workflows to make the installed workflow immediately available
+    context.workflowManager.loadProjectWorkflows(context.projectPath);
+
+    logger.info('Workflow installed successfully', {
+      source: workflowName,
+      target: targetName,
+      path: targetFile,
+    });
+
+    // Notify MCP client that tool list has changed. There is no specific
+    // notification for parameter description changes, so we reuse tool list change.
+    // most MCP hosts will however not support this properly, thus we'll instruct the user to restart the server.
+    await notificationService.notifyToolListChanged();
+
+    return {
+      success: true,
+      message: `Workflow '${workflowName}' installed as '${targetName}' in .vibe/workflows/ . You may need to restart your agent to use it.`,
+      installedPath: targetFile,
+    };
+  }
+
+  private findWorkflowsDirectory(): string {
+    // Same logic as WorkflowManager
+    const possiblePaths = [
+      path.join(process.cwd(), 'resources', 'workflows'),
+      path.join(process.cwd(), 'dist', '..', 'resources', 'workflows'),
+      path.join(process.cwd(), 'src', '..', 'resources', 'workflows'),
+    ];
+
+    for (const workflowsPath of possiblePaths) {
+      if (fs.existsSync(workflowsPath)) {
+        return workflowsPath;
+      }
+    }
+
+    throw new Error('Workflows directory not found');
+  }
+}

package/src/tool-handlers/list-workflows.ts

@@ -0,0 +1,94 @@
+/**
+ * List Workflows Tool Handler
+ *
+ * Provides an overview of all available workflows with their descriptions
+ * and resource URIs for detailed information.
+ */
+
+import { z } from 'zod';
+import { BaseToolHandler } from './base-tool-handler.js';
+import { createLogger } from '@codemcp/workflows-core';
+import { ServerContext } from '../types.js';
+
+const logger = createLogger('ListWorkflowsHandler');
+
+/**
+ * Schema for list_workflows tool arguments
+ */
+const ListWorkflowsArgsSchema = z.object({
+  include_unloaded: z
+    .boolean()
+    .optional()
+    .describe(
+      'Include workflows not loaded due to domain filtering. Default: false'
+    ),
+});
+
+type ListWorkflowsArgs = z.infer<typeof ListWorkflowsArgsSchema>;
+
+/**
+ * Response format for workflow information
+ */
+interface WorkflowOverview {
+  name: string;
+  displayName: string;
+  description: string;
+  resourceUri: string;
+}
+
+interface ListWorkflowsResponse {
+  workflows: WorkflowOverview[];
+}
+
+/**
+ * Tool handler for listing available workflows
+ */
+export class ListWorkflowsHandler extends BaseToolHandler<
+  ListWorkflowsArgs,
+  ListWorkflowsResponse
+> {
+  protected readonly argsSchema = ListWorkflowsArgsSchema;
+
+  async executeHandler(
+    args: ListWorkflowsArgs,
+    context: ServerContext
+  ): Promise<ListWorkflowsResponse> {
+    logger.info('Listing available workflows', {
+      projectPath: context.projectPath,
+      includeUnloaded: args.include_unloaded,
+    });
+
+    let availableWorkflows;
+
+    if (args.include_unloaded) {
+      // Get all workflows regardless of domain filtering
+      availableWorkflows = context.workflowManager.getAllAvailableWorkflows();
+    } else {
+      // Get only loaded workflows (respects current domain filtering)
+      availableWorkflows =
+        context.workflowManager.getAvailableWorkflowsForProject(
+          context.projectPath
+        );
+    }
+
+    // Transform to response format with resource URIs
+    const workflows: WorkflowOverview[] = availableWorkflows.map(workflow => ({
+      name: workflow.name,
+      displayName: workflow.displayName,
+      description: workflow.description,
+      resourceUri: `workflow://${workflow.name}`,
+    }));
+
+    const response: ListWorkflowsResponse = {
+      workflows,
+    };
+
+    logger.info('Successfully listed workflows', {
+      count: workflows.length,
+      includeUnloaded: args.include_unloaded,
+      workflows: workflows.map(w => w.name),
+    });
+
+    return response;
+  }
+}

package/src/tool-handlers/no-idea.ts

@@ -0,0 +1,47 @@
+/**
+ * No Idea Tool Handler
+ *
+ * Provides instructions for LLMs to acknowledge knowledge gaps
+ * instead of hallucinating responses.
+ */
+
+import { z } from 'zod';
+import { BaseToolHandler } from './base-tool-handler.js';
+import { ServerContext } from '../types.js';
+
+/**
+ * Schema for no_idea tool arguments
+ */
+const NoIdeaArgsSchema = z.object({
+  context: z
+    .string()
+    .optional()
+    .describe('Optional context about what you have no knowledge of'),
+});
+
+export type NoIdeaArgs = z.infer<typeof NoIdeaArgsSchema>;
+
+/**
+ * Response format for no_idea tool
+ */
+export interface NoIdeaResponse {
+  instructions: string;
+}
+
+/**
+ * Tool handler for acknowledging knowledge gaps
+ */
+export class NoIdeaHandler extends BaseToolHandler<NoIdeaArgs, NoIdeaResponse> {
+  protected readonly argsSchema = NoIdeaArgsSchema;
+
+  async executeHandler(
+    args: NoIdeaArgs,
+    _context: ServerContext
+  ): Promise<NoIdeaResponse> {
+    const context = args.context?.trim() || 'this topic';
+
+    const instructions = `You have no clue how to respond to ${context}. Admit it. Ask the user clarifying questions which might help you get new ideas.`;
+
+    return { instructions };
+  }
+}

package/src/tool-handlers/proceed-to-phase.ts

@@ -0,0 +1,205 @@
+/**
+ * ProceedToPhase Tool Handler
+ *
+ * Handles explicit transitions to specific development phases when the current
+ * phase is complete or when a direct phase change is needed.
+ */
+
+import { ConversationRequiredToolHandler } from './base-tool-handler.js';
+import { validateRequiredArgs } from '../server-helpers.js';
+import type { ConversationContext } from '@codemcp/workflows-core';
+import { ServerContext } from '../types.js';
+
+/**
+ * Arguments for the proceed_to_phase tool
+ */
+export interface ProceedToPhaseArgs {
+  target_phase: string;
+  reason?: string;
+  review_state: 'not-required' | 'pending' | 'performed';
+}
+
+/**
+ * Response from the proceed_to_phase tool
+ */
+export interface ProceedToPhaseResult {
+  phase: string;
+  instructions: string;
+  plan_file_path: string;
+  transition_reason: string;
+  is_modeled_transition: boolean;
+  conversation_id: string;
+}
+
+/**
+ * ProceedToPhase tool handler implementation
+ */
+export class ProceedToPhaseHandler extends ConversationRequiredToolHandler<
+  ProceedToPhaseArgs,
+  ProceedToPhaseResult
+> {
+  protected async executeWithConversation(
+    args: ProceedToPhaseArgs,
+    context: ServerContext,
+    conversationContext: ConversationContext
+  ): Promise<ProceedToPhaseResult> {
+    // Validate required arguments
+    validateRequiredArgs(args, ['target_phase', 'review_state']);
+
+    const { target_phase, reason = '', review_state } = args;
+    const conversationId = conversationContext.conversationId;
+    const currentPhase = conversationContext.currentPhase;
+
+    this.logger.debug('Processing proceed_to_phase request', {
+      conversationId,
+      currentPhase,
+      targetPhase: target_phase,
+      reason,
+      reviewState: review_state,
+    });
+
+    // Validate review state if reviews are required
+    if (conversationContext.requireReviewsBeforePhaseTransition) {
+      await this.validateReviewState(
+        review_state,
+        currentPhase,
+        target_phase,
+        conversationContext.workflowName,
+        context
+      );
+    }
+
+    // Ensure state machine is loaded for this project
+    this.ensureStateMachineForProject(context, conversationContext.projectPath);
+
+    // Perform explicit transition
+    const transitionResult = context.transitionEngine.handleExplicitTransition(
+      currentPhase,
+      target_phase,
+      conversationContext.projectPath,
+      reason,
+      conversationContext.workflowName
+    );
+
+    // Update conversation state
+    await context.conversationManager.updateConversationState(conversationId, {
+      currentPhase: transitionResult.newPhase,
+    });
+
+    this.logger.info('Explicit phase transition completed', {
+      from: currentPhase,
+      to: transitionResult.newPhase,
+      reason: transitionResult.transitionReason,
+    });
+
+    // Ensure plan file exists
+    await context.planManager.ensurePlanFile(
+      conversationContext.planFilePath,
+      conversationContext.projectPath,
+      conversationContext.gitBranch
+    );
+
+    // Check if plan file exists
+    const planInfo = await context.planManager.getPlanFileInfo(
+      conversationContext.planFilePath
+    );
+
+    // Generate enhanced instructions
+    const instructions =
+      await context.instructionGenerator.generateInstructions(
+        transitionResult.instructions,
+        {
+          phase: transitionResult.newPhase,
+          conversationContext: {
+            ...conversationContext,
+            currentPhase: transitionResult.newPhase,
+          },
+          transitionReason: transitionResult.transitionReason,
+          isModeled: transitionResult.isModeled,
+          planFileExists: planInfo.exists,
+        }
+      );
+
+    // Add commit instructions if configured
+    let finalInstructions = instructions.instructions;
+    if (
+      conversationContext.gitCommitConfig?.enabled &&
+      conversationContext.gitCommitConfig.commitOnPhase
+    ) {
+      const commitMessage = `Phase transition: ${currentPhase} → ${target_phase}`;
+      finalInstructions += `\n\n**Git Commit Required**: Create a commit for this phase transition using:\n\`\`\`bash\ngit add . && git commit -m "${commitMessage}"\n\`\`\``;
+    }
+
+    // Prepare response
+    const response: ProceedToPhaseResult = {
+      phase: transitionResult.newPhase,
+      instructions: finalInstructions,
+      plan_file_path: conversationContext.planFilePath,
+      transition_reason: transitionResult.transitionReason,
+      is_modeled_transition: transitionResult.isModeled,
+      conversation_id: conversationContext.conversationId,
+    };
+
+    // Log interaction
+    await this.logInteraction(
+      context,
+      conversationId,
+      'proceed_to_phase',
+      args,
+      response,
+      transitionResult.newPhase
+    );
+
+    return response;
+  }
+
+  /**
+   * Validate review state for transitions that require reviews
+   */
+  private async validateReviewState(
+    reviewState: string,
+    currentPhase: string,
+    targetPhase: string,
+    workflowName: string,
+    context: ServerContext
+  ): Promise<void> {
+    // Get transition configuration from workflow
+    const stateMachine = context.workflowManager.loadWorkflowForProject(
+      context.projectPath,
+      workflowName
+    );
+    const currentState = stateMachine.states[currentPhase];
+
+    if (!currentState) {
+      throw new Error(`Invalid current phase: ${currentPhase}`);
+    }
+
+    const transition = currentState.transitions.find(t => t.to === targetPhase);
+    if (!transition) {
+      throw new Error(
+        `No transition found from ${currentPhase} to ${targetPhase}`
+      );
+    }
+
+    const hasReviewPerspectives =
+      transition.review_perspectives &&
+      transition.review_perspectives.length > 0;
+
+    if (hasReviewPerspectives) {
+      // This transition has review perspectives defined
+      if (reviewState === 'pending') {
+        throw new Error(
+          `Review is required before proceeding to ${targetPhase}. Please use the conduct_review tool first.`
+        );
+      }
+      if (reviewState === 'not-required') {
+        throw new Error(
+          `This transition requires review, but review_state is 'not-required'. Use 'pending' or 'performed'.`
+        );
+      }
+    } else {
+      // No review perspectives defined - transition proceeds normally
+      // Note: No error thrown when hasReviewPerspectives is false, as per user feedback
+    }
+  }
+}

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

@@ -0,0 +1,90 @@
+/**
+ * ResetDevelopment Tool Handler
+ *
+ * Handles resetting conversation state and development progress.
+ * This permanently deletes conversation state and plan file, while
+ * soft-deleting interaction logs for audit trail.
+ */
+
+import { BaseToolHandler } from './base-tool-handler.js';
+import { validateRequiredArgs } from '../server-helpers.js';
+import { ServerContext } from '../types.js';
+
+/**
+ * Arguments for the reset_development tool
+ */
+export interface ResetDevelopmentArgs {
+  confirm: boolean;
+  reason?: string;
+}
+
+/**
+ * Response from the reset_development tool
+ */
+export interface ResetDevelopmentResult {
+  success: boolean;
+  resetItems: string[];
+  message: string;
+}
+
+/**
+ * ResetDevelopment tool handler implementation
+ */
+export class ResetDevelopmentHandler extends BaseToolHandler<
+  ResetDevelopmentArgs,
+  ResetDevelopmentResult
+> {
+  protected async executeHandler(
+    args: ResetDevelopmentArgs,
+    context: ServerContext
+  ): Promise<ResetDevelopmentResult> {
+    // Validate required arguments
+    validateRequiredArgs(args, ['confirm']);
+
+    const { confirm, reason } = args;
+
+    this.logger.debug('Processing reset_development request', {
+      confirm,
+      hasReason: !!reason,
+    });
+
+    // Validate parameters
+    if (typeof confirm !== 'boolean') {
+      throw new Error('confirm parameter must be a boolean');
+    }
+
+    if (!confirm) {
+      throw new Error(
+        'Reset operation requires explicit confirmation. Set confirm parameter to true.'
+      );
+    }
+
+    // Ensure state machine is loaded for current project
+    this.ensureStateMachineForProject(context, context.projectPath);
+
+    // Perform the reset
+    const resetResult = await context.conversationManager.resetConversation(
+      confirm,
+      reason
+    );
+
+    // Transform to match our interface
+    const result: ResetDevelopmentResult = {
+      success: resetResult.success,
+      resetItems: resetResult.resetItems,
+      message: resetResult.message,
+    };
+
+    // Add conversationId for backward compatibility with tests
+    (
+      result as ResetDevelopmentResult & { conversationId: string }
+    ).conversationId = resetResult.conversationId;
+
+    this.logger.info('Reset development completed successfully', {
+      resetItems: result.resetItems,
+      reason,
+    });
+
+    return result;
+  }
+}