@vibescope/mcp-server 0.2.0 → 0.2.1

package/src/handlers/tasks.ts

@@ -18,16 +18,105 @@
 
 import type { Handler, HandlerRegistry } from './types.js';
 import {
-	validateRequired,
-	validateUUID,
-	validateTaskStatus,
-	validatePriority,
-	validateProgressPercentage,
-	validateEstimatedMinutes,
+	parseArgs,
+	uuidValidator,
+	taskStatusValidator,
+	priorityValidator,
+	progressValidator,
+	minutesValidator,
+	createEnumValidator,
 	ValidationError,
 } from '../validators.js';
 import { getApiClient } from '../api-client.js';
 
+// Valid task types
+const VALID_TASK_TYPES = [
+	'frontend', 'backend', 'database', 'feature', 'bugfix',
+	'design', 'mcp', 'testing', 'docs', 'infra', 'other'
+] as const;
+
+// ============================================================================
+// Argument Schemas
+// ============================================================================
+
+const getTasksSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	status: { type: 'string' as const, validate: taskStatusValidator },
+	limit: { type: 'number' as const, default: 50 },
+	offset: { type: 'number' as const, default: 0 },
+	search_query: { type: 'string' as const },
+	include_subtasks: { type: 'boolean' as const, default: false },
+	include_metadata: { type: 'boolean' as const, default: false },
+};
+
+const getNextTaskSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+const addTaskSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	title: { type: 'string' as const, required: true as const },
+	description: { type: 'string' as const },
+	priority: { type: 'number' as const, default: 3, validate: priorityValidator },
+	estimated_minutes: { type: 'number' as const, validate: minutesValidator },
+	blocking: { type: 'boolean' as const, default: false },
+	task_type: { type: 'string' as const, validate: createEnumValidator(VALID_TASK_TYPES) },
+};
+
+const updateTaskSchema = {
+	task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	title: { type: 'string' as const },
+	description: { type: 'string' as const },
+	priority: { type: 'number' as const, validate: priorityValidator },
+	status: { type: 'string' as const, validate: taskStatusValidator },
+	progress_percentage: { type: 'number' as const, validate: progressValidator },
+	progress_note: { type: 'string' as const },
+	estimated_minutes: { type: 'number' as const, validate: minutesValidator },
+	git_branch: { type: 'string' as const },
+	task_type: { type: 'string' as const, validate: createEnumValidator(VALID_TASK_TYPES) },
+};
+
+const completeTaskSchema = {
+	task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	summary: { type: 'string' as const },
+};
+
+const deleteTaskSchema = {
+	task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+const addTaskReferenceSchema = {
+	task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	url: { type: 'string' as const, required: true as const },
+	label: { type: 'string' as const },
+};
+
+const removeTaskReferenceSchema = {
+	task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	url: { type: 'string' as const, required: true as const },
+};
+
+const batchUpdateTasksSchema = {
+	updates: { type: 'array' as const, required: true as const },
+};
+
+const batchCompleteTasksSchema = {
+	completions: { type: 'array' as const, required: true as const },
+};
+
+const addSubtaskSchema = {
+	parent_task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	title: { type: 'string' as const, required: true as const },
+	description: { type: 'string' as const },
+	priority: { type: 'number' as const, validate: priorityValidator },
+	estimated_minutes: { type: 'number' as const, validate: minutesValidator },
+};
+
+const getSubtasksSchema = {
+	parent_task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	status: { type: 'string' as const, validate: taskStatusValidator },
+};
+
 // ============================================================================
 // Git workflow helpers (used by complete_task response)
 // ============================================================================
@@ -126,24 +215,12 @@ export function getValidationApprovedGitInstructions(
 // ============================================================================
 
 export const getTasks: Handler = async (args, ctx) => {
-	const { project_id, status, limit = 50, offset = 0, search_query, include_subtasks = false, include_metadata = false } = args as {
-		project_id: string;
-		status?: string;
-		limit?: number;
-		offset?: number;
-		search_query?: string;
-		include_subtasks?: boolean;
-		include_metadata?: boolean; // When true, returns all task fields; when false (default), only id/title/priority/status
-	};
-
-	validateRequired(project_id, 'project_id');
-	validateUUID(project_id, 'project_id');
-	validateTaskStatus(status);
+	const { project_id, status, limit, offset, search_query, include_subtasks, include_metadata } = parseArgs(args, getTasksSchema);
 
 	const api = getApiClient();
 	const response = await api.getTasks(project_id, {
 		status,
-		limit: Math.min(limit, 200),
+		limit: Math.min(limit ?? 50, 200),
 		offset,
 		include_subtasks,
 		search_query,
@@ -164,10 +241,7 @@ export const getTasks: Handler = async (args, ctx) => {
 };
 
 export const getNextTask: Handler = async (args, ctx) => {
-	const { project_id } = args as { project_id: string };
-
-	validateRequired(project_id, 'project_id');
-	validateUUID(project_id, 'project_id');
+	const { project_id } = parseArgs(args, getNextTaskSchema);
 
 	const api = getApiClient();
 	const response = await api.getNextTask(project_id, ctx.session.currentSessionId || undefined);
@@ -211,21 +285,7 @@ export const getNextTask: Handler = async (args, ctx) => {
 };
 
 export const addTask: Handler = async (args, ctx) => {
-	const { project_id, title, description, priority = 3, estimated_minutes, blocking = false, task_type } = args as {
-		project_id: string;
-		title: string;
-		description?: string;
-		priority?: number;
-		estimated_minutes?: number;
-		blocking?: boolean;
-		task_type?: string;
-	};
-
-	validateRequired(project_id, 'project_id');
-	validateRequired(title, 'title');
-	validateUUID(project_id, 'project_id');
-	validatePriority(priority);
-	validateEstimatedMinutes(estimated_minutes);
+	const { project_id, title, description, priority, estimated_minutes, blocking, task_type } = parseArgs(args, addTaskSchema);
 
 	const api = getApiClient();
 	const response = await api.createTask(project_id, {
@@ -235,6 +295,7 @@ export const addTask: Handler = async (args, ctx) => {
 		estimated_minutes,
 		blocking,
 		session_id: ctx.session.currentSessionId || undefined,
+		task_type,
 	});
 
 	if (!response.ok) {
@@ -257,25 +318,8 @@ export const addTask: Handler = async (args, ctx) => {
 };
 
 export const updateTask: Handler = async (args, ctx) => {
-	const { task_id, progress_note, ...updates } = args as {
-		task_id: string;
-		title?: string;
-		description?: string;
-		priority?: number;
-		status?: string;
-		progress_percentage?: number;
-		progress_note?: string;
-		estimated_minutes?: number;
-		git_branch?: string;
-		task_type?: string;
-	};
-
-	validateRequired(task_id, 'task_id');
-	validateUUID(task_id, 'task_id');
-	validateTaskStatus(updates.status);
-	validatePriority(updates.priority);
-	validateProgressPercentage(updates.progress_percentage);
-	validateEstimatedMinutes(updates.estimated_minutes);
+	const { task_id, title, description, priority, status, progress_percentage, progress_note, estimated_minutes, git_branch, task_type } = parseArgs(args, updateTaskSchema);
+	const updates = { title, description, priority, status, progress_percentage, estimated_minutes, git_branch, task_type };
 
 	const api = getApiClient();
 	const response = await api.updateTask(task_id, {
@@ -310,6 +354,16 @@ export const updateTask: Handler = async (args, ctx) => {
 				},
 			};
 		}
+		if (response.error?.includes('branch_conflict')) {
+			return {
+				result: {
+					error: 'branch_conflict',
+					message: response.error,
+					conflicting_task_id: (response.data as { conflicting_task_id?: string })?.conflicting_task_id,
+					conflicting_task_title: (response.data as { conflicting_task_title?: string })?.conflicting_task_title,
+				},
+			};
+		}
 		throw new Error(`Failed to update task: ${response.error}`);
 	}
 
@@ -337,13 +391,7 @@ export const updateTask: Handler = async (args, ctx) => {
 };
 
 export const completeTask: Handler = async (args, ctx) => {
-	const { task_id, summary } = args as {
-		task_id: string;
-		summary?: string;
-	};
-
-	validateRequired(task_id, 'task_id');
-	validateUUID(task_id, 'task_id');
+	const { task_id, summary } = parseArgs(args, completeTaskSchema);
 
 	const api = getApiClient();
 	const response = await api.completeTask(task_id, {
@@ -386,10 +434,7 @@ export const completeTask: Handler = async (args, ctx) => {
 };
 
 export const deleteTask: Handler = async (args, ctx) => {
-	const { task_id } = args as { task_id: string };
-
-	validateRequired(task_id, 'task_id');
-	validateUUID(task_id, 'task_id');
+	const { task_id } = parseArgs(args, deleteTaskSchema);
 
 	const api = getApiClient();
 	const response = await api.deleteTask(task_id);
@@ -402,11 +447,7 @@ export const deleteTask: Handler = async (args, ctx) => {
 };
 
 export const addTaskReference: Handler = async (args, ctx) => {
-	const { task_id, url, label } = args as { task_id: string; url: string; label?: string };
-
-	validateRequired(task_id, 'task_id');
-	validateUUID(task_id, 'task_id');
-	validateRequired(url, 'url');
+	const { task_id, url, label } = parseArgs(args, addTaskReferenceSchema);
 
 	const api = getApiClient();
 	const response = await api.addTaskReference(task_id, url, label);
@@ -427,11 +468,7 @@ export const addTaskReference: Handler = async (args, ctx) => {
 };
 
 export const removeTaskReference: Handler = async (args, ctx) => {
-	const { task_id, url } = args as { task_id: string; url: string };
-
-	validateRequired(task_id, 'task_id');
-	validateUUID(task_id, 'task_id');
-	validateRequired(url, 'url');
+	const { task_id, url } = parseArgs(args, removeTaskReferenceSchema);
 
 	const api = getApiClient();
 	const response = await api.removeTaskReference(task_id, url);
@@ -447,41 +484,33 @@ export const removeTaskReference: Handler = async (args, ctx) => {
 };
 
 export const batchUpdateTasks: Handler = async (args, ctx) => {
-	const { updates } = args as {
-		updates: Array<{
-			task_id: string;
-			status?: string;
-			progress_percentage?: number;
-			progress_note?: string;
-			priority?: number;
-		}>;
-	};
+	const { updates } = parseArgs(args, batchUpdateTasksSchema);
+
+	const typedUpdates = updates as Array<{
+		task_id: string;
+		status?: string;
+		progress_percentage?: number;
+		progress_note?: string;
+		priority?: number;
+	}>;
 
-	if (!updates || !Array.isArray(updates) || updates.length === 0) {
+	if (!Array.isArray(typedUpdates) || typedUpdates.length === 0) {
 		throw new ValidationError('updates must be a non-empty array', {
 			field: 'updates',
 			hint: 'Provide an array of task updates with at least one item',
 		});
 	}
 
-	if (updates.length > 50) {
+	if (typedUpdates.length > 50) {
 		throw new ValidationError('Too many updates. Maximum is 50 per batch.', {
 			field: 'updates',
 			hint: 'Split your updates into smaller batches',
 		});
 	}
 
-	// Validate all inputs first
-	for (const update of updates) {
-		validateRequired(update.task_id, 'task_id');
-		validateUUID(update.task_id, 'task_id');
-		validateTaskStatus(update.status);
-		validatePriority(update.priority);
-		validateProgressPercentage(update.progress_percentage);
-	}
-
+	// Individual item validation happens at API level
 	const api = getApiClient();
-	const response = await api.batchUpdateTasks(updates);
+	const response = await api.batchUpdateTasks(typedUpdates);
 
 	if (!response.ok) {
 		throw new Error(`Failed to batch update tasks: ${response.error}`);
@@ -490,42 +519,38 @@ export const batchUpdateTasks: Handler = async (args, ctx) => {
 	return {
 		result: {
 			success: response.data?.success || false,
-			total: updates.length,
+			total: typedUpdates.length,
 			succeeded: response.data?.updated_count || 0,
 		},
 	};
 };
 
 export const batchCompleteTasks: Handler = async (args, ctx) => {
-	const { completions } = args as {
-		completions: Array<{
-			task_id: string;
-			summary?: string;
-		}>;
-	};
+	const { completions } = parseArgs(args, batchCompleteTasksSchema);
 
-	if (!completions || !Array.isArray(completions) || completions.length === 0) {
+	const typedCompletions = completions as Array<{
+		task_id: string;
+		summary?: string;
+	}>;
+
+	if (!Array.isArray(typedCompletions) || typedCompletions.length === 0) {
 		throw new ValidationError('completions must be a non-empty array', {
 			field: 'completions',
 			hint: 'Provide an array of task completions with at least one item',
 		});
 	}
 
-	if (completions.length > 50) {
+	if (typedCompletions.length > 50) {
 		throw new ValidationError('Too many completions. Maximum is 50 per batch.', {
 			field: 'completions',
 			hint: 'Split your completions into smaller batches',
 		});
 	}
 
-	// Validate all inputs first
-	for (const completion of completions) {
-		validateRequired(completion.task_id, 'task_id');
-		validateUUID(completion.task_id, 'task_id');
-	}
+	// Individual item validation happens at API level
 
 	const api = getApiClient();
-	const response = await api.batchCompleteTasks(completions);
+	const response = await api.batchCompleteTasks(typedCompletions);
 
 	if (!response.ok) {
 		throw new Error(`Failed to batch complete tasks: ${response.error}`);
@@ -535,9 +560,9 @@ export const batchCompleteTasks: Handler = async (args, ctx) => {
 	return {
 		result: {
 			success: data?.success || false,
-			total: completions.length,
+			total: typedCompletions.length,
 			succeeded: data?.completed_count || 0,
-			failed: completions.length - (data?.completed_count || 0),
+			failed: typedCompletions.length - (data?.completed_count || 0),
 			next_task: data?.next_task,
 		},
 	};
@@ -548,19 +573,7 @@ export const batchCompleteTasks: Handler = async (args, ctx) => {
 // ============================================================================
 
 export const addSubtask: Handler = async (args, ctx) => {
-	const { parent_task_id, title, description, priority, estimated_minutes } = args as {
-		parent_task_id: string;
-		title: string;
-		description?: string;
-		priority?: number;
-		estimated_minutes?: number;
-	};
-
-	validateRequired(parent_task_id, 'parent_task_id');
-	validateUUID(parent_task_id, 'parent_task_id');
-	validateRequired(title, 'title');
-	if (priority !== undefined) validatePriority(priority);
-	if (estimated_minutes !== undefined) validateEstimatedMinutes(estimated_minutes);
+	const { parent_task_id, title, description, priority, estimated_minutes } = parseArgs(args, addSubtaskSchema);
 
 	const api = getApiClient();
 	const response = await api.addSubtask(parent_task_id, {
@@ -593,14 +606,7 @@ export const addSubtask: Handler = async (args, ctx) => {
 };
 
 export const getSubtasks: Handler = async (args, ctx) => {
-	const { parent_task_id, status } = args as {
-		parent_task_id: string;
-		status?: string;
-	};
-
-	validateRequired(parent_task_id, 'parent_task_id');
-	validateUUID(parent_task_id, 'parent_task_id');
-	if (status) validateTaskStatus(status);
+	const { parent_task_id, status } = parseArgs(args, getSubtasksSchema);
 
 	const api = getApiClient();
 	const response = await api.getSubtasks(parent_task_id, status);

package/src/handlers/validation.test.ts

@@ -309,7 +309,7 @@ describe('validateTask', () => {
 
 		await expect(
 			validateTask({ task_id: VALID_UUID }, ctx)
-		).rejects.toThrow('approved is required');
+		).rejects.toThrow('Missing required field: approved');
 	});
 
 	it('should throw error when task not found', async () => {

package/src/handlers/validation.ts

@@ -8,14 +8,27 @@
  */
 
 import type { Handler, HandlerRegistry } from './types.js';
-import { validateRequired, validateUUID } from '../validators.js';
+import { parseArgs, uuidValidator } from '../validators.js';
 import { getApiClient } from '../api-client.js';
 
-export const getTasksAwaitingValidation: Handler = async (args, ctx) => {
-	const { project_id } = args as { project_id: string };
+// Argument schemas for type-safe parsing
+const getTasksAwaitingValidationSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+const claimValidationSchema = {
+	task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
 
-	validateRequired(project_id, 'project_id');
-	validateUUID(project_id, 'project_id');
+const validateTaskSchema = {
+	task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	approved: { type: 'boolean' as const, required: true as const },
+	validation_notes: { type: 'string' as const },
+	skip_pr_check: { type: 'boolean' as const },
+};
+
+export const getTasksAwaitingValidation: Handler = async (args, _ctx) => {
+	const { project_id } = parseArgs(args, getTasksAwaitingValidationSchema);
 
 	const apiClient = getApiClient();
 	const response = await apiClient.getTasksAwaitingValidation(project_id);
@@ -28,10 +41,7 @@ export const getTasksAwaitingValidation: Handler = async (args, ctx) => {
 };
 
 export const claimValidation: Handler = async (args, ctx) => {
-	const { task_id } = args as { task_id: string };
-
-	validateRequired(task_id, 'task_id');
-	validateUUID(task_id, 'task_id');
+	const { task_id } = parseArgs(args, claimValidationSchema);
 
 	const { session } = ctx;
 	const currentSessionId = session.currentSessionId;
@@ -47,19 +57,7 @@ export const claimValidation: Handler = async (args, ctx) => {
 };
 
 export const validateTask: Handler = async (args, ctx) => {
-	const { task_id, validation_notes, approved, skip_pr_check } = args as {
-		task_id: string;
-		validation_notes?: string;
-		approved: boolean;
-		skip_pr_check?: boolean;
-	};
-
-	validateRequired(task_id, 'task_id');
-	validateUUID(task_id, 'task_id');
-
-	if (approved === undefined) {
-		throw new Error('approved is required');
-	}
+	const { task_id, approved, validation_notes, skip_pr_check } = parseArgs(args, validateTaskSchema);
 
 	const { session } = ctx;
 	const currentSessionId = session.currentSessionId;