@vibescope/mcp-server 0.2.0 → 0.2.2

package/src/handlers/sprints.ts

@@ -16,18 +16,92 @@
  */
 
 import type { Handler, HandlerRegistry } from './types.js';
-import { validateRequired, validateUUID, validateEnum } from '../validators.js';
+import { parseArgs, uuidValidator, createEnumValidator } 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 = ['planning', 'active', 'in_review', 'retrospective', 'completed', 'cancelled'] as const;
+const TASK_PHASES = ['pre', 'core', 'post'] as const;
+const DEPLOY_ENVIRONMENTS = ['development', 'staging', 'production'] as const;
+const VERSION_BUMPS = ['patch', 'minor', 'major'] as const;
+
+type SprintStatus = typeof SPRINT_STATUSES[number];
+type TaskPhase = typeof TASK_PHASES[number];
+type DeployEnvironment = typeof DEPLOY_ENVIRONMENTS[number];
+type VersionBump = typeof VERSION_BUMPS[number];
+
+// ============================================================================
+// Argument Schemas
+// ============================================================================
+
+const createSprintSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	title: { type: 'string' as const, required: true as const },
+	goal: { type: 'string' as const },
+	start_date: { type: 'string' as const, required: true as const },
+	end_date: { type: 'string' as const, required: true as const },
+	auto_deploy_on_completion: { type: 'boolean' as const },
+	deploy_environment: { type: 'string' as const, validate: createEnumValidator(DEPLOY_ENVIRONMENTS) },
+	deploy_version_bump: { type: 'string' as const, validate: createEnumValidator(VERSION_BUMPS) },
+};
+
+const updateSprintSchema = {
+	sprint_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	title: { type: 'string' as const },
+	goal: { type: 'string' as const },
+	start_date: { type: 'string' as const },
+	end_date: { type: 'string' as const },
+	auto_deploy_on_completion: { type: 'boolean' as const },
+	deploy_environment: { type: 'string' as const, validate: createEnumValidator(DEPLOY_ENVIRONMENTS) },
+	deploy_version_bump: { type: 'string' as const, validate: createEnumValidator(VERSION_BUMPS) },
+};
+
+const getSprintSchema = {
+	sprint_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	summary_only: { type: 'boolean' as const, default: false },
+};
+
+const getSprintsSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	status: { type: 'string' as const, validate: createEnumValidator(SPRINT_STATUSES) },
+	limit: { type: 'number' as const, default: 20 },
+	offset: { type: 'number' as const, default: 0 },
+};
+
+const deleteSprintSchema = {
+	sprint_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+const startSprintSchema = {
+	sprint_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+const completeSprintSchema = {
+	sprint_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	retrospective_notes: { type: 'string' as const },
+	skip_retrospective: { type: 'boolean' as const },
+};
+
+const addTaskToSprintSchema = {
+	sprint_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	story_points: { type: 'number' as const },
+	phase: { type: 'string' as const, validate: createEnumValidator(TASK_PHASES) },
+};
+
+const removeTaskFromSprintSchema = {
+	sprint_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+const getSprintBacklogSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	sprint_id: { type: 'string' as const, validate: uuidValidator },
+};
 
-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'];
+const getSprintVelocitySchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	limit: { type: 'number' as const, default: 10 },
+};
 
 export const createSprint: Handler = async (args, ctx) => {
 	const {
@@ -39,41 +113,19 @@ export const createSprint: Handler = async (args, ctx) => {
 		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');
-	}
+	} = parseArgs(args, createSprintSchema);
 
 	// 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');
+		return { result: { error: 'Invalid start_date format. Use YYYY-MM-DD' }, isError: true };
 	}
 	if (isNaN(endDateObj.getTime())) {
-		throw new Error('Invalid end_date format. Use YYYY-MM-DD');
+		return { result: { error: 'Invalid end_date format. Use YYYY-MM-DD' }, isError: true };
 	}
 	if (endDateObj < startDateObj) {
-		throw new Error('end_date must be on or after start_date');
+		return { result: { error: 'end_date must be on or after start_date' }, isError: true };
 	}
 
 	const { session } = ctx;
@@ -99,7 +151,7 @@ export const createSprint: Handler = async (args, ctx) => {
 	});
 
 	if (!response.ok) {
-		throw new Error(`Failed to create sprint: ${response.error}`);
+		return { result: { error: response.error || 'Failed to create sprint' }, isError: true };
 	}
 
 	return {
@@ -126,38 +178,19 @@ export const updateSprint: Handler = async (args, ctx) => {
 		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');
-	}
+	} = parseArgs(args, updateSprintSchema);
 
 	// 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');
