@vibescope/mcp-server 0.2.0 → 0.2.2

package/src/handlers/tasks.ts

@@ -18,16 +18,107 @@
 
 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 },
+	worktree_path: { type: 'string' as const },
+	task_type: { type: 'string' as const, validate: createEnumValidator(VALID_TASK_TYPES) },
+	skip_worktree_requirement: { type: 'boolean' as const, default: false },
+};
+
+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 +217,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,
@@ -151,7 +230,7 @@ export const getTasks: Handler = async (args, ctx) => {
 	});
 
 	if (!response.ok) {
-		throw new Error(`Failed to fetch tasks: ${response.error}`);
+		return { result: { error: response.error || 'Failed to fetch tasks' }, isError: true };
 	}
 
 	return {
@@ -164,16 +243,13 @@ 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);
 
 	if (!response.ok) {
-		throw new Error(`Failed to get next task: ${response.error}`);
+		return { result: { error: response.error || 'Failed to get next task' }, isError: true };
 	}
 
 	const data = response.data;
@@ -211,21 +287,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,10 +297,11 @@ export const addTask: Handler = async (args, ctx) => {
 		estimated_minutes,
 		blocking,
 		session_id: ctx.session.currentSessionId || undefined,
+		task_type,
 	});
 
 	if (!response.ok) {
-		throw new Error(`Failed to add task: ${response.error}`);
+		return { result: { error: response.error || 'Failed to add task' }, isError: true };
 	}
 
 	const data = response.data;
@@ -257,25 +320,25 @@ 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;
-	};
+	const { task_id, title, description, priority, status, progress_percentage, progress_note, estimated_minutes, git_branch, worktree_path, task_type, skip_worktree_requirement } = parseArgs(args, updateTaskSchema);
+	const updates = { title, description, priority, status, progress_percentage, estimated_minutes, git_branch, worktree_path, task_type };
 
-	validateRequired(task_id, 'task_id');
-	validateUUID(task_id, 'task_id');
-	validateTaskStatus(updates.status);
-	validatePriority(updates.priority);
-	validateProgressPercentage(updates.progress_percentage);
-	validateEstimatedMinutes(updates.estimated_minutes);
+	// Enforce worktree creation: require git_branch when marking task as in_progress
+	// This ensures multi-agent collaboration works properly with isolated worktrees
+	if (status === 'in_progress' && !git_branch && !skip_worktree_requirement) {
+		return {
+			result: {
+				error: 'worktree_required',
+				message: 'git_branch is required when marking a task as in_progress. Create a worktree first and provide the branch name.',
+				hint: 'Create a worktree with: git worktree add ../PROJECT-task-TASKID -b feature/TASKID-description BASE_BRANCH, then call update_task with both status and git_branch parameters.',
+				worktree_example: {
+					command: `git worktree add ../worktree-${task_id.substring(0, 8)} -b feature/${task_id.substring(0, 8)}-task develop`,
+					then: `update_task(task_id: "${task_id}", status: "in_progress", git_branch: "feature/${task_id.substring(0, 8)}-task")`,
+				},
+				skip_option: 'If this project does not use git branching (trunk-based or no git workflow), pass skip_worktree_requirement: true',
+			},
+		};
+	}
 
 	const api = getApiClient();
 	const response = await api.updateTask(task_id, {
@@ -310,7 +373,17 @@ export const updateTask: Handler = async (args, ctx) => {
 				},
 			};
 		}
-		throw new Error(`Failed to update task: ${response.error}`);
+		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,
+				},
+			};
+		}
+		return { result: { error: response.error || 'Failed to update task' }, isError: true };
 	}
 
 	// Build result - include git workflow info when transitioning to in_progress
@@ -327,23 +400,11 @@ export const updateTask: Handler = async (args, ctx) => {
 		result.next_step = data.next_step;
 	}
 
-	// Warn if transitioning to in_progress without git_branch
-	if (updates.status === 'in_progress' && !updates.git_branch) {
-		result.warning = 'git_branch not set. For multi-agent collaboration, set git_branch when marking in_progress to track your worktree.';
-		result.hint = 'Call update_task again with git_branch parameter after creating your worktree.';
-	}
-
 	return { result };
 };
 
 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, {
@@ -352,12 +413,12 @@ export const completeTask: Handler = async (args, ctx) => {
 	});
 
 	if (!response.ok) {
-		throw new Error(`Failed to complete task: ${response.error}`);
+		return { result: { error: response.error || 'Failed to complete task' }, isError: true };
 	}
 
 	const data = response.data;
 	if (!data) {
-		throw new Error('No response data from complete task');
+		return { result: { error: 'No response data from complete task' }, isError: true };
 	}
 
 	// Build result matching expected format
@@ -386,27 +447,20 @@ 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);
 
 	if (!response.ok) {
-		throw new Error(`Failed to delete task: ${response.error}`);
+		return { result: { error: response.error || 'Failed to delete task' }, isError: true };
 	}
 
 	return { result: { success: true, deleted_id: task_id } };
 };
 
 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);
@@ -415,7 +469,7 @@ export const addTaskReference: Handler = async (args, ctx) => {
 		if (response.error?.includes('already exists')) {
 			return { result: { success: false, error: 'Reference with this URL already exists' } };
 		}
-		throw new Error(`Failed to add reference: ${response.error}`);
+		return { result: { error: response.error || 'Failed to add reference' }, isError: true };
 	}
 
 	return {
@@ -427,11 +481,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);
@@ -440,104 +490,92 @@ export const removeTaskReference: Handler = async (args, ctx) => {
 		if (response.error?.includes('not found')) {
 			return { result: { success: false, error: 'Reference with this URL not found' } };
 		}
-		throw new Error(`Failed to remove reference: ${response.error}`);
+		return { result: { error: response.error || 'Failed to remove reference' }, isError: true };
 	}
 
 	return { result: { success: true } };
 };
 
 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);
 
