@vibescope/mcp-server 0.2.0 → 0.2.2

package/src/handlers/project.ts

@@ -10,14 +10,60 @@
  */
 
 import type { Handler, HandlerRegistry } from './types.js';
-import { validateRequired, validateUUID, validateProjectStatus } from '../validators.js';
+import {
+	parseArgs,
+	uuidValidator,
+	projectStatusValidator,
+	createEnumValidator,
+	VALID_PROJECT_STATUSES,
+} from '../validators.js';
 import { getApiClient } from '../api-client.js';
 
-export const getProjectContext: Handler = async (args, ctx) => {
-	const { project_id, git_url } = args as {
-		project_id?: string;
-		git_url?: string;
-	};
+const VALID_GIT_WORKFLOWS = ['none', 'trunk-based', 'github-flow', 'git-flow'] as const;
+type GitWorkflow = typeof VALID_GIT_WORKFLOWS[number];
+
+// Argument schemas for type-safe parsing
+const getProjectContextSchema = {
+	project_id: { type: 'string' as const, validate: uuidValidator },
+	git_url: { type: 'string' as const },
+};
+
+const getGitWorkflowSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	task_id: { type: 'string' as const, validate: uuidValidator },
+};
+
+const createProjectSchema = {
+	name: { type: 'string' as const, required: true as const },
+	description: { type: 'string' as const },
+	goal: { type: 'string' as const },
+	git_url: { type: 'string' as const },
+	tech_stack: { type: 'array' as const },
+};
+
+const updateProjectSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	name: { type: 'string' as const },
+	description: { type: 'string' as const },
+	goal: { type: 'string' as const },
+	git_url: { type: 'string' as const },
+	tech_stack: { type: 'array' as const },
+	status: { type: 'string' as const, validate: projectStatusValidator },
+	git_workflow: { type: 'string' as const, validate: createEnumValidator(VALID_GIT_WORKFLOWS) },
+	git_main_branch: { type: 'string' as const },
+	git_develop_branch: { type: 'string' as const },
+	git_auto_branch: { type: 'boolean' as const },
+	git_auto_tag: { type: 'boolean' as const },
+	deployment_instructions: { type: 'string' as const },
+};
+
+const updateProjectReadmeSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	readme_content: { type: 'string' as const, required: true as const },
+};
+
+export const getProjectContext: Handler = async (args, _ctx) => {
+	const { project_id, git_url } = parseArgs(args, getProjectContextSchema);
 
 	const apiClient = getApiClient();
 
@@ -26,7 +72,7 @@ export const getProjectContext: Handler = async (args, ctx) => {
 		const response = await apiClient.listProjects();
 
 		if (!response.ok) {
-			throw new Error(response.error || 'Failed to fetch projects');
+			return { result: { error: response.error || 'Failed to fetch projects' }, isError: true };
 		}
 
 		return { result: { projects: response.data?.projects || [] } };
@@ -36,7 +82,7 @@ export const getProjectContext: Handler = async (args, ctx) => {
 	const response = await apiClient.getProject(project_id || 'by-git-url', git_url);
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to fetch project');
+		return { result: { error: response.error || 'Failed to fetch project' }, isError: true };
 	}
 
 	if (!response.data?.found) {
@@ -51,35 +97,21 @@ export const getProjectContext: Handler = async (args, ctx) => {
 	return { result: response.data };
 };
 
-export const getGitWorkflow: Handler = async (args, ctx) => {
-	const { project_id, task_id } = args as {
-		project_id: string;
-		task_id?: string;
-	};
-
-	validateRequired(project_id, 'project_id');
-	validateUUID(project_id, 'project_id');
+export const getGitWorkflow: Handler = async (args, _ctx) => {
+	const { project_id, task_id } = parseArgs(args, getGitWorkflowSchema);
 
 	const apiClient = getApiClient();
 	const response = await apiClient.getGitWorkflow(project_id, task_id);
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to get git workflow');
+		return { result: { error: response.error || 'Failed to get git workflow' }, isError: true };
 	}
 
 	return { result: response.data };
 };
 
-export const createProject: Handler = async (args, ctx) => {
-	const { name, description, goal, git_url, tech_stack } = args as {
-		name: string;
-		description?: string;
-		goal?: string;
-		git_url?: string;
-		tech_stack?: string[];
-	};
-
-	validateRequired(name, 'name');
+export const createProject: Handler = async (args, _ctx) => {
+	const { name, description, goal, git_url, tech_stack } = parseArgs(args, createProjectSchema);
 
 	const apiClient = getApiClient();
 	const response = await apiClient.createProject({
@@ -87,64 +119,64 @@ export const createProject: Handler = async (args, ctx) => {
 		description,
 		goal,
 		git_url,
-		tech_stack
+		tech_stack: tech_stack as string[] | undefined
 	});
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to create project');
+		return { result: { error: response.error || 'Failed to create project' }, isError: true };
 	}
 
 	return { result: response.data };
 };
 
-export const updateProject: Handler = async (args, ctx) => {
-	const { project_id, ...updates } = args as {
-		project_id: string;
-		name?: string;
-		description?: string;
-		goal?: string;
-		git_url?: string;
-		tech_stack?: string[];
-		status?: string;
-		git_workflow?: 'none' | 'trunk-based' | 'github-flow' | 'git-flow';
-		git_main_branch?: string;
-		git_develop_branch?: string;
-		git_auto_branch?: boolean;
-		git_auto_tag?: boolean;
-		git_auto_commit_on_complete?: boolean;
-		git_auto_pr_on_complete?: boolean;
-		deployment_instructions?: string;
-	};
-
-	validateRequired(project_id, 'project_id');
-	validateUUID(project_id, 'project_id');
-	validateProjectStatus(updates.status);
+export const updateProject: Handler = async (args, _ctx) => {
+	const {
+		project_id,
+		name,
+		description,
+		goal,
+		git_url,
+		tech_stack,
+		status,
+		git_workflow,
+		git_main_branch,
+		git_develop_branch,
+		git_auto_branch,
+		git_auto_tag,
+		deployment_instructions
+	} = parseArgs(args, updateProjectSchema);
 
 	const apiClient = getApiClient();
-	const response = await apiClient.updateProject(project_id, updates);
+	const response = await apiClient.updateProject(project_id, {
+		name,
+		description,
+		goal,
+		git_url,
+		tech_stack: tech_stack as string[] | undefined,
+		status: status as typeof VALID_PROJECT_STATUSES[number] | undefined,
+		git_workflow: git_workflow as GitWorkflow | undefined,
+		git_main_branch,
+		git_develop_branch,
+		git_auto_branch,
+		git_auto_tag,
+		deployment_instructions
+	});
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to update project');
+		return { result: { error: response.error || 'Failed to update project' }, isError: true };
 	}
 
 	return { result: response.data };
 };
 
-export const updateProjectReadme: Handler = async (args, ctx) => {
-	const { project_id, readme_content } = args as {
-		project_id: string;
-		readme_content: string;
-	};
-
-	validateRequired(project_id, 'project_id');
-	validateUUID(project_id, 'project_id');
-	validateRequired(readme_content, 'readme_content');
+export const updateProjectReadme: Handler = async (args, _ctx) => {
+	const { project_id, readme_content } = parseArgs(args, updateProjectReadmeSchema);
 
 	const apiClient = getApiClient();
 	const response = await apiClient.updateProjectReadme(project_id, readme_content);
 
 	if (!response.ok) {
-		throw new Error(response.error || 'Failed to update README');
+		return { result: { error: response.error || 'Failed to update README' }, isError: true };
 	}
 
 	return { result: response.data };

package/src/handlers/requests.test.ts

@@ -87,19 +87,22 @@ describe('getPendingRequests', () => {
 		);
 	});
 
-	it('should throw error when API call fails', async () => {
+	it('should return error when API call fails', async () => {
 		mockApiClient.getPendingRequests.mockResolvedValue({
 			ok: false,
 			error: 'Query failed',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			getPendingRequests(
-				{ project_id: '123e4567-e89b-12d3-a456-426614174000' },
-				ctx
-			)
-		).rejects.toThrow('Failed to get pending requests: Query failed');
+		const result = await getPendingRequests(
+			{ project_id: '123e4567-e89b-12d3-a456-426614174000' },
+			ctx
+		);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({
+			error: 'Query failed',
+		});
 	});
 });
 
@@ -159,16 +162,19 @@ describe('acknowledgeRequest', () => {
 		);
 	});
 
-	it('should throw error when API call fails', async () => {
+	it('should return error when API call fails', async () => {
 		mockApiClient.acknowledgeRequest.mockResolvedValue({
 			ok: false,
 			error: 'Update failed',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			acknowledgeRequest({ request_id: '123e4567-e89b-12d3-a456-426614174000' }, ctx)
-		).rejects.toThrow('Failed to acknowledge request: Update failed');
+		const result = await acknowledgeRequest({ request_id: '123e4567-e89b-12d3-a456-426614174000' }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({
+			error: 'Update failed',
+		});
 	});
 });
 
@@ -246,18 +252,21 @@ describe('answerQuestion', () => {
 		);
 	});
 
-	it('should throw error when API call fails', async () => {
+	it('should return error when API call fails', async () => {
 		mockApiClient.answerQuestion.mockResolvedValue({
 			ok: false,
 			error: 'Update failed',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			answerQuestion({
-				request_id: '123e4567-e89b-12d3-a456-426614174000',
-				answer: 'Answer',
-			}, ctx)
-		).rejects.toThrow('Failed to answer question: Update failed');
+		const result = await answerQuestion({
+			request_id: '123e4567-e89b-12d3-a456-426614174000',
+			answer: 'Answer',
+		}, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({
+			error: 'Update failed',
+		});
 	});
 });

package/src/handlers/requests.ts

@@ -10,14 +10,25 @@
  */
 
 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 getPendingRequests: Handler = async (args, ctx) => {
-	const { project_id } = args as { project_id: string };
+// Argument schemas for type-safe parsing
+const getPendingRequestsSchema = {
+	project_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
 
-	validateRequired(project_id, 'project_id');
-	validateUUID(project_id, 'project_id');
+const acknowledgeRequestSchema = {
+	request_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+};
+
+const answerQuestionSchema = {
+	request_id: { type: 'string' as const, required: true as const, validate: uuidValidator },
+	answer: { type: 'string' as const, required: true as const },
+};
+
+export const getPendingRequests: Handler = async (args, ctx) => {
+	const { project_id } = parseArgs(args, getPendingRequestsSchema);
 
 	const { session } = ctx;
 	const apiClient = getApiClient();
@@ -25,7 +36,7 @@ export const getPendingRequests: Handler = async (args, ctx) => {
 	const response = await apiClient.getPendingRequests(project_id, session.currentSessionId || undefined);
 
 	if (!response.ok) {
-		throw new Error(`Failed to get pending requests: ${response.error}`);
+		return { result: { error: response.error || 'Failed to get pending requests' }, isError: true };
 	}
 
 	return {
@@ -37,10 +48,7 @@ export const getPendingRequests: Handler = async (args, ctx) => {
 };
 
 export const acknowledgeRequest: Handler = async (args, ctx) => {
-	const { request_id } = args as { request_id: string };
-
-	validateRequired(request_id, 'request_id');
-	validateUUID(request_id, 'request_id');
+	const { request_id } = parseArgs(args, acknowledgeRequestSchema);
 
 	const { session } = ctx;
 	const apiClient = getApiClient();
@@ -48,7 +56,7 @@ export const acknowledgeRequest: Handler = async (args, ctx) => {
 	const response = await apiClient.acknowledgeRequest(request_id, session.currentSessionId || undefined);
 
 	if (!response.ok) {
-		throw new Error(`Failed to acknowledge request: ${response.error}`);
+		return { result: { error: response.error || 'Failed to acknowledge request' }, isError: true };
 	}
 
 	return {
@@ -59,11 +67,7 @@ export const acknowledgeRequest: Handler = async (args, ctx) => {
 };
 
 export const answerQuestion: Handler = async (args, ctx) => {
-	const { request_id, answer } = args as { request_id: string; answer: string };
-
-	validateRequired(request_id, 'request_id');
-	validateRequired(answer, 'answer');
-	validateUUID(request_id, 'request_id');
+	const { request_id, answer } = parseArgs(args, answerQuestionSchema);
 
 	const { session } = ctx;
 	const apiClient = getApiClient();
@@ -71,7 +75,7 @@ export const answerQuestion: Handler = async (args, ctx) => {
 	const response = await apiClient.answerQuestion(request_id, answer, session.currentSessionId || undefined);
 
 	if (!response.ok) {
-		throw new Error(`Failed to answer question: ${response.error}`);
+		return { result: { error: response.error || 'Failed to answer question' }, isError: true };
 	}
 
 	return {

package/src/handlers/roles.test.ts

@@ -0,0 +1,303 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import {
+	getRoleSettings,
+	updateRoleSettings,
+	setSessionRole,
+	getAgentsByRole,
+} from './roles.js';
+import { createMockContext } from './__test-utils__.js';
+import { mockApiClient } from './__test-setup__.js';
+
+// ============================================================================
+// getRoleSettings Tests
+// ============================================================================
+
+describe('getRoleSettings', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should return error for missing project_id', async () => {
+		const ctx = createMockContext();
+
+		const result = await getRoleSettings({}, ctx);
+
+		expect(result.result).toMatchObject({
+			error: 'project_id is required',
+		});
+	});
+
+	it('should get role settings successfully', async () => {
+		const mockRoles = [
+			{ role: 'developer', enabled: true, display_name: 'Developer' },
+			{ role: 'validator', enabled: true, display_name: 'Validator' },
+		];
+		mockApiClient.proxy.mockResolvedValue({
+			ok: true,
+			data: { roles: mockRoles },
+		});
+		const ctx = createMockContext();
+
+		const result = await getRoleSettings(
+			{ project_id: '123e4567-e89b-12d3-a456-426614174000' },
+			ctx
+		);
+
+		expect(result.result).toMatchObject({ roles: mockRoles });
+		expect(mockApiClient.proxy).toHaveBeenCalledWith(
+			'get_role_settings',
+			{ project_id: '123e4567-e89b-12d3-a456-426614174000' }
+		);
+	});
+
+	it('should return error from API', async () => {
+		mockApiClient.proxy.mockResolvedValue({
+			ok: false,
+			error: 'Project not found',
+		});
+		const ctx = createMockContext();
+
+		const result = await getRoleSettings(
+			{ project_id: '123e4567-e89b-12d3-a456-426614174000' },
+			ctx
+		);
+
+		expect(result.result).toMatchObject({
+			error: 'Project not found',
+		});
+	});
+});
+
+// ============================================================================
+// updateRoleSettings Tests
+// ============================================================================
+
+describe('updateRoleSettings', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should return error for missing project_id', async () => {
+		const ctx = createMockContext();
+
+		const result = await updateRoleSettings({ role: 'developer' }, ctx);
+
+		expect(result.result).toMatchObject({
+			error: 'project_id is required',
+		});
+	});
+
+	it('should return error for missing role', async () => {
+		const ctx = createMockContext();
+
+		const result = await updateRoleSettings(
+			{ project_id: '123e4567-e89b-12d3-a456-426614174000' },
+			ctx
+		);
+
+		expect(result.result).toMatchObject({
+			error: 'role is required',
+		});
+	});
+
+	it('should update role settings successfully', async () => {
+		mockApiClient.proxy.mockResolvedValue({
+			ok: true,
+			data: { success: true, role: 'validator' },
+		});
+		const ctx = createMockContext();
+
+		const result = await updateRoleSettings(
+			{
+				project_id: '123e4567-e89b-12d3-a456-426614174000',
+				role: 'validator',
+				enabled: true,
+				auto_assign_validation: true,
+			},
+			ctx
+		);
+
+		expect(result.result).toMatchObject({
+			success: true,
+			role: 'validator',
+		});
+		expect(mockApiClient.proxy).toHaveBeenCalledWith(
+			'update_role_settings',
+			expect.objectContaining({
+				project_id: '123e4567-e89b-12d3-a456-426614174000',
+				role: 'validator',
+				enabled: true,
+				auto_assign_validation: true,
+			})
+		);
+	});
+
+	it('should return error from API', async () => {
+		mockApiClient.proxy.mockResolvedValue({
+			ok: false,
+			error: 'Access denied',
+		});
+		const ctx = createMockContext();
+
+		const result = await updateRoleSettings(
+			{
+				project_id: '123e4567-e89b-12d3-a456-426614174000',
+				role: 'validator',
+			},
+			ctx
+		);
+
+		expect(result.result).toMatchObject({
+			error: 'Access denied',
+		});
+	});
+});
+
+// ============================================================================
+// setSessionRole Tests
+// ============================================================================
+
+describe('setSessionRole', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should return error for missing role', async () => {
+		const ctx = createMockContext();
+
+		const result = await setSessionRole({}, ctx);
+
+		expect(result.result).toMatchObject({
+			error: 'role is required',
+		});
+	});
+
+	it('should return error for invalid role', async () => {
+		const ctx = createMockContext();
+
+		const result = await setSessionRole({ role: 'invalid_role' }, ctx);
+
+		expect(result.result).toMatchObject({
+			error: expect.stringContaining('Invalid role: invalid_role'),
+		});
+	});
+
+	it('should set local role when no active session', async () => {
+		const ctx = createMockContext({ sessionId: null });
+
+		const result = await setSessionRole({ role: 'validator' }, ctx);
+
+		expect(result.result).toMatchObject({
+			success: true,
+			role: 'validator',
+			message: expect.stringContaining('Local role set to validator'),
+		});
+	});
+
+	it('should update session role on server when session active', async () => {
+		mockApiClient.proxy.mockResolvedValue({
+			ok: true,
+			data: { success: true, session_id: 'session-123', role: 'deployer' },
+		});
+		const ctx = createMockContext({ sessionId: 'session-123' });
+
+		const result = await setSessionRole({ role: 'deployer' }, ctx);
+
+		expect(result.result).toMatchObject({
+			success: true,
+			session_id: 'session-123',
+			role: 'deployer',
+		});
+		expect(mockApiClient.proxy).toHaveBeenCalledWith(
+			'set_session_role',
+			expect.objectContaining({
+				session_id: 'session-123',
+				role: 'deployer',
+			})
+		);
+	});
+
+	it('should update local state when setting role', async () => {
+		const updateSession = vi.fn();
+		const ctx = createMockContext({ sessionId: null });
+		ctx.updateSession = updateSession;
+
+		await setSessionRole({ role: 'reviewer' }, ctx);
+
+		expect(updateSession).toHaveBeenCalledWith({ currentRole: 'reviewer' });
+	});
+
+	it('should return error from API when updating session', async () => {
+		mockApiClient.proxy.mockResolvedValue({
+			ok: false,
+			error: 'Session not found',
+		});
+		const ctx = createMockContext({ sessionId: 'session-123' });
+
+		const result = await setSessionRole({ role: 'maintainer' }, ctx);
+
+		expect(result.result).toMatchObject({
+			error: 'Session not found',
+		});
+	});
+});
+
+// ============================================================================
+// getAgentsByRole Tests
+// ============================================================================
+
+describe('getAgentsByRole', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('should return error for missing project_id', async () => {
+		const ctx = createMockContext();
+
+		const result = await getAgentsByRole({}, ctx);
+
+		expect(result.result).toMatchObject({
+			error: 'project_id is required',
+		});
+	});
+
+	it('should get agents by role successfully', async () => {
+		const mockAgentsByRole = {
+			developer: [
+				{ session_id: 'session-1', agent_name: 'Edge', status: 'active' },
+			],
+			validator: [],
+			deployer: [],
+			reviewer: [],
+			maintainer: [],
+		};
+		mockApiClient.proxy.mockResolvedValue({
+			ok: true,
+			data: { agents_by_role: mockAgentsByRole, total_active: 1 },
+		});
+		const ctx = createMockContext();
+
+		const result = await getAgentsByRole(
+			{ project_id: '123e4567-e89b-12d3-a456-426614174000' },
+			ctx
+		);
+
+		expect(result.result).toMatchObject({
+			agents_by_role: mockAgentsByRole,
+			total_active: 1,
+		});
+		expect(mockApiClient.proxy).toHaveBeenCalledWith(
+			'get_agents_by_role',
+			{ project_id: '123e4567-e89b-12d3-a456-426614174000' }
+		);
+	});
+
+	it('should return error from API', async () => {
+		mockApiClient.proxy.mockResolvedValue({
+			ok: false,
+			error: 'Project not found',
+		});
+		const ctx = createMockContext();
+
+		const result = await getAgentsByRole(
+			{ project_id: '123e4567-e89b-12d3-a456-426614174000' },
+			ctx
+		);
+
+		expect(result.result).toMatchObject({
+			error: 'Project not found',
+		});
+	});
+});