+			return { result: { error: 'Invalid start_date format. Use YYYY-MM-DD' }, isError: true };
 		}
 	}
 	if (end_date) {
 		const endDateObj = new Date(end_date);
 		if (isNaN(endDateObj.getTime())) {
-			throw new Error('Invalid end_date format. Use YYYY-MM-DD');
+			return { result: { error: 'Invalid end_date format. Use YYYY-MM-DD' }, isError: true };
 		}
 	}
 
@@ -175,17 +208,14 @@ export const updateSprint: Handler = async (args, ctx) => {
 	});
 
 	if (!response.ok) {
-		throw new Error(`Failed to update sprint: ${response.error}`);
+		return { result: { error: response.error || 'Failed to update sprint' }, isError: true };
 	}
 
 	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 { sprint_id, summary_only } = parseArgs(args, getSprintSchema);
 
 	const apiClient = getApiClient();
 
@@ -220,26 +250,14 @@ export const getSprint: Handler = async (args, ctx) => {
 	}>('get_sprint', { sprint_id, summary_only });
 
 	if (!response.ok) {
-		throw new Error(`Failed to get sprint: ${response.error}`);
+		return { result: { error: response.error || 'Failed to get sprint' }, isError: true };
 	}
 
 	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 { project_id, status, limit, offset } = parseArgs(args, getSprintsSchema);
 
 	const apiClient = getApiClient();
 
@@ -261,22 +279,19 @@ export const getSprints: Handler = async (args, ctx) => {
 	}>('get_sprints', {
 		project_id,
 		status,
-		limit: Math.min(limit, 100),
+		limit: Math.min(limit ?? 20, 100),
 		offset,
 	});
 
 	if (!response.ok) {
-		throw new Error(`Failed to fetch sprints: ${response.error}`);
+		return { result: { error: response.error || 'Failed to fetch sprints' }, isError: true };
 	}
 
 	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 { sprint_id } = parseArgs(args, deleteSprintSchema);
 
 	const apiClient = getApiClient();
 
@@ -285,17 +300,14 @@ export const deleteSprint: Handler = async (args, ctx) => {
 	});
 
 	if (!response.ok) {
-		throw new Error(`Failed to delete sprint: ${response.error}`);
+		return { result: { error: response.error || 'Failed to delete sprint' }, isError: true };
 	}
 
 	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 { sprint_id } = parseArgs(args, startSprintSchema);
 
 	const apiClient = getApiClient();
 
@@ -308,21 +320,14 @@ export const startSprint: Handler = async (args, ctx) => {
 	}>('start_sprint', { sprint_id });
 
 	if (!response.ok) {
-		throw new Error(`Failed to start sprint: ${response.error}`);
+		return { result: { error: response.error || 'Failed to start sprint' }, isError: true };
 	}
 
 	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 { sprint_id, retrospective_notes, skip_retrospective } = parseArgs(args, completeSprintSchema);
 
 	const apiClient = getApiClient();
 
@@ -341,31 +346,17 @@ export const completeSprint: Handler = async (args, ctx) => {
 	});
 
 	if (!response.ok) {
-		throw new Error(`Failed to complete sprint: ${response.error}`);
+		return { result: { error: response.error || 'Failed to complete sprint' }, isError: true };
 	}
 
 	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');