-	if (!updates || !Array.isArray(updates) || updates.length === 0) {
+	const typedUpdates = updates as Array<{
+		task_id: string;
+		status?: string;
+		progress_percentage?: number;
+		progress_note?: string;
+		priority?: number;
+	}>;
+
+	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}`);
+		return { result: { error: response.error || 'Failed to batch update tasks' }, isError: true };
 	}
 
 	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}`);
+		return { result: { error: response.error || 'Failed to batch complete tasks' }, isError: true };
 	}
 
 	const data = response.data;
 	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 +586,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, {
@@ -580,7 +606,7 @@ export const addSubtask: Handler = async (args, ctx) => {
 				},
 			};
 		}
-		throw new Error(`Failed to add subtask: ${response.error}`);
+		return { result: { error: response.error || 'Failed to add subtask' }, isError: true };
 	}
 
 	return {
@@ -593,20 +619,13 @@ 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);
 
 	if (!response.ok) {
-		throw new Error(`Failed to fetch subtasks: ${response.error}`);
+		return { result: { error: response.error || 'Failed to fetch subtasks' }, isError: true };
 	}
 
 	return {
@@ -621,6 +640,59 @@ export const getSubtasks: Handler = async (args, ctx) => {
 	};
 };
 
+// ============================================================================
+// Worktree Cleanup Handlers
+// ============================================================================
+
+const getStaleWorktreesSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+const clearWorktreePathSchema = {
+	task_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+export const getStaleWorktrees: Handler = async (args, ctx) => {
+	const { project_id } = parseArgs(args, getStaleWorktreesSchema);
+
+	const api = getApiClient();
+	const response = await api.getStaleWorktrees(project_id);
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to get stale worktrees' }, isError: true };
+	}
+
+	const data = response.data;
+	return {
+		result: {
+			project_id: data?.project_id,
+			project_name: data?.project_name,
+			stale_worktrees: data?.stale_worktrees || [],
+			count: data?.count || 0,
+			cleanup_instructions: data?.cleanup_instructions,
+		},
+	};
+};
+
+export const clearWorktreePath: Handler = async (args, ctx) => {
+	const { task_id } = parseArgs(args, clearWorktreePathSchema);
+
+	const api = getApiClient();
+	const response = await api.clearWorktreePath(task_id);
+
+	if (!response.ok) {
+		return { result: { error: response.error || 'Failed to clear worktree path' }, isError: true };
+	}
+
+	return {
+		result: {
+			success: true,
+			task_id,
+			message: 'Worktree path cleared. The worktree can now be safely removed if not already done.',
+		},
+	};
+};
+
 /**
  * Task handlers registry
  */
@@ -638,4 +710,7 @@ export const taskHandlers: HandlerRegistry = {
 	// Subtask handlers
 	add_subtask: addSubtask,
 	get_subtasks: getSubtasks,
+	// Worktree cleanup handlers
+	get_stale_worktrees: getStaleWorktrees,
+	clear_worktree_path: clearWorktreePath,
 };

package/src/handlers/tool-categories.test.ts

@@ -0,0 +1,66 @@
+/**
+ * Tests for the documentation generator
+ */
+
+import { describe, it, expect } from 'vitest';
+import { tools } from '../tools.js';
+import { TOOL_CATEGORIES } from './discovery.js';
+
+describe('Documentation Generator Prerequisites', () => {
+	it('should have tools defined', () => {
+		expect(tools).toBeDefined();
+		expect(Array.isArray(tools)).toBe(true);
+		expect(tools.length).toBeGreaterThan(0);
+	});
+
+	it('should have TOOL_CATEGORIES exported', () => {
+		expect(TOOL_CATEGORIES).toBeDefined();
+		expect(typeof TOOL_CATEGORIES).toBe('object');
+	});
+
+	it('should have all tools categorized', () => {
+		const categorizedTools = new Set<string>();
+		for (const category of Object.values(TOOL_CATEGORIES)) {
+			for (const tool of category.tools) {
+				categorizedTools.add(tool.name);
+			}
+		}
+
+		const uncategorized = tools.filter((t) => !categorizedTools.has(t.name)).map((t) => t.name);
+
+		expect(uncategorized).toEqual([]);
+	});
+
+	it('should have valid tool schemas', () => {
+		for (const tool of tools) {
+			expect(tool.name).toBeDefined();
+			expect(typeof tool.name).toBe('string');
+			expect(tool.description).toBeDefined();
+			expect(typeof tool.description).toBe('string');
+			expect(tool.inputSchema).toBeDefined();
+			expect(tool.inputSchema.type).toBe('object');
+		}
+	});
+
+	it('should have category tools that exist in tools array', () => {
+		const toolNames = new Set(tools.map((t) => t.name));
+
+		for (const [categoryName, category] of Object.entries(TOOL_CATEGORIES)) {
+			for (const toolRef of category.tools) {
+				expect(toolNames.has(toolRef.name)).toBe(true);
+			}
+		}
+	});
+
+	it('should have unique tool names', () => {
+		const names = tools.map((t) => t.name);
+		const uniqueNames = new Set(names);
+		expect(names.length).toBe(uniqueNames.size);
+	});
+
+	it('should have unique category names', () => {
+		const names = Object.keys(TOOL_CATEGORIES);
+		const uniqueNames = new Set(names);
+		expect(names.length).toBe(uniqueNames.size);
+	});
+});