@vibescope/mcp-server 0.0.1 → 0.1.0

package/src/handlers/sprints.test.ts

@@ -0,0 +1,711 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { HandlerContext, TokenUsage } from './types.js';
+import {
+	createSprint,
+	updateSprint,
+	getSprint,
+	getSprints,
+	deleteSprint,
+	startSprint,
+	completeSprint,
+	addTaskToSprint,
+	removeTaskFromSprint,
+	getSprintBacklog,
+	getSprintVelocity,
+} from './sprints.js';
+import { ValidationError } from '../validators.js';
+
+// ============================================================================
+// Mock API Client
+// ============================================================================
+
+const mockApiClient = {
+	proxy: vi.fn(),
+};
+
+vi.mock('../api-client.js', () => ({
+	getApiClient: () => mockApiClient,
+}));
+
+// ============================================================================
+// Test Utilities
+// ============================================================================
+
+function createMockContext(
+	options: { sessionId?: string | null } = {}
+): HandlerContext {
+	const defaultTokenUsage: TokenUsage = {
+		callCount: 5,
+		totalTokens: 2500,
+		byTool: {},
+		byModel: {},
+		currentModel: null,
+	};
+
+	const sessionId = 'sessionId' in options ? options.sessionId : 'session-123';
+
+	return {
+		auth: { userId: 'user-123', apiKeyId: 'api-key-123', scope: 'personal' as const },
+		session: {
+			instanceId: 'instance-abc',
+			currentSessionId: sessionId,
+			currentPersona: 'Wave',
+			currentRole: null,
+			tokenUsage: defaultTokenUsage,
+		},
+		updateSession: vi.fn(),
+	};
+}
+
+const VALID_UUID = '123e4567-e89b-12d3-a456-426614174000';
+const VALID_UUID_2 = '223e4567-e89b-12d3-a456-426614174001';
+
+// ============================================================================
+// createSprint Tests
+// ============================================================================
+
+describe('createSprint', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should throw error for missing project_id', async () => {
+		const ctx = createMockContext();
+
+		await expect(
+			createSprint({ title: 'Sprint 1', start_date: '2025-01-01', end_date: '2025-01-14' }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should throw error for missing title', async () => {
+		const ctx = createMockContext();
+
+		await expect(
+			createSprint({ project_id: VALID_UUID, start_date: '2025-01-01', end_date: '2025-01-14' }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should throw error for missing start_date', async () => {
+		const ctx = createMockContext();
+
+		await expect(
+			createSprint({ project_id: VALID_UUID, title: 'Sprint 1', end_date: '2025-01-14' }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should throw error for missing end_date', async () => {
+		const ctx = createMockContext();
+
+		await expect(
+			createSprint({ project_id: VALID_UUID, title: 'Sprint 1', start_date: '2025-01-01' }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should throw error for invalid start_date format', async () => {
+		const ctx = createMockContext();
+
+		await expect(
+			createSprint({
+				project_id: VALID_UUID,
+				title: 'Sprint 1',
+				start_date: 'invalid',
+				end_date: '2025-01-14'
+			}, ctx)
+		).rejects.toThrow('Invalid start_date format');
+	});
+
+	it('should throw error when end_date is before start_date', async () => {
+		const ctx = createMockContext();
+
+		await expect(
+			createSprint({
+				project_id: VALID_UUID,
+				title: 'Sprint 1',
+				start_date: '2025-01-14',
+				end_date: '2025-01-01'
+			}, ctx)
+		).rejects.toThrow('end_date must be on or after start_date');
+	});
+
+	it('should create sprint successfully', async () => {
+		mockApiClient.proxy.mockResolvedValue({
+			ok: true,
+			data: { success: true, sprint_id: VALID_UUID, sprint_number: 1 },
+		});
+		const ctx = createMockContext();
+
+		const result = await createSprint({
+			project_id: VALID_UUID,
+			title: 'Sprint 1',
+			start_date: '2025-01-01',
+			end_date: '2025-01-14',
+		}, ctx);
+
+		expect(result.result).toMatchObject({
+			success: true,
+			sprint_id: VALID_UUID,
+			sprint_number: 1,
+			status: 'planning',
+		});
+	});
+
+	it('should create sprint with optional fields', async () => {
+		mockApiClient.proxy.mockResolvedValue({
+			ok: true,
+			data: { success: true, sprint_id: VALID_UUID, sprint_number: 2 },
+		});
+		const ctx = createMockContext();
+
+		const result = await createSprint({
+			project_id: VALID_UUID,
+			title: 'Sprint 2',
+			goal: 'Complete feature X',
+			start_date: '2025-01-15',
+			end_date: '2025-01-28',
+			auto_deploy_on_completion: true,
+			deploy_environment: 'staging',
+			deploy_version_bump: 'minor',
+		}, ctx);
+
+		expect(result.result).toMatchObject({
+			success: true,
+			sprint_number: 2,
+		});
+		expect(mockApiClient.proxy).toHaveBeenCalledWith(
+			'create_sprint',
+			expect.objectContaining({
+				goal: 'Complete feature X',
+				auto_deploy_on_completion: true,
+				deploy_environment: 'staging',
+			}),
+			expect.any(Object)
+		);
+	});
+
+	it('should throw error when API call fails', async () => {
+		mockApiClient.proxy.mockResolvedValue({
+			ok: false,
+			error: 'Database error',
+		});
+		const ctx = createMockContext();
+
+		await expect(
+			createSprint({
+				project_id: VALID_UUID,
+				title: 'Sprint 1',
+				start_date: '2025-01-01',
+				end_date: '2025-01-14',
+			}, ctx)
+		).rejects.toThrow('Failed to create sprint: Database error');
+	});
+});
+
+// ============================================================================
+// updateSprint Tests
+// ============================================================================
+
+describe('updateSprint', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should throw error for missing sprint_id', async () => {
+		const ctx = createMockContext();
+
+		await expect(updateSprint({}, ctx)).rejects.toThrow(ValidationError);
+	});
+
+	it('should throw error for invalid sprint_id UUID', async () => {
+		const ctx = createMockContext();
+
+		await expect(
+			updateSprint({ sprint_id: 'invalid' }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should update sprint successfully', async () => {
+		mockApiClient.proxy.mockResolvedValue({
+			ok: true,
+			data: { success: true },
+		});
+		const ctx = createMockContext();
+
+		const result = await updateSprint({
+			sprint_id: VALID_UUID,
+			title: 'Updated Sprint',
+			goal: 'New goal',
+		}, ctx);
+
+		expect(result.result).toMatchObject({
+			success: true,
+			sprint_id: VALID_UUID,
+		});
+	});
+
+	it('should throw error when API call fails', async () => {
+		mockApiClient.proxy.mockResolvedValue({
+			ok: false,
+			error: 'Sprint not found',
+		});
+		const ctx = createMockContext();
+
+		await expect(
+			updateSprint({ sprint_id: VALID_UUID, title: 'Test' }, ctx)
+		).rejects.toThrow('Failed to update sprint: Sprint not found');
+	});
+});
+
+// ============================================================================
+// getSprint Tests
+// ============================================================================
+
+describe('getSprint', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should throw error for missing sprint_id', async () => {
+		const ctx = createMockContext();
+
+		await expect(getSprint({}, ctx)).rejects.toThrow(ValidationError);
+	});
+
+	it('should return sprint with tasks', async () => {
+		mockApiClient.proxy.mockResolvedValue({
+			ok: true,
+			data: {
+				id: VALID_UUID,
+				title: 'Sprint 1',
+				sprint_number: 1,
+				sprint_status: 'active',
+				progress_percentage: 50,
+				velocity_points: 8,
+				committed_points: 13,
+				pre_tasks: [],
+				core_tasks: [{ id: 'task-1', title: 'Task 1' }],
+				post_tasks: [],
+				total_tasks: 1,
+			},
+		});
+		const ctx = createMockContext();
+
+		const result = await getSprint({ sprint_id: VALID_UUID }, ctx);
+
+		expect(result.result).toMatchObject({
+			id: VALID_UUID,
+			sprint_status: 'active',
+			velocity_points: 8,
+			committed_points: 13,
+		});
+	});
+});
+
+// ============================================================================
+// getSprints Tests
+// ============================================================================
+
+describe('getSprints', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should throw error for missing project_id', async () => {
+		const ctx = createMockContext();
+
+		await expect(getSprints({}, ctx)).rejects.toThrow(ValidationError);
+	});
+
+	it('should return empty list when no sprints', async () => {
+		mockApiClient.proxy.mockResolvedValue({
+			ok: true,
+			data: { sprints: [], total_count: 0, has_more: false },
+		});
+		const ctx = createMockContext();
+
+		const result = await getSprints({ project_id: VALID_UUID }, ctx);
+
+		expect(result.result).toMatchObject({
+			sprints: [],
+			total_count: 0,
+		});
+	});
+
+	it('should return sprints filtered by status', async () => {
+		mockApiClient.proxy.mockResolvedValue({
+			ok: true,
+			data: {
+				sprints: [{ id: VALID_UUID, sprint_status: 'active' }],
+				total_count: 1,
+				has_more: false,
+			},
+		});
+		const ctx = createMockContext();
+
+		const result = await getSprints({
+			project_id: VALID_UUID,
+			status: 'active',
+		}, ctx);
+
+		expect(mockApiClient.proxy).toHaveBeenCalledWith(
+			'get_sprints',
+			expect.objectContaining({ status: 'active' })
+		);
+	});
+
+	it('should throw error for invalid status', async () => {
+		const ctx = createMockContext();
+
+		await expect(
+			getSprints({ project_id: VALID_UUID, status: 'invalid_status' }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+});
+
+// ============================================================================
+// deleteSprint Tests
+// ============================================================================
+
+describe('deleteSprint', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should throw error for missing sprint_id', async () => {
+		const ctx = createMockContext();
+
+		await expect(deleteSprint({}, ctx)).rejects.toThrow(ValidationError);
+	});
+
+	it('should delete sprint successfully', async () => {
+		mockApiClient.proxy.mockResolvedValue({
+			ok: true,
+			data: { success: true },
+		});
+		const ctx = createMockContext();
+
+		const result = await deleteSprint({ sprint_id: VALID_UUID }, ctx);
+
+		expect(result.result).toMatchObject({
+			success: true,
+			message: 'Sprint deleted. Tasks are preserved.',
+		});
+	});
+});
+
+// ============================================================================
+// startSprint Tests
+// ============================================================================
+
+describe('startSprint', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should throw error for missing sprint_id', async () => {
+		const ctx = createMockContext();
+
+		await expect(startSprint({}, ctx)).rejects.toThrow(ValidationError);
+	});
+
+	it('should start sprint and lock committed_points', async () => {
+		mockApiClient.proxy.mockResolvedValue({
+			ok: true,
+			data: {
+				success: true,
+				sprint_id: VALID_UUID,
+				sprint_status: 'active',
+				committed_points: 21,
+				message: 'Sprint started',
+			},
+		});
+		const ctx = createMockContext();
+
+		const result = await startSprint({ sprint_id: VALID_UUID }, ctx);
+
+		expect(result.result).toMatchObject({
+			success: true,
+			sprint_status: 'active',
+			committed_points: 21,
+		});
+	});
+
+	it('should throw error when sprint not in planning', async () => {
+		mockApiClient.proxy.mockResolvedValue({
+			ok: false,
+			error: "Cannot start sprint in 'active' status",
+		});
+		const ctx = createMockContext();
+
+		await expect(
+			startSprint({ sprint_id: VALID_UUID }, ctx)
+		).rejects.toThrow("Cannot start sprint in 'active' status");
+	});
+});
+
+// ============================================================================
+// completeSprint Tests
+// ============================================================================
+
+describe('completeSprint', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should throw error for missing sprint_id', async () => {
+		const ctx = createMockContext();
+
+		await expect(completeSprint({}, ctx)).rejects.toThrow(ValidationError);
+	});
+
+	it('should complete sprint and calculate velocity', async () => {
+		mockApiClient.proxy.mockResolvedValue({
+			ok: true,
+			data: {
+				success: true,
+				sprint_id: VALID_UUID,
+				sprint_status: 'completed',
+				velocity_points: 18,
+				committed_points: 21,
+				deployment_triggered: true,
+				message: 'Sprint completed',
+			},
+		});
+		const ctx = createMockContext();
+
+		const result = await completeSprint({
+			sprint_id: VALID_UUID,
+			skip_retrospective: true,
+		}, ctx);
+
+		expect(result.result).toMatchObject({
+			success: true,
+			sprint_status: 'completed',
+			velocity_points: 18,
+			committed_points: 21,
+		});
+	});
+
+	it('should transition through status phases', async () => {
+		mockApiClient.proxy.mockResolvedValue({
+			ok: true,
+			data: {
+				success: true,
+				sprint_id: VALID_UUID,
+				sprint_status: 'in_review',
+				message: "Sprint moved to 'in_review'",
+			},
+		});
+		const ctx = createMockContext();
+
+		const result = await completeSprint({ sprint_id: VALID_UUID }, ctx);
+
+		expect(result.result).toMatchObject({
+			sprint_status: 'in_review',
+		});
+	});
+});
+
+// ============================================================================
+// addTaskToSprint Tests
+// ============================================================================
+
+describe('addTaskToSprint', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should throw error for missing sprint_id', async () => {
+		const ctx = createMockContext();
+
+		await expect(
+			addTaskToSprint({ task_id: VALID_UUID_2 }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should throw error for missing task_id', async () => {
+		const ctx = createMockContext();
+
+		await expect(
+			addTaskToSprint({ sprint_id: VALID_UUID }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should throw error for negative story_points', async () => {
+		const ctx = createMockContext();
+
+		await expect(
+			addTaskToSprint({
+				sprint_id: VALID_UUID,
+				task_id: VALID_UUID_2,
+				story_points: -1,
+			}, ctx)
+		).rejects.toThrow('story_points must be a non-negative integer');
+	});
+
+	it('should add task to sprint with story points', async () => {
+		mockApiClient.proxy.mockResolvedValue({
+			ok: true,
+			data: {
+				success: true,
+				sprint_id: VALID_UUID,
+				task_id: VALID_UUID_2,
+				story_points: 5,
+				phase: 'core',
+				committed_points: 21,
+			},
+		});
+		const ctx = createMockContext();
+
+		const result = await addTaskToSprint({
+			sprint_id: VALID_UUID,
+			task_id: VALID_UUID_2,
+			story_points: 5,
+		}, ctx);
+
+		expect(result.result).toMatchObject({
+			success: true,
+			task_id: VALID_UUID_2,
+			story_points: 5,
+			committed_points: 21,
+		});
+	});
+
+	it('should throw error when sprint not in planning', async () => {
+		mockApiClient.proxy.mockResolvedValue({
+			ok: false,
+			error: "Cannot add tasks to sprint in 'active' status",
+		});
+		const ctx = createMockContext();
+
+		await expect(
+			addTaskToSprint({
+				sprint_id: VALID_UUID,
+				task_id: VALID_UUID_2,
+			}, ctx)
+		).rejects.toThrow("Cannot add tasks to sprint in 'active' status");
+	});
+});
+
+// ============================================================================
+// removeTaskFromSprint Tests
+// ============================================================================
+
+describe('removeTaskFromSprint', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should throw error for missing sprint_id', async () => {
+		const ctx = createMockContext();
+
+		await expect(
+			removeTaskFromSprint({ task_id: VALID_UUID_2 }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should throw error for missing task_id', async () => {
+		const ctx = createMockContext();
+
+		await expect(
+			removeTaskFromSprint({ sprint_id: VALID_UUID }, ctx)
+		).rejects.toThrow(ValidationError);
+	});
+
+	it('should remove task from sprint', async () => {
+		mockApiClient.proxy.mockResolvedValue({
+			ok: true,
+			data: {
+				success: true,
+				sprint_id: VALID_UUID,
+				task_id: VALID_UUID_2,
+				committed_points: 16,
+				message: 'Task removed from sprint',
+			},
+		});
+		const ctx = createMockContext();
+
+		const result = await removeTaskFromSprint({
+			sprint_id: VALID_UUID,
+			task_id: VALID_UUID_2,
+		}, ctx);
+
+		expect(result.result).toMatchObject({
+			success: true,
+			committed_points: 16,
+		});
+	});
+});
+
+// ============================================================================
+// getSprintBacklog Tests
+// ============================================================================
+
+describe('getSprintBacklog', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should throw error for missing project_id', async () => {
+		const ctx = createMockContext();
+
+		await expect(getSprintBacklog({}, ctx)).rejects.toThrow(ValidationError);
+	});
+
+	it('should return available tasks', async () => {
+		mockApiClient.proxy.mockResolvedValue({
+			ok: true,
+			data: {
+				tasks: [
+					{ id: 'task-1', title: 'Task 1', priority: 2, status: 'pending' },
+					{ id: 'task-2', title: 'Task 2', priority: 3, status: 'backlog' },
+				],
+				total_count: 2,
+			},
+		});
+		const ctx = createMockContext();
+
+		const result = await getSprintBacklog({ project_id: VALID_UUID }, ctx);
+
+		expect(result.result).toMatchObject({
+			tasks: expect.any(Array),
+			total_count: 2,
+		});
+	});
+});
+
+// ============================================================================
+// getSprintVelocity Tests
+// ============================================================================
+
+describe('getSprintVelocity', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should throw error for missing project_id', async () => {
+		const ctx = createMockContext();
+
+		await expect(getSprintVelocity({}, ctx)).rejects.toThrow(ValidationError);
+	});
+
+	it('should return velocity metrics', async () => {
+		mockApiClient.proxy.mockResolvedValue({
+			ok: true,
+			data: {
+				sprints: [
+					{ sprint_number: 3, committed_points: 21, velocity_points: 18, completion_rate: 86 },
+					{ sprint_number: 2, committed_points: 18, velocity_points: 16, completion_rate: 89 },
+					{ sprint_number: 1, committed_points: 15, velocity_points: 15, completion_rate: 100 },
+				],
+				average_velocity: 16,
+				total_sprints: 3,
+			},
+		});
+		const ctx = createMockContext();
+
+		const result = await getSprintVelocity({ project_id: VALID_UUID }, ctx);
+
+		expect(result.result).toMatchObject({
+			average_velocity: 16,
+			total_sprints: 3,
+		});
+	});
+
+	it('should return empty metrics when no completed sprints', async () => {
+		mockApiClient.proxy.mockResolvedValue({
+			ok: true,
+			data: {
+				sprints: [],
+				average_velocity: 0,
+				total_sprints: 0,
+			},
+		});
+		const ctx = createMockContext();
+
+		const result = await getSprintVelocity({ project_id: VALID_UUID }, ctx);
+
+		expect(result.result).toMatchObject({
+			sprints: [],
+			average_velocity: 0,
+			total_sprints: 0,
+		});
+	});
+});