-	}
+	const { sprint_id, task_id, story_points, phase } = parseArgs(args, addTaskToSprintSchema);
 
 	if (story_points !== undefined && (story_points < 0 || !Number.isInteger(story_points))) {
-		throw new Error('story_points must be a non-negative integer');
+		return { result: { error: 'story_points must be a non-negative integer' }, isError: true };
 	}
 
 	const apiClient = getApiClient();
@@ -385,22 +376,14 @@ export const addTaskToSprint: Handler = async (args, ctx) => {
 	});
 
 	if (!response.ok) {
-		throw new Error(`Failed to add task to sprint: ${response.error}`);
+		return { result: { error: response.error || 'Failed to add task to sprint' }, isError: true };
 	}
 
 	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 { sprint_id, task_id } = parseArgs(args, removeTaskFromSprintSchema);
 
 	const apiClient = getApiClient();
 
@@ -416,24 +399,14 @@ export const removeTaskFromSprint: Handler = async (args, ctx) => {
 	});
 
 	if (!response.ok) {
-		throw new Error(`Failed to remove task from sprint: ${response.error}`);
+		return { result: { error: response.error || 'Failed to remove task from sprint' }, isError: true };
 	}
 
 	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 { project_id, sprint_id } = parseArgs(args, getSprintBacklogSchema);
 
 	const apiClient = getApiClient();
 
@@ -453,20 +426,14 @@ export const getSprintBacklog: Handler = async (args, ctx) => {
 	});
 
 	if (!response.ok) {
-		throw new Error(`Failed to get sprint backlog: ${response.error}`);
+		return { result: { error: response.error || 'Failed to get sprint backlog' }, isError: true };
 	}
 
 	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 { project_id, limit } = parseArgs(args, getSprintVelocitySchema);
 
 	const apiClient = getApiClient();
 
@@ -482,11 +449,11 @@ export const getSprintVelocity: Handler = async (args, ctx) => {
 		total_sprints: number;
 	}>('get_sprint_velocity', {
 		project_id,
-		limit: Math.min(limit, 50),
+		limit: Math.min(limit ?? 10, 50),
 	});
 
 	if (!response.ok) {
-		throw new Error(`Failed to get sprint velocity: ${response.error}`);
+		return { result: { error: response.error || 'Failed to get sprint velocity' }, isError: true };
 	}
 
 	return { result: response.data };

package/src/handlers/tasks.test.ts

