@vibescope/mcp-server 0.0.1 → 0.2.0

package/src/handlers/sprints.ts

@@ -0,0 +1,510 @@
+/**
+ * Sprint Handlers
+ *
+ * Handles sprint-specific operations, leveraging bodies of work infrastructure:
+ * - create_sprint
+ * - update_sprint
+ * - get_sprint
+ * - get_sprints
+ * - delete_sprint
+ * - start_sprint
+ * - complete_sprint
+ * - add_task_to_sprint
+ * - remove_task_from_sprint
+ * - get_sprint_backlog
+ * - get_sprint_velocity
+ */
+
+import type { Handler, HandlerRegistry } from './types.js';
+import { validateRequired, validateUUID, validateEnum } from '../validators.js';
+import { getApiClient } from '../api-client.js';
+
+type SprintStatus = 'planning' | 'active' | 'in_review' | 'retrospective' | 'completed' | 'cancelled';
+type TaskPhase = 'pre' | 'core' | 'post';
+type DeployEnvironment = 'development' | 'staging' | 'production';
+type VersionBump = 'patch' | 'minor' | 'major';
+
+const SPRINT_STATUSES: SprintStatus[] = ['planning', 'active', 'in_review', 'retrospective', 'completed', 'cancelled'];
+const TASK_PHASES: TaskPhase[] = ['pre', 'core', 'post'];
+const DEPLOY_ENVIRONMENTS: DeployEnvironment[] = ['development', 'staging', 'production'];
+const VERSION_BUMPS: VersionBump[] = ['patch', 'minor', 'major'];
+
+export const createSprint: Handler = async (args, ctx) => {
+	const {
+		project_id,
+		title,
+		goal,
+		start_date,
+		end_date,
+		auto_deploy_on_completion,
+		deploy_environment,
+		deploy_version_bump,
+	} = args as {
+		project_id: string;
+		title: string;
+		goal?: string;
+		start_date: string;
+		end_date: string;
+		auto_deploy_on_completion?: boolean;
+		deploy_environment?: DeployEnvironment;
+		deploy_version_bump?: VersionBump;
+	};
+
+	validateRequired(project_id, 'project_id');
+	validateUUID(project_id, 'project_id');
+	validateRequired(title, 'title');
+	validateRequired(start_date, 'start_date');
+	validateRequired(end_date, 'end_date');
+
+	if (deploy_environment) {
+		validateEnum(deploy_environment, DEPLOY_ENVIRONMENTS, 'deploy_environment');
+	}
+	if (deploy_version_bump) {
+		validateEnum(deploy_version_bump, VERSION_BUMPS, 'deploy_version_bump');
+	}
+
+	// Validate date format and order
+	const startDateObj = new Date(start_date);
+	const endDateObj = new Date(end_date);
+	if (isNaN(startDateObj.getTime())) {
+		throw new Error('Invalid start_date format. Use YYYY-MM-DD');
+	}
+	if (isNaN(endDateObj.getTime())) {
+		throw new Error('Invalid end_date format. Use YYYY-MM-DD');
+	}
+	if (endDateObj < startDateObj) {
+		throw new Error('end_date must be on or after start_date');
+	}
+
+	const { session } = ctx;
+	const apiClient = getApiClient();
+
+	const response = await apiClient.proxy<{
+		success: boolean;
+		sprint_id: string;
+		sprint_number: number;
+	}>('create_sprint', {
+		project_id,
+		title,
+		goal,
+		start_date,
+		end_date,
+		auto_deploy_on_completion,
+		deploy_environment,
+		deploy_version_bump,
+	}, {
+		session_id: session.currentSessionId,
+		persona: session.currentPersona,
+		instance_id: session.instanceId
+	});
+
+	if (!response.ok) {
+		throw new Error(`Failed to create sprint: ${response.error}`);
+	}
+
+	return {
+		result: {
+			success: true,
+			sprint_id: response.data?.sprint_id,
+			sprint_number: response.data?.sprint_number,
+			title,
+			status: 'planning',
+			start_date,
+			end_date,
+			message: 'Sprint created in planning status. Add tasks with add_task_to_sprint, then call start_sprint when ready.',
+		},
+	};
+};
+
+export const updateSprint: Handler = async (args, ctx) => {
+	const {
+		sprint_id,
+		title,
+		goal,
+		start_date,
+		end_date,
+		auto_deploy_on_completion,
+		deploy_environment,
+		deploy_version_bump,
+	} = args as {
+		sprint_id: string;
+		title?: string;
+		goal?: string;
+		start_date?: string;
+		end_date?: string;
+		auto_deploy_on_completion?: boolean;
+		deploy_environment?: DeployEnvironment;
+		deploy_version_bump?: VersionBump;
+	};
+
+	validateRequired(sprint_id, 'sprint_id');
+	validateUUID(sprint_id, 'sprint_id');
+
+	if (deploy_environment) {
+		validateEnum(deploy_environment, DEPLOY_ENVIRONMENTS, 'deploy_environment');
+	}
+	if (deploy_version_bump) {
+		validateEnum(deploy_version_bump, VERSION_BUMPS, 'deploy_version_bump');
+	}
+
+	// Validate dates if provided
+	if (start_date) {
+		const startDateObj = new Date(start_date);
+		if (isNaN(startDateObj.getTime())) {
+			throw new Error('Invalid start_date format. Use YYYY-MM-DD');
+		}
+	}
+	if (end_date) {
+		const endDateObj = new Date(end_date);
+		if (isNaN(endDateObj.getTime())) {
+			throw new Error('Invalid end_date format. Use YYYY-MM-DD');
+		}
+	}
+
+	const apiClient = getApiClient();
+
+	const response = await apiClient.proxy<{ success: boolean }>('update_sprint', {
+		sprint_id,
+		title,
+		goal,
+		start_date,
+		end_date,
+		auto_deploy_on_completion,
+		deploy_environment,
+		deploy_version_bump,
+	});
+
+	if (!response.ok) {
+		throw new Error(`Failed to update sprint: ${response.error}`);
+	}
+
+	return { result: { success: true, sprint_id } };
+};
+
+export const getSprint: Handler = async (args, ctx) => {
+	const { sprint_id, summary_only = false } = args as { sprint_id: string; summary_only?: boolean };
+
+	validateRequired(sprint_id, 'sprint_id');
+	validateUUID(sprint_id, 'sprint_id');
+
+	const apiClient = getApiClient();
+
+	// Response type varies based on summary_only
+	const response = await apiClient.proxy<{
+		id: string;
+		title: string;
+		goal?: string;
+		sprint_number: number;
+		sprint_status: SprintStatus;
+		start_date: string;
+		end_date: string;
+		progress_percentage: number;
+		velocity_points: number;
+		committed_points: number;
+		// Full response includes task arrays
+		pre_tasks?: unknown[];
+		core_tasks?: unknown[];
+		post_tasks?: unknown[];
+		total_tasks?: number;
+		// Summary response includes counts and next task
+		task_counts?: {
+			pre: { total: number; completed: number };
+			core: { total: number; completed: number };
+			post: { total: number; completed: number };
+			total: number;
+			completed: number;
+			in_progress: number;
+		};
+		current_task?: { id: string; title: string } | null;
+		next_task?: { id: string; title: string; priority: number } | null;
+	}>('get_sprint', { sprint_id, summary_only });
+
+	if (!response.ok) {
+		throw new Error(`Failed to get sprint: ${response.error}`);
+	}
+
+	return { result: response.data };
+};
+
+export const getSprints: Handler = async (args, ctx) => {
+	const { project_id, status, limit = 20, offset = 0 } = args as {
+		project_id: string;
+		status?: SprintStatus;
+		limit?: number;
+		offset?: number;
+	};
+
+	validateRequired(project_id, 'project_id');
+	validateUUID(project_id, 'project_id');
+
+	if (status) {
+		validateEnum(status, SPRINT_STATUSES, 'status');
+	}
+
+	const apiClient = getApiClient();
+
+	const response = await apiClient.proxy<{
+		sprints: Array<{
+			id: string;
+			title: string;
+			goal?: string;
+			sprint_number: number;
+			sprint_status: SprintStatus;
+			start_date: string;
+			end_date: string;
+			progress_percentage: number;
+			velocity_points: number;
+			committed_points: number;
+		}>;
+		total_count: number;
+		has_more: boolean;
+	}>('get_sprints', {
+		project_id,
+		status,
+		limit: Math.min(limit, 100),
+		offset,
+	});
+
+	if (!response.ok) {
+		throw new Error(`Failed to fetch sprints: ${response.error}`);
+	}
+
+	return { result: response.data };
+};
+
+export const deleteSprint: Handler = async (args, ctx) => {
+	const { sprint_id } = args as { sprint_id: string };
+
+	validateRequired(sprint_id, 'sprint_id');
+	validateUUID(sprint_id, 'sprint_id');
+
+	const apiClient = getApiClient();
+
+	const response = await apiClient.proxy<{ success: boolean }>('delete_sprint', {
+		sprint_id
+	});
+
+	if (!response.ok) {
+		throw new Error(`Failed to delete sprint: ${response.error}`);
+	}
+
+	return { result: { success: true, message: 'Sprint deleted. Tasks are preserved.' } };
+};
+
+export const startSprint: Handler = async (args, ctx) => {
+	const { sprint_id } = args as { sprint_id: string };
+
+	validateRequired(sprint_id, 'sprint_id');
+	validateUUID(sprint_id, 'sprint_id');
+
+	const apiClient = getApiClient();
+
+	const response = await apiClient.proxy<{
+		success: boolean;
+		sprint_id: string;
+		sprint_status: SprintStatus;
+		committed_points: number;
+		message: string;
+	}>('start_sprint', { sprint_id });
+
+	if (!response.ok) {
+		throw new Error(`Failed to start sprint: ${response.error}`);
+	}
+
+	return { result: response.data };
+};
+
+export const completeSprint: Handler = async (args, ctx) => {
+	const { sprint_id, retrospective_notes, skip_retrospective } = args as {
+		sprint_id: string;
+		retrospective_notes?: string;
+		skip_retrospective?: boolean;
+	};
+
+	validateRequired(sprint_id, 'sprint_id');
+	validateUUID(sprint_id, 'sprint_id');
+
+	const apiClient = getApiClient();
+
+	const response = await apiClient.proxy<{
+		success: boolean;
+		sprint_id: string;
+		sprint_status: SprintStatus;
+		velocity_points: number;
+		committed_points: number;
+		deployment_triggered?: boolean;
+		message: string;
+	}>('complete_sprint', {
+		sprint_id,
+		retrospective_notes,
+		skip_retrospective,
+	});
+
+	if (!response.ok) {
+		throw new Error(`Failed to complete sprint: ${response.error}`);
+	}
+
+	return { result: response.data };
+};
+
+export const addTaskToSprint: Handler = async (args, ctx) => {
+	const { sprint_id, task_id, story_points, phase } = args as {
+		sprint_id: string;
+		task_id: string;
+		story_points?: number;
+		phase?: TaskPhase;
+	};
+
+	validateRequired(sprint_id, 'sprint_id');
+	validateUUID(sprint_id, 'sprint_id');
+	validateRequired(task_id, 'task_id');
+	validateUUID(task_id, 'task_id');
+
+	if (phase) {
+		validateEnum(phase, TASK_PHASES, 'phase');
+	}
+
+	if (story_points !== undefined && (story_points < 0 || !Number.isInteger(story_points))) {
+		throw new Error('story_points must be a non-negative integer');
+	}
+
+	const apiClient = getApiClient();
+
+	const response = await apiClient.proxy<{
+		success: boolean;
+		sprint_id: string;
+		task_id: string;
+		story_points?: number;
+		phase: TaskPhase;
+		committed_points: number;
+	}>('add_task_to_sprint', {
+		sprint_id,
+		task_id,
+		story_points,
+		phase: phase || 'core',
+	});
+
+	if (!response.ok) {
+		throw new Error(`Failed to add task to sprint: ${response.error}`);
+	}
+
+	return { result: response.data };
+};
+
+export const removeTaskFromSprint: Handler = async (args, ctx) => {
+	const { sprint_id, task_id } = args as {
+		sprint_id: string;
+		task_id: string;
+	};
+
+	validateRequired(sprint_id, 'sprint_id');
+	validateUUID(sprint_id, 'sprint_id');
+	validateRequired(task_id, 'task_id');
+	validateUUID(task_id, 'task_id');
+
+	const apiClient = getApiClient();
+
+	const response = await apiClient.proxy<{
+		success: boolean;
+		sprint_id: string;
+		task_id: string;
+		committed_points: number;
+		message: string;
+	}>('remove_task_from_sprint', {
+		sprint_id,
+		task_id,
+	});
+
+	if (!response.ok) {
+		throw new Error(`Failed to remove task from sprint: ${response.error}`);
+	}
+
+	return { result: response.data };
+};
+
+export const getSprintBacklog: Handler = async (args, ctx) => {
+	const { project_id, sprint_id } = args as {
+		project_id: string;
+		sprint_id?: string;
+	};
+
+	validateRequired(project_id, 'project_id');
+	validateUUID(project_id, 'project_id');
+
+	if (sprint_id) {
+		validateUUID(sprint_id, 'sprint_id');
+	}
+
+	const apiClient = getApiClient();
+
+	const response = await apiClient.proxy<{
+		tasks: Array<{
+			id: string;
+			title: string;
+			priority: number;
+			status: string;
+			story_points?: number;
+			estimated_minutes?: number;
+		}>;
+		total_count: number;
+	}>('get_sprint_backlog', {
+		project_id,
+		sprint_id,
+	});
+
+	if (!response.ok) {
+		throw new Error(`Failed to get sprint backlog: ${response.error}`);
+	}
+
+	return { result: response.data };
+};
+
+export const getSprintVelocity: Handler = async (args, ctx) => {
+	const { project_id, limit = 10 } = args as {
+		project_id: string;
+		limit?: number;
+	};
+
+	validateRequired(project_id, 'project_id');
+	validateUUID(project_id, 'project_id');
+
+	const apiClient = getApiClient();
+
+	const response = await apiClient.proxy<{
+		sprints: Array<{
+			sprint_number: number;
+			title: string;
+			committed_points: number;
+			velocity_points: number;
+			completion_rate: number;
+		}>;
+		average_velocity: number;
+		total_sprints: number;
+	}>('get_sprint_velocity', {
+		project_id,
+		limit: Math.min(limit, 50),
+	});
+
+	if (!response.ok) {
+		throw new Error(`Failed to get sprint velocity: ${response.error}`);
+	}
+
+	return { result: response.data };
+};
+
+/**
+ * Sprint handlers registry
+ */
+export const sprintHandlers: HandlerRegistry = {
+	create_sprint: createSprint,
+	update_sprint: updateSprint,
+	get_sprint: getSprint,
+	get_sprints: getSprints,
+	delete_sprint: deleteSprint,
+	start_sprint: startSprint,
+	complete_sprint: completeSprint,
+	add_task_to_sprint: addTaskToSprint,
+	remove_task_from_sprint: removeTaskFromSprint,
+	get_sprint_backlog: getSprintBacklog,
+	get_sprint_velocity: getSprintVelocity,
+};