@codemcp/workflows 3.1.21

package/test/unit/start-development-artifact-detection.test.ts

@@ -0,0 +1,387 @@
+/**
+ * Unit tests for StartDevelopmentHandler dynamic artifact detection
+ *
+ * Tests the enhanced start_development functionality that dynamically analyzes workflows
+ * to detect which document variables are referenced and validates only those documents
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { TestAccess } from '../utils/test-access.js';
+import { StartDevelopmentHandler } from '../../packages/mcp-server/src/tool-handlers/start-development.js';
+import type { YamlStateMachine } from './../../src/state-machine-types';
+import { join } from 'node:path';
+import {
+  MockContextFactory,
+  TEST_WORKFLOWS,
+  TestAssertions,
+} from '../utils/test-helpers.js';
+
+// Mock ProjectDocsManager
+vi.mock('../../src/project-docs-manager.js');
+
+// Mock other dependencies
+vi.mock('../../src/git-manager.js', () => ({
+  GitManager: {
+    isGitRepository: vi.fn().mockReturnValue(true),
+    getCurrentCommitHash: vi.fn().mockReturnValue('abc123'),
+  },
+}));
+
+describe('StartDevelopmentHandler - Dynamic Artifact Detection', () => {
+  let handler: StartDevelopmentHandler;
+  let mockProjectDocsManager: ReturnType<
+    typeof MockContextFactory.createProjectDocsManagerMock
+  >;
+  let testProjectPath: string;
+  let mockContext: ReturnType<typeof MockContextFactory.createBasicContext>;
+
+  beforeEach(() => {
+    testProjectPath = '/test/project';
+
+    // Create mock project docs manager
+    mockProjectDocsManager =
+      MockContextFactory.createProjectDocsManagerMock(testProjectPath);
+
+    // Create handler and inject mock
+    handler = new StartDevelopmentHandler();
+    TestAccess.injectMock(
+      handler,
+      'projectDocsManager',
+      mockProjectDocsManager
+    );
+
+    // Create basic mock context
+    mockContext = MockContextFactory.createBasicContext(testProjectPath);
+
+    // Mock file system operations
+    vi.mock('fs', () => ({
+      readFileSync: vi.fn().mockReturnValue('main'),
+      writeFileSync: vi.fn(),
+      existsSync: vi.fn().mockReturnValue(false),
+    }));
+  });
+
+  describe('dynamic workflow analysis', () => {
+    it('should proceed normally when workflow contains no document variables', async () => {
+      mockContext.workflowManager.loadWorkflowForProject.mockReturnValue(
+        TEST_WORKFLOWS.simple
+      );
+
+      const result = await handler.executeHandler(
+        { workflow: 'simple-workflow' },
+        mockContext
+      );
+
+      expect(mockProjectDocsManager.getProjectDocsInfo).not.toHaveBeenCalled();
+      TestAssertions.expectNormalPhase(result, 'requirements');
+    });
+
+    it('should detect and validate only referenced document variables', async () => {
+      mockContext.workflowManager.loadWorkflowForProject.mockReturnValue(
+        TEST_WORKFLOWS.requiredArchDoc
+      );
+
+      // Update mock context to match the workflow's initial state
+      mockContext.conversationManager.createConversationContext = vi
+        .fn()
+        .mockResolvedValue({
+          conversationId: 'test-conversation',
+          currentPhase: 'design',
+          planFilePath: join(testProjectPath, '.vibe', 'development-plan.md'),
+        });
+
+      mockProjectDocsManager.getProjectDocsInfo.mockResolvedValue({
+        architecture: {
+          exists: false,
+          path: join(testProjectPath, '.vibe', 'docs', 'architecture.md'),
+        },
+        requirements: {
+          exists: true,
+          path: join(testProjectPath, '.vibe', 'docs', 'requirements.md'),
+        },
+        design: {
+          exists: true,
+          path: join(testProjectPath, '.vibe', 'docs', 'design.md'),
+        },
+      });
+
+      const result = await handler.executeHandler(
+        { workflow: 'arch-focused' },
+        mockContext
+      );
+
+      TestAssertions.expectArtifactSetupPhase(result);
+      expect(result.instructions).toContain(
+        '**Referenced Variables:** `$ARCHITECTURE_DOC`'
+      );
+      expect(result.instructions).toContain('architecture.md');
+      expect(result.instructions).toContain('✅ requirements.md');
+      expect(result.instructions).toContain('✅ design.md');
+    });
+
+    it('should detect multiple document variables in workflow', async () => {
+      mockContext.workflowManager.loadWorkflowForProject.mockReturnValue(
+        TEST_WORKFLOWS.requiredMultipleDocs
+      );
+
+      // Update mock context to match the workflow's initial state
+      mockContext.conversationManager.createConversationContext = vi
+        .fn()
+        .mockResolvedValue({
+          conversationId: 'test-conversation',
+          currentPhase: 'implementation',
+          planFilePath: join(testProjectPath, '.vibe', 'development-plan.md'),
+        });
+
+      mockProjectDocsManager.getProjectDocsInfo.mockResolvedValue({
+        architecture: {
+          exists: false,
+          path: join(testProjectPath, '.vibe', 'docs', 'architecture.md'),
+        },
+        requirements: {
+          exists: false,
+          path: join(testProjectPath, '.vibe', 'docs', 'requirements.md'),
+        },
+        design: {
+          exists: false,
+          path: join(testProjectPath, '.vibe', 'docs', 'design.md'),
+        },
+      });
+
+      const result = await handler.executeHandler(
+        { workflow: 'multi-doc' },
+        mockContext
+      );
+
+      TestAssertions.expectArtifactSetupPhase(result);
+      expect(result.instructions).toContain(
+        '**Referenced Variables:** `$ARCHITECTURE_DOC`, `$REQUIREMENTS_DOC`, `$DESIGN_DOC`'
+      );
+      expect(result.instructions).toContain('architecture.md');
+      expect(result.instructions).toContain('requirements.md');
+      expect(result.instructions).toContain('design.md');
+    });
+
+    it('should proceed normally when all referenced documents exist', async () => {
+      mockContext.workflowManager.loadWorkflowForProject.mockReturnValue(
+        TEST_WORKFLOWS.requiredMultipleDocs
+      );
+
+      // Mock conversation context to match initial state
+      mockContext.conversationManager.createConversationContext.mockResolvedValue(
+        {
+          conversationId: 'test-conversation',
+          currentPhase: 'implementation',
+          projectPath: testProjectPath,
+          planFilePath: join(testProjectPath, '.vibe', 'plan.md'),
+          gitBranch: 'feature-branch',
+        }
+      );
+
+      // Mock transition engine to return the correct phase
+      mockContext.transitionEngine.handleExplicitTransition.mockResolvedValue({
+        newPhase: 'implementation',
+      });
+
+      mockProjectDocsManager.getProjectDocsInfo.mockResolvedValue({
+        architecture: {
+          exists: true,
+          path: join(testProjectPath, '.vibe', 'docs', 'architecture.md'),
+        },
+        requirements: {
+          exists: true,
+          path: join(testProjectPath, '.vibe', 'docs', 'requirements.md'),
+        },
+        design: {
+          exists: true,
+          path: join(testProjectPath, '.vibe', 'docs', 'design.md'),
+        },
+      });
+
+      const result = await handler.executeHandler(
+        { workflow: 'complete-docs' },
+        mockContext
+      );
+
+      expect(mockProjectDocsManager.getProjectDocsInfo).toHaveBeenCalledWith(
+        testProjectPath
+      );
+      TestAssertions.expectNormalPhase(result, 'implementation');
+    });
+
+    it('should handle partial document availability correctly', async () => {
+      // Mock workflow that references REQUIREMENTS_DOC and DESIGN_DOC
+      const partialWorkflow = {
+        name: 'req-design-focused',
+        description: 'Workflow focusing on requirements and design docs',
+        initial_state: 'development',
+        metadata: {
+          requiresDocumentation: true,
+        },
+        states: {
+          development: {
+            default_instructions:
+              'Implement features based on $REQUIREMENTS_DOC and follow $DESIGN_DOC patterns.',
+          },
+        },
+      } as Partial<YamlStateMachine>;
+
+      mockContext.workflowManager.loadWorkflowForProject.mockReturnValue(
+        partialWorkflow
+      );
+
+      // Update mock context to match the workflow's initial state
+      mockContext.conversationManager.createConversationContext = vi
+        .fn()
+        .mockResolvedValue({
+          conversationId: 'test-conversation',
+          currentPhase: 'development',
+          planFilePath: join(testProjectPath, '.vibe', 'development-plan.md'),
+        });
+
+      mockProjectDocsManager.getProjectDocsInfo.mockResolvedValue({
+        architecture: {
+          exists: true,
+          path: join(testProjectPath, '.vibe', 'docs', 'architecture.md'),
+        },
+        requirements: {
+          exists: true,
+          path: join(testProjectPath, '.vibe', 'docs', 'requirements.md'),
+        },
+        design: {
+          exists: false,
+          path: join(testProjectPath, '.vibe', 'docs', 'design.md'),
+        },
+      });
+
+      const result = await handler.executeHandler(
+        { workflow: 'req-design-focused' },
+        mockContext
+      );
+
+      TestAssertions.expectArtifactSetupPhase(result);
+      expect(result.instructions).toContain(
+        '**Referenced Variables:** `$REQUIREMENTS_DOC`, `$DESIGN_DOC`'
+      );
+      expect(result.instructions).toContain('design.md'); // Only missing doc
+      expect(result.instructions).toContain('✅ architecture.md'); // Existing doc
+      expect(result.instructions).toContain('✅ requirements.md'); // Existing doc
+    });
+
+    it('should handle workflow loading errors gracefully', async () => {
+      // Mock workflow loading failure - this should happen during artifact check, not during normal workflow loading
+      let callCount = 0;
+      mockContext.workflowManager.loadWorkflowForProject.mockImplementation(
+        () => {
+          callCount++;
+          if (callCount === 1) {
+            // First call during artifact check - throw error
+            throw new Error('Workflow not found');
+          } else {
+            // Second call during normal flow - return valid workflow
+            return TEST_WORKFLOWS.simple;
+          }
+        }
+      );
+
+      const result = await handler.executeHandler(
+        { workflow: 'invalid-workflow' },
+        mockContext
+      );
+
+      // Should proceed without artifact check when workflow analysis fails
+      TestAssertions.expectNormalPhase(result, 'requirements');
+    });
+
+    it('should include detected variables in setup guidance', async () => {
+      mockContext.workflowManager.loadWorkflowForProject.mockReturnValue(
+        TEST_WORKFLOWS.requiredArchDoc
+      );
+
+      // Update mock context to match the workflow's initial state
+      mockContext.conversationManager.createConversationContext = vi
+        .fn()
+        .mockResolvedValue({
+          conversationId: 'test-conversation',
+          currentPhase: 'design',
+          planFilePath: join(testProjectPath, '.vibe', 'development-plan.md'),
+        });
+
+      mockProjectDocsManager.getProjectDocsInfo.mockResolvedValue({
+        architecture: {
+          exists: false,
+          path: join(testProjectPath, '.vibe', 'docs', 'architecture.md'),
+        },
+        requirements: {
+          exists: true,
+          path: join(testProjectPath, '.vibe', 'docs', 'requirements.md'),
+        },
+        design: {
+          exists: true,
+          path: join(testProjectPath, '.vibe', 'docs', 'design.md'),
+        },
+      });
+
+      const result = await handler.executeHandler(
+        { workflow: 'arch-only' },
+        mockContext
+      );
+
+      expect(result.instructions).toContain(
+        '**Referenced Variables:** `$ARCHITECTURE_DOC`'
+      );
+      expect(result.instructions).toContain(
+        'detected variables: `$ARCHITECTURE_DOC`'
+      );
+    });
+
+    it('should proceed normally for optional workflows with missing documents', async () => {
+      // Use a workflow that has document variables but NO requiresDocumentation flag
+      mockContext.workflowManager.loadWorkflowForProject.mockReturnValue(
+        TEST_WORKFLOWS.withArchDoc
+      );
+
+      // Mock conversation context to match initial state
+      mockContext.conversationManager.createConversationContext.mockResolvedValue(
+        {
+          conversationId: 'test-conversation',
+          currentPhase: 'design',
+          projectPath: testProjectPath,
+          planFilePath: join(testProjectPath, '.vibe', 'plan.md'),
+          gitBranch: 'feature-branch',
+        }
+      );
+
+      // Mock transition engine to return the correct phase
+      mockContext.transitionEngine.handleExplicitTransition.mockResolvedValue({
+        newPhase: 'design',
+      });
+
+      // Mock all documents as missing
+      mockProjectDocsManager.getProjectDocsInfo.mockResolvedValue({
+        architecture: {
+          exists: false,
+          path: join(testProjectPath, '.vibe', 'docs', 'architecture.md'),
+        },
+        requirements: {
+          exists: false,
+          path: join(testProjectPath, '.vibe', 'docs', 'requirements.md'),
+        },
+        design: {
+          exists: false,
+          path: join(testProjectPath, '.vibe', 'docs', 'design.md'),
+        },
+      });
+
+      const result = await handler.executeHandler(
+        { workflow: 'optional-arch-workflow' },
+        mockContext
+      );
+
+      // Should proceed to normal phase instead of artifact-setup
+      // because requiresDocumentation is not set (defaults to false)
+      TestAssertions.expectNormalPhase(result, 'design');
+      expect(result.instructions).not.toContain('Referenced Variables');
+    });
+  });
+});

package/test/unit/start-development-gitignore.test.ts

@@ -0,0 +1,178 @@
+/**
+ * Unit tests for StartDevelopment .gitignore management
+ *
+ * Tests the automatic .vibe/.gitignore creation functionality
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  rmSync,
+} from 'node:fs';
+import { resolve } from 'node:path';
+import { TestAccess } from '../utils/test-access.js';
+import { tmpdir } from 'node:os';
+import { StartDevelopmentHandler } from '../../packages/mcp-server/src/tool-handlers/start-development.js';
+
+describe('StartDevelopment .gitignore management', () => {
+  let tempDir: string;
+  let handler: StartDevelopmentHandler;
+  let mockLogger: {
+    debug: ReturnType<typeof vi.fn>;
+    info: ReturnType<typeof vi.fn>;
+    warn: ReturnType<typeof vi.fn>;
+    error: ReturnType<typeof vi.fn>;
+  };
+
+  beforeEach(() => {
+    // Create temporary directory for testing
+    tempDir = resolve(tmpdir(), `vibe-test-${Date.now()}`);
+    mkdirSync(tempDir, { recursive: true });
+
+    // Mock logger
+    mockLogger = {
+      debug: vi.fn(),
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+    };
+
+    // Create handler instance with mocked logger
+    handler = new StartDevelopmentHandler();
+    (handler as unknown as { logger: unknown }).logger = mockLogger;
+  });
+
+  afterEach(() => {
+    // Clean up temporary directory
+    if (existsSync(tempDir)) {
+      rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  describe('ensureGitignoreEntry', () => {
+    it('should skip non-git repositories', () => {
+      // Call the private method cleanly
+      TestAccess.callMethod(handler, 'ensureGitignoreEntry', tempDir);
+
+      expect(mockLogger.debug).toHaveBeenCalledWith(
+        'Not a git repository, skipping .gitignore management',
+        { projectPath: tempDir }
+      );
+    });
+
+    it('should create .vibe/.gitignore when none exists in git repo', () => {
+      // Create .git directory to simulate git repo
+      mkdirSync(resolve(tempDir, '.git'));
+
+      // Call the method
+      TestAccess.callMethod(handler, 'ensureGitignoreEntry', tempDir);
+
+      // Check that .vibe/.gitignore was created with correct content
+      const vibeGitignorePath = resolve(tempDir, '.vibe', '.gitignore');
+      expect(existsSync(vibeGitignorePath)).toBe(true);
+
+      const content = readFileSync(vibeGitignorePath, 'utf-8');
+      expect(content).toContain('*.sqlite');
+      expect(content).toContain('conversation-state.sqlite');
+
+      expect(mockLogger.info).toHaveBeenCalledWith(
+        'Created .vibe/.gitignore to exclude SQLite files',
+        { projectPath: tempDir, gitignorePath: vibeGitignorePath }
+      );
+    });
+
+    it('should create .vibe directory if it does not exist', () => {
+      // Create .git directory to simulate git repo
+      mkdirSync(resolve(tempDir, '.git'));
+
+      // Ensure .vibe directory doesn't exist
+      const vibeDir = resolve(tempDir, '.vibe');
+      expect(existsSync(vibeDir)).toBe(false);
+
+      // Call the method
+      TestAccess.callMethod(handler, 'ensureGitignoreEntry', tempDir);
+
+      // Check that .vibe directory was created
+      expect(existsSync(vibeDir)).toBe(true);
+
+      // Check that .vibe/.gitignore was created
+      const vibeGitignorePath = resolve(vibeDir, '.gitignore');
+      expect(existsSync(vibeGitignorePath)).toBe(true);
+    });
+
+    it('should skip when .vibe/.gitignore already exists with SQLite exclusions', () => {
+      // Create .git directory
+      mkdirSync(resolve(tempDir, '.git'));
+
+      // Create .vibe directory and .gitignore with existing SQLite exclusions
+      const vibeDir = resolve(tempDir, '.vibe');
+      mkdirSync(vibeDir, { recursive: true });
+      const vibeGitignorePath = resolve(vibeDir, '.gitignore');
+      const existingContent = '*.sqlite\nconversation-state.sqlite*\n';
+      writeFileSync(vibeGitignorePath, existingContent);
+
+      // Call the method
+      TestAccess.callMethod(handler, 'ensureGitignoreEntry', tempDir);
+
+      // Check that content wasn't changed
+      const content = readFileSync(vibeGitignorePath, 'utf-8');
+      expect(content).toBe(existingContent);
+
+      expect(mockLogger.debug).toHaveBeenCalledWith(
+        '.vibe/.gitignore already exists with SQLite exclusions',
+        { gitignorePath: vibeGitignorePath }
+      );
+    });
+
+    it('should recreate .vibe/.gitignore if existing one is incomplete', () => {
+      // Create .git directory
+      mkdirSync(resolve(tempDir, '.git'));
+
+      // Create .vibe directory and incomplete .gitignore
+      const vibeDir = resolve(tempDir, '.vibe');
+      mkdirSync(vibeDir, { recursive: true });
+      const vibeGitignorePath = resolve(vibeDir, '.gitignore');
+      const incompleteContent = 'some-other-file\n';
+      writeFileSync(vibeGitignorePath, incompleteContent);
+
+      // Call the method
+      TestAccess.callMethod(handler, 'ensureGitignoreEntry', tempDir);
+
+      // Check that content was updated to include SQLite exclusions
+      const content = readFileSync(vibeGitignorePath, 'utf-8');
+      expect(content).toContain('*.sqlite');
+      expect(content).toContain('conversation-state.sqlite');
+
+      expect(mockLogger.info).toHaveBeenCalledWith(
+        'Created .vibe/.gitignore to exclude SQLite files',
+        { projectPath: tempDir, gitignorePath: vibeGitignorePath }
+      );
+    });
+
+    it('should not affect parent directory .gitignore', () => {
+      // Create .git directory
+      mkdirSync(resolve(tempDir, '.git'));
+
+      // Create parent .gitignore with existing content
+      const parentGitignorePath = resolve(tempDir, '.gitignore');
+      const parentContent = 'node_modules/\n*.log\n';
+      writeFileSync(parentGitignorePath, parentContent);
+
+      // Call the method
+      TestAccess.callMethod(handler, 'ensureGitignoreEntry', tempDir);
+
+      // Check that parent .gitignore was not modified
+      const parentContentAfter = readFileSync(parentGitignorePath, 'utf-8');
+      expect(parentContentAfter).toBe(parentContent);
+
+      // Check that .vibe/.gitignore was created
+      const vibeGitignorePath = resolve(tempDir, '.vibe', '.gitignore');
+      expect(existsSync(vibeGitignorePath)).toBe(true);
+      const vibeContent = readFileSync(vibeGitignorePath, 'utf-8');
+      expect(vibeContent).toContain('*.sqlite');
+    });
+  });
+});

package/test/unit/system-prompt-resource.test.ts

@@ -0,0 +1,101 @@
+/**
+ * System Prompt Resource Tests
+ *
+ * Tests for the system-prompt resource handler to ensure it properly
+ * exposes the system prompt through the MCP protocol.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { SystemPromptResourceHandler } from '../../src/resource-handlers/system-prompt.js';
+import type { ServerContext } from '../../src/types.js';
+
+describe('System Prompt Resource', () => {
+  it('should expose system prompt as MCP resource', async () => {
+    const handler = new SystemPromptResourceHandler();
+
+    // Call the handler directly
+    const result = await handler.handle(
+      new URL('system-prompt://'),
+      {} as ServerContext
+    );
+
+    // Verify the safeExecute wrapper structure
+    expect(result).toBeDefined();
+    expect(result.success).toBe(true);
+    expect(result.data).toBeDefined();
+
+    const data = result.data;
+    expect(data.uri).toBe('system-prompt://');
+    expect(data.mimeType).toBe('text/plain');
+    expect(data.text).toBeDefined();
+    expect(typeof data.text).toBe('string');
+
+    // Verify content contains expected system prompt elements
+    expect(data.text).toContain(
+      'You are an AI assistant that helps users develop software features'
+    );
+    expect(data.text).toContain('responsible-vibe-mcp');
+    expect(data.text).toContain('whats_next()');
+    expect(data.text).toContain('proceed_to_phase({');
+    expect(data.text).toContain('Core Workflow');
+
+    // Verify it's a substantial prompt (not empty or truncated)
+    expect(data.text.length).toBeGreaterThan(1000);
+  });
+
+  it('should be workflow-independent and consistent', async () => {
+    const handler = new SystemPromptResourceHandler();
+
+    // Get system prompt multiple times
+    const result1 = await handler.handle(
+      new URL('system-prompt://'),
+      {} as ServerContext
+    );
+    const result2 = await handler.handle(
+      new URL('system-prompt://'),
+      {} as ServerContext
+    );
+    const result3 = await handler.handle(
+      new URL('system-prompt://'),
+      {} as ServerContext
+    );
+
+    // All should be successful
+    expect(result1.success).toBe(true);
+    expect(result2.success).toBe(true);
+    expect(result3.success).toBe(true);
+
+    // All should be identical
+    expect(result1.data.text).toBe(result2.data.text);
+    expect(result2.data.text).toBe(result3.data.text);
+
+    // Verify the prompt contains standard elements
+    expect(result1.data.text).toContain('You are an AI assistant');
+    expect(result1.data.text).toContain('whats_next()');
+    expect(result1.data.text).toContain('Development Workflow');
+    expect(result1.data.text).toContain('start_development()');
+  });
+
+  it('should use default waterfall workflow for system prompt', async () => {
+    const handler = new SystemPromptResourceHandler();
+
+    const result = await handler.handle(
+      new URL('system-prompt://'),
+      {} as ServerContext
+    );
+
+    expect(result.success).toBe(true);
+
+    // The system prompt should be generated using the default workflow
+    // and should contain workflow-agnostic instructions
+    expect(result.data.text).toContain(
+      'The responsible-vibe-mcp server will guide you through development phases'
+    );
+    expect(result.data.text).toContain(
+      'available phases and their descriptions will be provided'
+    );
+    expect(result.data.text).toContain(
+      'tool responses from start_development() and resume_workflow()'
+    );
+  });
+});