@@ -306,6 +306,7 @@ describe('updateTask', () => {
 			{
 				task_id: '123e4567-e89b-12d3-a456-426614174000',
 				status: 'in_progress',
+				git_branch: 'feature/test-branch',
 			},
 			ctx
 		);
@@ -324,6 +325,7 @@ describe('updateTask', () => {
 			{
 				task_id: '123e4567-e89b-12d3-a456-426614174000',
 				status: 'in_progress',
+				git_branch: 'feature/test-branch',
 			},
 			ctx
 		);
@@ -344,6 +346,7 @@ describe('updateTask', () => {
 			{
 				task_id: '123e4567-e89b-12d3-a456-426614174000',
 				status: 'in_progress',
+				git_branch: 'feature/test-branch',
 			},
 			ctx
 		);
@@ -353,7 +356,42 @@ describe('updateTask', () => {
 		});
 	});
 
-	it('should warn when setting in_progress without git_branch', async () => {
+	it('should return error when setting in_progress without git_branch', async () => {
+		const ctx = createMockContext();
+		const result = await updateTask(
+			{
+				task_id: '123e4567-e89b-12d3-a456-426614174000',
+				status: 'in_progress',
+			},
+			ctx
+		);
+
+		expect(result.result).toMatchObject({
+			error: 'worktree_required',
+			message: expect.stringContaining('git_branch is required'),
+			hint: expect.stringContaining('Create a worktree'),
+		});
+		// Should NOT call the API when worktree requirement fails
+		expect(mockApiClient.updateTask).not.toHaveBeenCalled();
+	});
+
+	it('should return worktree_example in error response', async () => {
+		const ctx = createMockContext();
+		const result = await updateTask(
+			{
+				task_id: '123e4567-e89b-12d3-a456-426614174000',
+				status: 'in_progress',
+			},
+			ctx
+		);
+
+		expect(result.result).toHaveProperty('worktree_example');
+		expect(result.result.worktree_example).toHaveProperty('command');
+		expect(result.result.worktree_example).toHaveProperty('then');
+		expect(result.result).toHaveProperty('skip_option');
+	});
+
+	it('should succeed when setting in_progress with git_branch', async () => {
 		mockApiClient.updateTask.mockResolvedValue({
 			ok: true,
 			data: { success: true },
@@ -364,18 +402,17 @@ describe('updateTask', () => {
 			{
 				task_id: '123e4567-e89b-12d3-a456-426614174000',
 				status: 'in_progress',
+				git_branch: 'feature/my-task',
 			},
 			ctx
 		);
 
-		expect(result.result).toMatchObject({
-			success: true,
-			warning: expect.stringContaining('git_branch not set'),
-			hint: expect.stringContaining('update_task again'),
-		});
+		expect(result.result).toMatchObject({ success: true });
+		expect(result.result).not.toHaveProperty('error');
+		expect(mockApiClient.updateTask).toHaveBeenCalled();
 	});
 
-	it('should not warn when setting in_progress with git_branch', async () => {
+	it('should succeed when using skip_worktree_requirement without git_branch', async () => {
 		mockApiClient.updateTask.mockResolvedValue({
 			ok: true,
 			data: { success: true },
@@ -386,16 +423,17 @@ describe('updateTask', () => {
 			{
 				task_id: '123e4567-e89b-12d3-a456-426614174000',
 				status: 'in_progress',
-				git_branch: 'feature/my-task',
+				skip_worktree_requirement: true,
 			},
 			ctx
 		);
 
 		expect(result.result).toMatchObject({ success: true });
-		expect(result.result).not.toHaveProperty('warning');
+		expect(result.result).not.toHaveProperty('error');
+		expect(mockApiClient.updateTask).toHaveBeenCalled();
 	});
 
-	it('should not warn when updating status other than in_progress', async () => {
+	it('should not require git_branch when updating status other than in_progress', async () => {
 		mockApiClient.updateTask.mockResolvedValue({
 			ok: true,
 			data: { success: true },
@@ -411,7 +449,28 @@ describe('updateTask', () => {
 		);
 
 		expect(result.result).toMatchObject({ success: true });
-		expect(result.result).not.toHaveProperty('warning');
+		expect(result.result).not.toHaveProperty('error');
+		expect(mockApiClient.updateTask).toHaveBeenCalled();
+	});
+
+	it('should not require git_branch when updating progress only', async () => {
+		mockApiClient.updateTask.mockResolvedValue({
+			ok: true,
+			data: { success: true },
+		});
+
+		const ctx = createMockContext();
+		const result = await updateTask(
+			{
+				task_id: '123e4567-e89b-12d3-a456-426614174000',
+				progress_percentage: 50,
+				progress_note: 'Halfway done',
+			},
+			ctx
+		);
+
+		expect(result.result).toMatchObject({ success: true });
+		expect(mockApiClient.updateTask).toHaveBeenCalled();
 	});
 });
 
@@ -480,16 +539,19 @@ describe('completeTask', () => {
 		);
 	});
 
-	it('should throw error when API returns error', async () => {
+	it('should return error when API returns error', async () => {
 		mockApiClient.completeTask.mockResolvedValue({
 			ok: false,
 			error: 'Task not found',
 		});
 
 		const ctx = createMockContext();
-		await expect(
-			completeTask({ task_id: '123e4567-e89b-12d3-a456-426614174000' }, ctx)
-		).rejects.toThrow('Failed to complete task: Task not found');
+		const result = await completeTask({ task_id: '123e4567-e89b-12d3-a456-426614174000' }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({
+			error: 'Task not found',
+		});
 	});
 });